Documentation
¶
Overview ¶
Package secrets implements optional application-level envelope encryption for secret columns in the metadata store (issue #54): webhook HMAC signing keys and upstream-sync credential passwords.
The envelope is AES-256-GCM with a random 96-bit nonce per value, stored as a text column value of the form
enc:v1:<keyid>:<base64(nonce || ciphertext)>
where <keyid> is the first 8 hex characters of SHA-256(key) — a public fingerprint that lets operators verify rotation progress with plain SQL (`... WHERE secret NOT LIKE 'enc:v1:<keyid>:%'`) and lets decrypt failures name the missing key without exposing material.
Keys come from OPENSTORAGE_SECRETS_KEY: a comma-separated list of base64 32-byte keys. The first key encrypts every write; the rest are decrypt-only, supporting rotation (put the new key first, keep old keys listed until every row has been rewritten). An empty value disables encryption entirely (legacy plaintext behavior).
Marker collision: only stored values carrying the exact v1 marker ("enc:v1:") are treated as envelopes. Write paths additionally reject NEW plaintext secrets starting with ReservedPrefix ("enc:", all versions — meta.ErrReservedSecret) so values written from now on can never be confused with any envelope version; pre-existing plaintext rows that happen to start with "enc:" but are not v1 envelopes keep reading as plaintext (they were legal before this package existed) and are migrated into envelopes by the lazy rewrite once a key is set, which removes the ambiguity permanently. Residual assumption (documented, astronomically unlikely): a legacy plaintext secret shaped exactly like a v1 envelope — "enc:v1:" + 8 hex + ":" + base64 — would fail closed as an unknown-key/corrupt envelope rather than read as plaintext.
Invariant: no function in this package ever includes plaintext, ciphertext, or key material in an error message or log — key ids only.
Index ¶
Constants ¶
const ( // Marker prefixes every v1 envelope. Marker = "enc:v1:" // ReservedPrefix is the stored-value namespace reserved for envelopes // (all versions). Write paths must reject plaintext secrets starting // with it — see the package comment. ReservedPrefix = "enc:" // KeySize is the AES-256 key length in bytes. KeySize = 32 )
Variables ¶
var ( // ErrUnknownKey: the envelope names a key id absent from the configured // list — the operator removed a still-needed key (or points the server // at another deployment's database). ErrUnknownKey = errors.New("value is encrypted with a key not listed in OPENSTORAGE_SECRETS_KEY") // ErrDecrypt: the envelope is malformed or GCM authentication failed — // corrupt row, or a different key with a colliding fingerprint. ErrDecrypt = errors.New("decrypt failed: ciphertext corrupt or key mismatch") )
Sentinel errors; callers match with errors.Is. Both are operational (wrong OPENSTORAGE_SECRETS_KEY for the data at hand), never programming errors.
Functions ¶
func IsEncrypted ¶
IsEncrypted reports whether a stored value is a v1 envelope.
Types ¶
type Codec ¶
type Codec struct {
// DecryptOnly is the OPENSTORAGE_SECRETS_MODE=decrypt-only staging mode
// for first enablement on multi-replica fleets: every listed key
// decrypts, but nothing is encrypted or rewritten, so no envelope is
// written until every replica can already read it. Callers (the meta
// package) must not call Encrypt while it is set.
DecryptOnly bool
// contains filtered or unexported fields
}
Codec encrypts with keys[0] and decrypts with any listed key. A nil *Codec means encryption is disabled.
func ParseKeys ¶
ParseKeys parses the OPENSTORAGE_SECRETS_KEY format: comma-separated base64 (standard, padded) 32-byte keys, first = active. Returns (nil, nil) for an empty value (encryption disabled). Error messages name entry positions, never material.
func (*Codec) ActiveKeyID ¶
ActiveKeyID returns the fingerprint of the encrypt (first) key.
func (*Codec) Decrypt ¶
Decrypt opens a stored envelope. stale=true when a non-active key decrypted it — the caller should rewrite the row under the active key. Errors wrap ErrUnknownKey or ErrDecrypt and carry key ids only.
func (*Codec) Encrypt ¶
Encrypt seals plaintext under the active key and returns the stored envelope. Sealing a value that is already a v1 envelope is always a bug (double encryption); other ReservedPrefix-carrying plaintext is legal here only for migrating legacy rows — write paths reject it for new secrets (meta.ErrReservedSecret) before reaching Encrypt.