Documentation
¶
Overview ¶
Package secret is the compiler-enforced containment boundary for key-encryption-key (KEK) material and key-at-rest wrapping, per docs/adr/0007-secret-containment-boundary.md and roadmap/SECRET-CONTAINMENT-PLAN.md.
The boundary IS the point of the package. The raw-KEK source is an UNEXPORTED interface method (kekSource.kek), so no code outside this package can obtain the KEK bytes. Callers receive an opaque *Provider (built via ResolveProvider/FileProvider/EnvProvider) and, from Open, an opaque *Sealed handle; plaintext is reachable only through the scoped Sealed.WithPlaintext escape hatch, which zeroizes on return. Seal/Open reuse the audited PSCA envelope in internal/ca (AES-256-GCM + PBKDF2-SHA256, random salt + nonce per call) — no new primitive is introduced.
This package deliberately wires into NOTHING in this PR: it ships alongside the existing package-main kek.go helpers, with its own tests, and later PRs migrate each consumer (cluster CA, DP node, CDR client, backup/restore, diagnostics) onto it before the package-main byte-returning API is removed. This is the same land-the-foundation-first pattern kek.go itself used in CA-3 PR1.
Index ¶
Constants ¶
const EnvKEKName = "CULVERT_KEK"
EnvKEKName is the default environment variable carrying a hex-encoded KEK.
const KEKLen = 32
KEKLen is the size of a key-encryption key in bytes (256-bit). The KEK is fed to the PSCA envelope's PBKDF2 step as the passphrase input.
Variables ¶
var ErrKEKMissing = errors.New("secret: required key-encryption key is missing")
ErrKEKMissing is returned when a provider requires externally-supplied unlock material that is absent. Callers must fail closed.
Functions ¶
func IsEnvelope ¶
IsEnvelope reports whether raw on-disk bytes are a PSCA envelope (the encrypted form produced by Seal). Mirrors the Root-CA / cluster-CA detector.
func Seal ¶
Seal encrypts plaintext under the provider's KEK using the PSCA envelope (AES-256-GCM + PBKDF2-SHA256, random salt + nonce per call).
func SealToFile ¶
SealToFile encrypts plaintext under p and writes the envelope to path with 0600 permissions, atomically (fileutil.AtomicWrite).
func ValidateProvider ¶
ValidateProvider reports whether the provider can supply a KEK, WITHOUT returning any bytes. Use for availability / diagnostics checks that must not surface key material.
Types ¶
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider is an opaque handle to KEK material. It exposes NO exported method that returns the KEK. Construct via ResolveProvider/FileProvider/EnvProvider.
func EnvProvider ¶
EnvProvider returns an opaque Provider reading a hex KEK from the given env var (model C). An empty name defaults to EnvKEKName.
func FileProvider ¶
FileProvider returns an opaque Provider backed by the KEK file at path (model B), auto-generated 0600 on first use.
func ResolveProvider ¶
ResolveProvider selects a provider deterministically: if the env var (envName, default CULVERT_KEK) is set and non-empty, the env provider (model C) is used; otherwise the file provider (model B) backed by filePath is used, which auto-generates the KEK file on first use. It performs no I/O itself; the returned provider reads its source lazily on the first KEK use.
func (Provider) Format ¶
Format redacts the Provider under all fmt verbs so an accidental %v/%+v/%#v never reflects its internal source (KEK file path, env var name). Use Name() for intentional, non-secret provider identification in logs.
type Sealed ¶
type Sealed struct {
// contains filtered or unexported fields
}
Sealed is an opaque handle to plaintext secret bytes. It has no exported byte accessor; reach the plaintext only via WithPlaintext. Its Format/String/ GoString methods below are REDACTING (not accessors): they exist precisely so fmt can never reflect the backing buffer.
func Open ¶
Open decrypts a PSCA envelope produced by Seal and returns an opaque handle. It fails closed on bad magic, unsupported version, a malformed header, a wrong KEK, or a corrupted ciphertext/tag — none of which disclose key material.
func OpenFile ¶
OpenFile reads an envelope previously written by SealToFile and returns an opaque handle. Read or decrypt failures fail closed; no key material is included in the returned error.
func OpenOrPlaintext ¶
OpenOrPlaintext returns an opaque handle for raw on-disk key bytes following the content-driven at-rest contract shared by every key-at-rest consumer: if the bytes are a PSCA envelope it decrypts them (fail closed on missing/wrong KEK or corruption); otherwise the plaintext is wrapped unchanged. The bool reports whether the input was encrypted. Returning a Sealed for BOTH branches means callers never hold raw key bytes directly — they reach the plaintext only through the scoped, zeroize-on-return WithPlaintext.
func (*Sealed) Destroy ¶
func (s *Sealed) Destroy()
Destroy zeroizes the plaintext buffer. Safe to call more than once.
func (Sealed) Format ¶
Format implements fmt.Formatter so EVERY verb (%v, %+v, %#v, %s, %x, %d, …) prints a constant redaction instead of reflecting the plaintext buffer. fmt consults Formatter before Stringer/GoStringer, so this single method closes every verb. Value receiver so both Sealed and *Sealed are covered even when passed by value (fmt cannot take the address of a value operand).
func (Sealed) String ¶
String redacts for explicit Stringer consumers (belt and suspenders alongside Format).
func (*Sealed) WithPlaintext ¶
WithPlaintext runs fn with the plaintext, then zeroizes the buffer. The []byte passed to fn is invalid once fn returns; fn MUST NOT retain it. A Sealed is single-use: a second call after the buffer is zeroized returns an error.
Source Files