Documentation
¶
Overview ¶
Package crypto provides the KeyProvider abstraction and implementations for encrypting sensitive values at the repository boundary.
Design:
- KeyProvider abstracts any KMS backend (LocalAES, VaultTransit, AWS-KMS, ...).
- KeyHandle represents a specific key version, provides Encrypt/Decrypt.
- ValueTransformer is a thin caller-facing wrapper over KeyProvider.
Interfaces (KeyProvider, KeyHandle, ValueTransformer, CurrentKeyIDProvider) are defined in kernel/crypto and re-exported here via type aliases so that existing import paths continue to work without modification.
ref: kubernetes/kubernetes staging/src/k8s.io/apiserver/pkg/storage/value/transformer.go@master ref: hashicorp/vault vault/barrier_aes_gcm.go@main:L1199-L1233 ref: PR#200 R1a kernel/lifecycle type-alias bridge pattern
Index ¶
Constants ¶
const ( // LocalAESCurrentKeyID is the version label for the current master key. LocalAESCurrentKeyID = "local-aes-v1" // LocalAESPreviousKeyID is the version label for the previous master key. LocalAESPreviousKeyID = "local-aes-v0" )
Key ID constants for the LocalAES two-version keyring.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CurrentKeyIDProvider ¶
type CurrentKeyIDProvider = kcrypto.CurrentKeyIDProvider
CurrentKeyIDProvider is a type alias for the kernel CurrentKeyIDProvider interface. The authoritative definition lives in kernel/crypto.
See ValueTransformer alias comment for guidance on import choices.
type EncryptResult ¶
type EncryptResult = kcrypto.EncryptResult
EncryptResult is a type alias for the kernel encryption result contract. The authoritative definition lives in kernel/crypto.
type KeyHandle ¶
KeyHandle is a type alias for the kernel KeyHandle interface. The authoritative definition lives in kernel/crypto.
See KeyProvider alias comment for guidance on import choices.
type KeyProvider ¶
type KeyProvider = kcrypto.KeyProvider
KeyProvider is a type alias for the kernel KeyProvider interface. The authoritative definition lives in kernel/crypto.
This is not a migration shim — the alias exists so runtime/crypto implementations (LocalAES, VaultTransit, keyProviderTransformer) type-check against the kernel contract without importing kernel/crypto from every local impl file.
Guidance for new consumers: code in cells/ or cmd/ referencing only interfaces SHOULD import kernel/crypto directly and reference kcrypto.KeyProvider (the kernel contract).
type LocalAESKeyProvider ¶
type LocalAESKeyProvider struct {
// contains filtered or unexported fields
}
LocalAESKeyProvider implements KeyProvider using local AES-GCM-256 keys. Suitable for dev/CI; not recommended for production (use `adapters/vault.TransitKeyProvider` instead).
Keys are supplied by the caller as hex/base64-encoded 32-byte strings. Use cmd/corebundle.LoadConfigCoreKeyProvider to read per-cell env variables and pass the result to NewLocalAESKeyProviderFromKeys.
ref: hashicorp/vault sdk/helper/keysutil/policy.go@main:L127 — keyring with current + historical versions.
func NewLocalAESKeyProviderFromKeys ¶
func NewLocalAESKeyProviderFromKeys(currentKey, prevKey string) (*LocalAESKeyProvider, error)
NewLocalAESKeyProviderFromKeys constructs a LocalAESKeyProvider from the supplied hex/base64 encoded 32-byte keys. prevKey may be empty (no previous key in keyring). Both keys must decode to exactly 32 bytes.
currentKey is the active master KEK (required; must be non-empty). prevKey enables decryption of values encrypted with a prior key version (supports rotation); may be empty for single-key mode.
func (*LocalAESKeyProvider) ByID ¶
ByID returns the KeyHandle for the given key ID. Returns ErrKeyNotFound when the ID is absent from the keyring.
func (*LocalAESKeyProvider) Current ¶
func (p *LocalAESKeyProvider) Current(_ context.Context) (KeyHandle, error)
Current returns the active KeyHandle.
func (*LocalAESKeyProvider) Rotate ¶
func (p *LocalAESKeyProvider) Rotate(_ context.Context) (string, error)
Rotate is not supported for LocalAESKeyProvider in production use.
LocalAES key rotation is not persistent: a new in-memory key is lost on restart, causing all previously encrypted values to become unreadable. This method returns ErrNotImplemented so that callers receive an explicit error rather than silently losing data.
Production rotation strategy (S14a):
- Use adapters/vault.TransitKeyProvider.Rotate() which delegates key generation to Vault.
- Vault persists key versions server-side; historical ciphertext remains decryptable via the ciphertext version prefix.
Testing rotation scenarios: use adapters/vault.TransitKeyProvider with a fake VaultClient (see adapters/vault/transit_provider_test.go).
type NoopTransformer ¶
type NoopTransformer struct{}
NoopTransformer implements ValueTransformer with identity (no-op) semantics. Used for sensitive=false config values that do not require encryption. Encrypt returns the plaintext unchanged; Decrypt returns ciphertext unchanged.
func (NoopTransformer) Decrypt ¶
func (NoopTransformer) Decrypt(_ context.Context, ciphertext []byte, _ string, _, _, _ []byte) ([]byte, error)
Decrypt returns ciphertext as-is.
func (NoopTransformer) Encrypt ¶
func (NoopTransformer) Encrypt(_ context.Context, plaintext, _ []byte) (EncryptResult, error)
Encrypt returns plaintext as-is with empty keyID, nonce, and edk.
type ValueTransformer ¶
type ValueTransformer = kcrypto.ValueTransformer
ValueTransformer is a type alias for the kernel ValueTransformer interface. The authoritative definition lives in kernel/crypto.
This is not a migration shim — the alias exists so runtime/crypto implementations (keyProviderTransformer, NoopTransformer) type-check against the kernel contract without importing kernel/crypto from every local impl file.
Guidance for new consumers: code in cells/ or cmd/ referencing only interfaces SHOULD import kernel/crypto directly and reference kcrypto.ValueTransformer (the kernel contract).
func NewValueTransformer ¶
func NewValueTransformer(p KeyProvider) ValueTransformer
NewValueTransformer returns a ValueTransformer backed by the given KeyProvider.
Source Files