dataencryption

Documentation

Overview

Package dataencryption provides the MSEH envelope format and DataEncryptionService.

Wire format (Java-compatible):

[4 bytes: 0x4D 0x53 0x45 0x48]  "MSEH" magic
[varint32: proto byte length]
[EncryptionHeader proto bytes]   see dataencryption/v1/encryption_header.proto
[ciphertext bytes]

Index

• Constants
• func HasMagic(b []byte) bool
• func WithContext(ctx context.Context, svc *Service) context.Context
• func WriteHeader(w io.Writer, h Header) error
• type Header
  • func ReadHeader(r io.Reader) (*Header, bool, error)
• type Service
  • func FromContext(ctx context.Context) *Service
  • func New(ctx context.Context, cfg *config.Config) (*Service, error)
  • func (s *Service) AttachmentSigningKeys(ctx context.Context) ([][]byte, error)
  • func (s *Service) Decrypt(ciphertext []byte) ([]byte, error)
  • func (s *Service) DecryptStream(src io.Reader) (io.Reader, error)
  • func (s *Service) Encrypt(plaintext []byte) ([]byte, error)
  • func (s *Service) EncryptStream(dst io.Writer) (io.WriteCloser, error)
  • func (s *Service) IsPrimaryReal() bool

Constants

const (
	// VersionAESGCM is the legacy MSEH format used by byte-slice encryption APIs.
	VersionAESGCM uint32 = 1
	// VersionAESCTR is the streaming MSEH format used for attachment streams.
	VersionAESCTR uint32 = 2
)

Functions

func HasMagic

func HasMagic(b []byte) bool

HasMagic reports whether b starts with the MSEH magic bytes.

func WithContext

func WithContext(ctx context.Context, svc *Service) context.Context

WithContext returns a new context carrying the given Service.

func WriteHeader

func WriteHeader(w io.Writer, h Header) error

WriteHeader encodes h as an MSEH envelope prefix and writes it to w.

Types

type Header

type Header struct {
	Version    uint32
	ProviderID string
	Nonce      []byte
}

Header is the decoded MSEH envelope header.

func ReadHeader

func ReadHeader(r io.Reader) (*Header, bool, error)

ReadHeader reads the MSEH magic + varint + proto fields from r. Returns (header, true, nil) on success, (nil, false, nil) if magic is absent, or (nil, true, err) on a read error after the magic has been confirmed present.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service orchestrates encryption providers. The primary provider is used for new encryptions; all registered providers are available for decryption routing via the MSEH ProviderID field.

func FromContext

func FromContext(ctx context.Context) *Service

FromContext retrieves the Service from the context. Returns nil if none was set.

func New

func New(ctx context.Context, cfg *config.Config) (*Service, error)

New constructs a Service from cfg.EncryptionProviders (comma-separated list). The first named provider becomes the primary (used for encryption).

func (*Service) AttachmentSigningKeys

func (s *Service) AttachmentSigningKeys(ctx context.Context) ([][]byte, error)

AttachmentSigningKeys returns signing keys from the primary provider for attachment download URL HMAC signing. Returns nil when the primary provider does not support signed URLs (e.g. "plain" with no key configured).

func (*Service) Decrypt

func (s *Service) Decrypt(ciphertext []byte) ([]byte, error)

Decrypt routes to the provider named in the MSEH header when present. When "plain" is registered in the provider list, two additional cases are handled:

• Scenario 1 (migration): no MSEH header → return bytes as-is via "plain". Covers data written before encryption was enabled (e.g. providers = "dek,plain"): old rows have no MSEH header and must not be routed to the primary ("dek"), which would fail expecting an envelope.

• Scenario 2 (magic collision): MSEH magic present but header is malformed → return bytes as-is via "plain". Raw plaintext that coincidentally starts with the 4-byte MSEH sentinel is treated as plain data rather than returning an error.

Without "plain" in the list, the primary provider handles header-less data and any header parse failure is a hard error.

func (*Service) DecryptStream

func (s *Service) DecryptStream(src io.Reader) (io.Reader, error)

DecryptStream peeks at the first 4 bytes to detect MSEH magic. If found, reads the full header and routes to the matching provider. The same two "plain" fallback scenarios as Decrypt apply here:

• Scenario 1 (migration): no MSEH magic + "plain" registered → pass stream through.

• Scenario 2 (magic collision): MSEH magic present but header is malformed + "plain" registered → reconstruct the original stream (using the bytes captured by recordingReader during the failed header parse) and pass it through as-is.

func (*Service) Encrypt

func (s *Service) Encrypt(plaintext []byte) ([]byte, error)

Encrypt delegates to the primary provider.

func (*Service) EncryptStream

func (s *Service) EncryptStream(dst io.Writer) (io.WriteCloser, error)

EncryptStream delegates to the primary provider.

func (*Service) IsPrimaryReal

func (s *Service) IsPrimaryReal() bool

IsPrimaryReal returns true when the primary provider performs actual encryption (i.e. is not the "plain" no-op provider).