secrets

package
v0.20.0 Latest Latest
Warning

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

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

README

internal/secrets

Overview

AES-256-GCM envelope encryption for stored secret strings. ParseKeys builds a Codec from base64 keys, Encrypt seals under the first key, and Decrypt opens with any listed key and flags reads that used a non-active key as stale. The package is in-memory computation only.

Interface

  • Marker, ReservedPrefix, KeySize — envelope prefix enc:v1:, reserved namespace enc:, and the 32-byte key length [secrets.go:Marker]
  • ErrUnknownKey, ErrDecrypt — sentinel errors for an unlisted key ID and for malformed or failed envelopes [secrets.go:ErrUnknownKey]
  • ParseKeys — parses comma-separated base64 keys into a *Codec; empty input returns nil, nil [secrets.go:ParseKeys]
  • Codec (with exported DecryptOnly flag), Codec.KeyCount, Codec.ActiveKeyID — key set, count, and the 8-hex fingerprint of the encrypt key [secrets.go:Codec]
  • IsEncrypted — reports whether a stored string has the v1 marker [secrets.go:IsEncrypted]
  • Codec.Encrypt, Codec.Decrypt — seal plaintext; open an envelope and return plaintext, a stale flag, and an error [secrets.go:Encrypt]

Invariants

  • ParseKeys rejects empty entries, invalid base64, keys that are not 32 bytes, and duplicates, and names only entry positions in errors [secrets.go:ParseKeys]
  • Encrypt panics on a nil or empty codec, on a DecryptOnly codec, and on plaintext that already has the marker [secrets.go:Encrypt]
  • Encrypt decrypts its own output before returning and panics if the round trip fails [secrets.go:Encrypt]
  • Decrypt panics on a nil or empty codec or on input without the marker; malformed envelopes return ErrDecrypt. A malformed key-ID field is never echoed. A well-formed key ID with a malformed base64 payload is echoed as malformed envelope (key id <id>) [secrets.go:Decrypt]
  • Decrypt returns ErrUnknownKey when no key matches, and sets stale only when a key at index > 0 opened the envelope [secrets.go:Decrypt]
  • validKeyID accepts exactly 8 lowercase hex characters [secrets.go:validKeyID]

Side Effects

  • Encrypt reads crypto/rand for a fresh nonce and panics if the read fails [secrets.go:Encrypt]
  • Failed assertions panic with the prefix secrets assertion failed [secrets.go:assertf]

Verification

  • Run: go test ./internal/secrets/... -tags=openstorage_viewcheck -count=1 -race -timeout=30m
  • Nightly fuzz lane (.github/workflows/fuzz-nightly.yml), one target per run, for FuzzDecrypt and FuzzParseKeys: go test ./internal/secrets -run '^$' -fuzz '^FuzzDecrypt$' -fuzztime 4m -parallel 8 -timeout 30m

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