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 EncodeHeader(h Header) ([]byte, error)
- func FieldAAD(headerPrefix []byte, domain, identity string) []byte
- func HasMagic(b []byte) bool
- func WithContext(ctx context.Context, svc *Service) context.Context
- func WriteHeader(w io.Writer, h Header) error
- type Header
- type Service
- func (s *Service) AttachmentSigningKeys(ctx context.Context) ([][]byte, error)
- func (s *Service) Decrypt(ciphertext []byte) ([]byte, error)
- func (s *Service) DecryptField(ciphertext []byte, domain, identity string) ([]byte, error)
- func (s *Service) DecryptStream(src io.Reader) (io.Reader, error)
- func (s *Service) Encrypt(plaintext []byte) ([]byte, error)
- func (s *Service) EncryptField(plaintext []byte, domain, identity string) ([]byte, error)
- func (s *Service) EncryptStream(dst io.Writer) (io.WriteCloser, error)
- func (s *Service) IsPrimaryReal() bool
- func (s *Service) PrimaryProviderID() string
- func (s *Service) PrimarySupportsFieldEncryption() bool
Constants ¶
const ( // VersionAESGCM is the legacy MSEH format used by byte-slice encryption APIs. VersionAESGCM uint32 = 1 // VersionAESCTR is the legacy unauthenticated AES-CTR stream format used for attachment streams. VersionAESCTR uint32 = 2 // VersionAttachmentStreamAESGCM is the authenticated record stream format used for attachments. VersionAttachmentStreamAESGCM uint32 = 3 // VersionFieldAESGCM is the authenticated field format using domain/identity AAD. VersionFieldAESGCM uint32 = 4 )
Variables ¶
This section is empty.
Functions ¶
func EncodeHeader ¶ added in v0.0.6
EncodeHeader encodes h as an MSEH envelope prefix.
func FieldAAD ¶ added in v0.0.6
FieldAAD returns the canonical associated data for an MSEH v4 persisted field.
func WithContext ¶
WithContext returns a new context carrying the given Service.
Types ¶
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 ¶
FromContext retrieves the Service from the context. Returns nil if none was set.
func New ¶
New constructs a Service from cfg.EncryptionProviders (comma-separated list). The first named provider becomes the primary (used for encryption).
func (*Service) AttachmentSigningKeys ¶
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 ¶
Decrypt routes to the provider named in the MSEH header when present. When "plain" is registered in the provider list and legacy plaintext reads are explicitly enabled, one additional case is 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.
Malformed MSEH is always a hard error. It never falls back to plaintext.
func (*Service) DecryptField ¶ added in v0.0.6
DecryptField decrypts a persisted field. MSEH v4 values are authenticated with the supplied domain and identity; legacy MSEH v1 values are readable only when the explicit migration compatibility flag is enabled.
func (*Service) DecryptStream ¶
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 explicit legacy plaintext fallback as Decrypt applies here:
- Scenario 1 (migration): no MSEH magic + "plain" registered → pass stream through.
Malformed MSEH is always a hard error. It never falls back to plaintext.
func (*Service) EncryptField ¶ added in v0.0.6
EncryptField encrypts a persisted field with MSEH v4 domain/identity AAD binding.
func (*Service) EncryptStream ¶
EncryptStream delegates to the primary provider.
func (*Service) IsPrimaryReal ¶
IsPrimaryReal returns true when the primary provider performs actual encryption (i.e. is not the "plain" no-op provider).
func (*Service) PrimaryProviderID ¶ added in v0.0.6
PrimaryProviderID returns the configured primary provider ID.
func (*Service) PrimarySupportsFieldEncryption ¶ added in v0.0.6
PrimarySupportsFieldEncryption reports whether the primary provider can write MSEH v4 persisted-field envelopes with domain/identity AAD.
Source Files