Documentation
¶
Overview ¶
Package encryption defines interfaces and types for field-level encryption in event sourcing. Providers implement the Provider interface to support envelope encryption with various key management systems (local, AWS KMS, HashiCorp Vault).
Index ¶
- Variables
- func AESGCMDecrypt(key, ciphertext, aad []byte) ([]byte, error)
- func AESGCMEncrypt(key, plaintext, aad []byte) ([]byte, error)
- func ClearBytes(b []byte)
- func IsRevoked(p Provider, keyID string) (bool, error)
- func Revoke(p Provider, keyID string) error
- func SoftRevoke(p Provider, keyID string, graceWindow time.Duration) error
- func Unrevoke(p Provider, keyID string) error
- type DataKey
- type EncryptionError
- type KeyNotFoundError
- type KeyRevokedError
- type Provider
- type RecoverableRevocable
- type Revocable
- type RevocationState
- type StatefulRevocable
Constants ¶
This section is empty.
Variables ¶
var ( // ErrEncryptionFailed indicates a field encryption operation failed. ErrEncryptionFailed = errors.New("mink: encryption failed") // ErrDecryptionFailed indicates a field decryption operation failed. ErrDecryptionFailed = errors.New("mink: decryption failed") // ErrKeyNotFound indicates the requested encryption key does not exist. ErrKeyNotFound = errors.New("mink: encryption key not found") // ErrKeyRevoked indicates the encryption key has been revoked (crypto-shredding). ErrKeyRevoked = errors.New("mink: encryption key revoked") // ErrRevocationUnsupported indicates the configured provider does not implement // Revocable, so crypto-shredding (key revocation) is not available. ErrRevocationUnsupported = errors.New("mink: key revocation unsupported by provider") // ErrProviderClosed indicates the encryption provider has been closed. ErrProviderClosed = errors.New("mink: encryption provider closed") )
Sentinel errors for encryption operations.
Functions ¶
func AESGCMDecrypt ¶
AESGCMDecrypt decrypts ciphertext produced by AESGCMEncrypt. The aad parameter must match the value used during encryption.
func AESGCMEncrypt ¶
AESGCMEncrypt encrypts plaintext using AES-256-GCM with additional authenticated data. The aad parameter binds the ciphertext to its context (e.g., field path, key ID), preventing ciphertext from being moved between contexts undetected. Output format: nonce (12 bytes) || ciphertext+tag
func ClearBytes ¶
func ClearBytes(b []byte)
ClearBytes zeroes out a byte slice to prevent key material from lingering in memory.
func IsRevoked ¶ added in v1.1.3
IsRevoked reports whether keyID is revoked via p, returning ErrRevocationUnsupported when p does not implement Revocable.
func Revoke ¶ added in v1.1.3
Revoke crypto-shreds keyID via p when p implements Revocable, otherwise it returns ErrRevocationUnsupported. It is the detection entry point the erasure machinery uses so callers need not type-assert the provider themselves.
func SoftRevoke ¶ added in v1.1.3
SoftRevoke soft-revokes keyID via p when p implements RecoverableRevocable, otherwise it returns ErrRevocationUnsupported — so a caller relying on a grace window is told explicitly rather than silently falling through to a hard revoke.
Types ¶
type DataKey ¶
type DataKey struct {
// Plaintext is the 32-byte AES key used for field encryption.
// Must be zeroed after use via ClearBytes.
Plaintext []byte
// Ciphertext is the encrypted form of the DEK, safe to persist.
Ciphertext []byte
// KeyID is the master key that encrypted this DEK.
KeyID string
}
DataKey holds the plaintext and ciphertext forms of a data encryption key (DEK). The plaintext is used for local AES-256-GCM encryption and must NEVER be persisted. The ciphertext is safe to store in event metadata.
type EncryptionError ¶
type EncryptionError struct {
Operation string // "encrypt" or "decrypt"
KeyID string
Field string
Cause error
}
EncryptionError provides detailed information about an encryption or decryption failure.
func NewDecryptionError ¶
func NewDecryptionError(keyID, field string, cause error) *EncryptionError
NewDecryptionError creates a new EncryptionError for a decrypt operation.
func NewEncryptionError ¶
func NewEncryptionError(keyID, field string, cause error) *EncryptionError
NewEncryptionError creates a new EncryptionError for an encrypt operation.
func (*EncryptionError) Error ¶
func (e *EncryptionError) Error() string
Error returns the error message.
func (*EncryptionError) Is ¶
func (e *EncryptionError) Is(target error) bool
Is reports whether this error matches the target error.
func (*EncryptionError) Unwrap ¶
func (e *EncryptionError) Unwrap() error
Unwrap returns the underlying cause for errors.Unwrap().
type KeyNotFoundError ¶
type KeyNotFoundError struct {
KeyID string
}
KeyNotFoundError provides detailed information about a missing encryption key.
func NewKeyNotFoundError ¶
func NewKeyNotFoundError(keyID string) *KeyNotFoundError
NewKeyNotFoundError creates a new KeyNotFoundError.
func (*KeyNotFoundError) Error ¶
func (e *KeyNotFoundError) Error() string
Error returns the error message.
func (*KeyNotFoundError) Is ¶
func (e *KeyNotFoundError) Is(target error) bool
Is reports whether this error matches the target error.
func (*KeyNotFoundError) Unwrap ¶
func (e *KeyNotFoundError) Unwrap() error
Unwrap returns the underlying error for errors.Unwrap().
type KeyRevokedError ¶
type KeyRevokedError struct {
KeyID string
}
KeyRevokedError provides detailed information about a revoked encryption key.
func NewKeyRevokedError ¶
func NewKeyRevokedError(keyID string) *KeyRevokedError
NewKeyRevokedError creates a new KeyRevokedError.
func (*KeyRevokedError) Error ¶
func (e *KeyRevokedError) Error() string
Error returns the error message.
func (*KeyRevokedError) Is ¶
func (e *KeyRevokedError) Is(target error) bool
Is reports whether this error matches the target error.
func (*KeyRevokedError) Unwrap ¶
func (e *KeyRevokedError) Unwrap() error
Unwrap returns the underlying error for errors.Unwrap().
type Provider ¶
type Provider interface {
// Encrypt encrypts plaintext using the specified master key.
Encrypt(ctx context.Context, keyID string, plaintext []byte) (ciphertext []byte, err error)
// Decrypt decrypts ciphertext using the specified master key.
Decrypt(ctx context.Context, keyID string, ciphertext []byte) (plaintext []byte, err error)
// GenerateDataKey creates a new data encryption key (DEK) protected by the master key.
// The returned DataKey contains both the plaintext DEK (for immediate use) and the
// encrypted DEK (for storage in event metadata). The plaintext must be zeroed after use.
GenerateDataKey(ctx context.Context, keyID string) (*DataKey, error)
// DecryptDataKey decrypts a previously encrypted DEK using the specified master key.
// Returns the plaintext DEK for use in decrypting event fields.
DecryptDataKey(ctx context.Context, keyID string, encryptedKey []byte) ([]byte, error)
// Close releases any resources held by the provider.
Close() error
}
Provider abstracts crypto operations for field-level encryption. Implementations must be safe for concurrent use.
type RecoverableRevocable ¶ added in v1.1.3
type RecoverableRevocable interface {
Revocable
// SoftRevokeKey blocks decryption under keyID but allows UnrevokeKey to restore
// it until graceWindow elapses.
SoftRevokeKey(keyID string, graceWindow time.Duration) error
// UnrevokeKey restores a soft-revoked key, if still within its grace window.
UnrevokeKey(keyID string) error
}
RecoverableRevocable is an OPTIONAL extension of Revocable supporting a grace window: SoftRevokeKey blocks decryption but can be undone with UnrevokeKey until the window elapses, after which the revocation becomes a permanent crypto-shred. This lets an accidental erasure be recovered. Providers MAY implement it.
type Revocable ¶ added in v1.1.3
type Revocable interface {
// RevokeKey permanently revokes keyID (crypto-shredding). It is idempotent:
// revoking an already-revoked key returns nil.
RevokeKey(keyID string) error
// IsRevoked reports whether keyID is currently revoked.
IsRevoked(keyID string) (bool, error)
}
Revocable is an OPTIONAL extension of Provider that supports crypto-shredding: revoking a master key renders all data encrypted under it permanently unrecoverable, which is how go-mink satisfies the GDPR right to erasure (Article 17). Providers MAY implement it; detect support with a type assertion or the Revoke / IsRevoked package helpers.
The signature intentionally mirrors the existing local provider's RevokeKey (no context.Context): revocation is a deliberate administrative operation and the established provider revocation signature is context-free. Providers whose backend needs a context (KMS, Vault) use a background context internally.
type RevocationState ¶ added in v1.1.3
type RevocationState int
RevocationState is the revocation status of a key. It lets callers (notably erasure Verify) distinguish a still-recoverable soft-revocation from a permanent crypto-shred, which IsRevoked (a single bool) cannot.
const ( // NotRevoked means the key is active and its data is recoverable. NotRevoked RevocationState = iota // SoftRevoked means decryption is blocked but the key can still be restored via // UnrevokeKey until its grace window elapses — the data is NOT yet permanently // erased. Verify MUST NOT certify a soft-revoked key as erased. SoftRevoked // Revoked means the key is permanently crypto-shredded; its data is unrecoverable. Revoked )
func GetRevocationState ¶ added in v1.1.3
func GetRevocationState(p Provider, keyID string) (RevocationState, error)
GetRevocationState reports the RevocationState of keyID via p. If p implements StatefulRevocable it is used directly; otherwise it falls back to IsRevoked, mapping true→Revoked and false→NotRevoked (so a provider without soft-revoke can never report SoftRevoked). Returns ErrRevocationUnsupported when p is not even Revocable.
func (RevocationState) String ¶ added in v1.1.3
func (s RevocationState) String() string
String returns the state name.
type StatefulRevocable ¶ added in v1.1.3
type StatefulRevocable interface {
Revocable
RevocationState(keyID string) (RevocationState, error)
}
StatefulRevocable is an OPTIONAL extension that reports the fine-grained RevocationState of a key. Providers with a grace window (RecoverableRevocable) SHOULD implement it so callers can tell SoftRevoked from Revoked. Detect support with GetRevocationState, which falls back to IsRevoked for providers without it.
It embeds Revocable — reporting a revocation state only makes sense for a provider that can revoke — so GetRevocationState's contract holds: a provider that is not Revocable is never treated as stateful, and GetRevocationState reports it as unsupported. This mirrors RecoverableRevocable, which also embeds Revocable.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package kms provides an AWS KMS encryption provider for field-level encryption.
|
Package kms provides an AWS KMS encryption provider for field-level encryption. |
|
Package local provides an in-memory AES-256-GCM encryption provider for testing.
|
Package local provides an in-memory AES-256-GCM encryption provider for testing. |
|
Package providertest provides shared test helpers for encryption.Provider implementations.
|
Package providertest provides shared test helpers for encryption.Provider implementations. |
|
Package vault provides a HashiCorp Vault Transit encryption provider for field-level encryption.
|
Package vault provides a HashiCorp Vault Transit encryption provider for field-level encryption. |