secrets

package
v0.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 12, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

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

View Source
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

View Source
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

func IsEncrypted(stored string) bool

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

func ParseKeys(raw string) (*Codec, error)

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

func (c *Codec) ActiveKeyID() string

ActiveKeyID returns the fingerprint of the encrypt (first) key.

func (*Codec) Decrypt

func (c *Codec) Decrypt(stored string) (plaintext string, stale bool, err error)

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

func (c *Codec) Encrypt(plaintext string) string

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.

func (*Codec) KeyCount

func (c *Codec) KeyCount() int

KeyCount returns the number of configured keys.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL