Documentation
¶
Overview ¶
Package domain defines core cryptographic domain models for envelope encryption. Implements Master Key → KEK → DEK → Data hierarchy with AESGCM and ChaCha20 support.
Package domain defines core cryptographic domain models for envelope encryption. Implements Master Key → KEK → DEK → Data hierarchy with AESGCM and ChaCha20 support.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrUnsupportedAlgorithm indicates the requested encryption algorithm is not supported. ErrUnsupportedAlgorithm = errors.Wrap(errors.ErrInvalidInput, "unsupported algorithm") // ErrInvalidKeySize indicates the cryptographic key size is invalid (must be 32 bytes). ErrInvalidKeySize = errors.Wrap(errors.ErrInvalidInput, "invalid key size") // ErrDecryptionFailed indicates decryption failed due to wrong key or corrupted data. ErrDecryptionFailed = errors.Wrap(errors.ErrInvalidInput, "decryption failed") // ErrMasterKeysNotSet indicates the MASTER_KEYS environment variable is not configured. ErrMasterKeysNotSet = errors.Wrap(errors.ErrInvalidInput, "MASTER_KEYS not set") // ErrActiveMasterKeyIDNotSet indicates the ACTIVE_MASTER_KEY_ID environment variable is not configured. ErrActiveMasterKeyIDNotSet = errors.Wrap(errors.ErrInvalidInput, "ACTIVE_MASTER_KEY_ID not set") // ErrInvalidMasterKeysFormat indicates the MASTER_KEYS format is invalid. ErrInvalidMasterKeysFormat = errors.Wrap(errors.ErrInvalidInput, "invalid MASTER_KEYS format") // ErrInvalidMasterKeyBase64 indicates a master key is not valid base64. ErrInvalidMasterKeyBase64 = errors.Wrap(errors.ErrInvalidInput, "invalid master key base64") // ErrActiveMasterKeyNotFound indicates the active master key ID was not found in the keychain. ErrActiveMasterKeyNotFound = errors.Wrap(errors.ErrInvalidInput, "active master key not found") // ErrMasterKeyNotFound indicates a master key with the specified ID was not found. ErrMasterKeyNotFound = errors.Wrap(errors.ErrNotFound, "master key not found") // ErrDekNotFound indicates a DEK with the specified ID was not found. ErrDekNotFound = errors.Wrap(errors.ErrNotFound, "dek not found") // ErrKekNotFound indicates a KEK with the specified ID was not found. ErrKekNotFound = errors.Wrap(errors.ErrNotFound, "kek not found") // ErrKMSProviderNotSet indicates the KMS_PROVIDER environment variable is set but KMS_KEY_URI is not. ErrKMSProviderNotSet = errors.Wrap( errors.ErrInvalidInput, "KMS_PROVIDER is set but KMS_KEY_URI is not configured", ) // ErrKMSKeyURINotSet indicates the KMS_KEY_URI environment variable is set but KMS_PROVIDER is not. ErrKMSKeyURINotSet = errors.Wrap( errors.ErrInvalidInput, "KMS_KEY_URI is set but KMS_PROVIDER is not configured", ) // ErrKMSDecryptionFailed indicates KMS decryption of master keys failed. ErrKMSDecryptionFailed = errors.Wrap(errors.ErrInvalidInput, "KMS decryption failed") // ErrKMSOpenKeeperFailed indicates opening KMS keeper failed. ErrKMSOpenKeeperFailed = errors.Wrap(errors.ErrInvalidInput, "failed to open KMS keeper") )
Cryptographic operation errors.
Functions ¶
Types ¶
type Algorithm ¶
type Algorithm string
Algorithm represents the cryptographic algorithm used for encryption. Supported algorithms provide AEAD (Authenticated Encryption with Associated Data).
type Dek ¶
type Dek struct {
ID uuid.UUID // Unique identifier (UUIDv7)
KekID uuid.UUID // Reference to the KEK used to encrypt this DEK
Algorithm Algorithm // Encryption algorithm (AESGCM or ChaCha20)
EncryptedKey []byte // The DEK encrypted with the KEK
Nonce []byte // Unique nonce for encrypting the DEK
CreatedAt time.Time
}
Dek represents a Data Encryption Key used to encrypt application data. Encrypted with a KEK and stored alongside encrypted data. The plaintext DEK is never persisted and should be zeroed from memory immediately after use.
type KMSKeeper ¶ added in v0.6.0
type KMSKeeper interface {
// Decrypt decrypts ciphertext using the KMS key.
Decrypt(ctx context.Context, ciphertext []byte) ([]byte, error)
// Close releases resources held by the keeper.
Close() error
}
KMSKeeper defines the interface for KMS decrypt operations.
type KMSService ¶ added in v0.6.0
type KMSService interface {
// OpenKeeper opens a secrets.Keeper for the configured KMS provider.
OpenKeeper(ctx context.Context, keyURI string) (KMSKeeper, error)
}
KMSService defines the interface for KMS operations required by LoadMasterKeyChain. This interface is implemented by crypto/service.KMSService.
type Kek ¶
type Kek struct {
ID uuid.UUID // Unique identifier (UUIDv7)
MasterKeyID string // ID of the master key used to encrypt this KEK
Algorithm Algorithm // Encryption algorithm (AESGCM or ChaCha20)
EncryptedKey []byte // The KEK encrypted with the master key
Key []byte // Plaintext KEK (populated after decryption, never persisted)
Nonce []byte // Unique nonce for encrypting the KEK
Version uint // Version number for rotation tracking
CreatedAt time.Time
}
Kek represents a Key Encryption Key used to encrypt Data Encryption Keys. Encrypted with a master key and stored in the database. The Key field contains sensitive plaintext data (populated after decryption) and should be zeroed after use.
type KekChain ¶
type KekChain struct {
// contains filtered or unexported fields
}
KekChain manages a collection of Key Encryption Keys with thread-safe access. The active KEK (highest version) is used for encrypting new DEKs.
func NewKekChain ¶
NewKekChain creates a new KekChain with the first KEK as active. KEKs must be ordered by version descending (newest first) and slice must not be empty.
func (*KekChain) ActiveKekID ¶
ActiveKekID returns the UUID of the currently active Key Encryption Key.
type MasterKey ¶
type MasterKey struct {
ID string // Unique identifier for the master key
Key []byte // The raw 32-byte master key material
}
MasterKey represents a cryptographic master key used to encrypt KEKs. Must be 32 bytes (256 bits) and stored securely in KMS or environment variables. The Key field contains sensitive data and should be zeroed after use.
type MasterKeyChain ¶
type MasterKeyChain struct {
// contains filtered or unexported fields
}
MasterKeyChain manages a collection of master keys with one designated as active. Supports key rotation by maintaining multiple keys simultaneously.
func LoadMasterKeyChain ¶ added in v0.6.0
func LoadMasterKeyChain( ctx context.Context, cfg *config.Config, kmsService KMSService, logger *slog.Logger, ) (*MasterKeyChain, error)
LoadMasterKeyChain loads master keys from environment variables with auto-detection for KMS or legacy mode. If KMS_PROVIDER is set, decrypts keys using KMS. Otherwise, uses plaintext base64-encoded keys. Validates that both KMS_PROVIDER and KMS_KEY_URI are set together or both empty. Returns ErrKMSProviderNotSet, ErrKMSKeyURINotSet, or errors from loadMasterKeyChainFromKMS/LoadMasterKeyChainFromEnv.
func LoadMasterKeyChainFromEnv ¶
func LoadMasterKeyChainFromEnv() (*MasterKeyChain, error)
LoadMasterKeyChainFromEnv loads master keys from MASTER_KEYS and ACTIVE_MASTER_KEY_ID environment variables. Keys must be in format "id:base64key" (comma-separated) and exactly 32 bytes when decoded. Returns ErrMasterKeysNotSet, ErrActiveMasterKeyIDNotSet, ErrInvalidKeySize, or ErrActiveMasterKeyNotFound on failure.
func (*MasterKeyChain) ActiveMasterKeyID ¶
func (m *MasterKeyChain) ActiveMasterKeyID() string
ActiveMasterKeyID returns the ID of the currently active master key.
func (*MasterKeyChain) Close ¶
func (m *MasterKeyChain) Close()
Close securely zeros all master keys from memory, clears the chain, and resets the active ID.
Source Files