Documentation
¶
Overview ¶
Package encryption provides bounded, versioned AES-256-GCM envelopes using Go's random-nonce AEAD. Keys are explicit application configuration; the package never generates a replacement for a missing decryption key. Bind each value to its purpose and owning record through Context. It does not provide streaming encryption, key custody or a distributed key-usage counter.
Index ¶
- Constants
- func EnvelopePrefix(id KeyID) (string, error)
- type Ciphertext
- type Context
- type Key
- type KeyID
- type Keyring
- func (r *Keyring) ActiveID() KeyID
- func (r *Keyring) Decrypt(ctx context.Context, binding Context, ciphertext Ciphertext) (secret.String, error)
- func (r *Keyring) Encrypt(ctx context.Context, binding Context, plaintext secret.String) (Ciphertext, error)
- func (Keyring) Format(s fmt.State, _ rune)
- func (Keyring) LogValue() slog.Value
- func (Keyring) MarshalJSON() ([]byte, error)
- func (r *Keyring) Reencrypt(ctx context.Context, binding Context, ciphertext Ciphertext) (Ciphertext, error)
- func (r *Keyring) Validate() error
- type Purpose
Constants ¶
const MaxBindingBytes = 8192
const MaxKeys = 32
const MaxPlaintextBytes = 1 << 20
Variables ¶
This section is empty.
Functions ¶
func EnvelopePrefix ¶
EnvelopePrefix returns the text every envelope encrypted under id starts with. Storage adapters use it to select records that still use another key during rotation; it is not secret and never authenticates anything.
Types ¶
type Ciphertext ¶
type Ciphertext struct {
// contains filtered or unexported fields
}
Ciphertext is a bounded, canonical versioned envelope. Parsing validates its structure only; authentication happens in Keyring.Decrypt. Encoded is the explicit persistence boundary. Ordinary formatting and JSON redact it.
func ParseCiphertext ¶
func ParseCiphertext(encoded string) (Ciphertext, error)
ParseCiphertext validates the version, key identifier, canonical base64 encoding, and size of a ciphertext envelope.
func (Ciphertext) Encoded ¶
func (c Ciphertext) Encoded() string
Encoded returns the encoded ciphertext envelope.
func (Ciphertext) Format ¶
func (Ciphertext) Format(s fmt.State, _ rune)
Format writes the redaction marker instead of ciphertext.
func (Ciphertext) IsZero ¶
func (c Ciphertext) IsZero() bool
IsZero reports whether the ciphertext is uninitialized.
func (Ciphertext) KeyID ¶
func (c Ciphertext) KeyID() KeyID
KeyID returns the envelope's key identifier.
func (Ciphertext) LogValue ¶
func (Ciphertext) LogValue() slog.Value
LogValue returns the redaction marker for logging.
func (Ciphertext) MarshalJSON ¶
func (Ciphertext) MarshalJSON() ([]byte, error)
MarshalJSON encodes the redaction marker instead of ciphertext.
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context authenticates a purpose and exact owning-record binding alongside an envelope. It is not stored in the envelope and must be reconstructed from trusted record identity at decryption. Include tenant and record generation when relevant. Empty bindings are rejected.
func NewContext ¶
NewContext constructs a context from a semantic purpose and a nonempty, bounded binding.
func (Context) MarshalJSON ¶
MarshalJSON encodes the redaction marker instead of context data.
type Key ¶
type Key struct {
// contains filtered or unexported fields
}
Key owns one immutable AES-256 key and a local encryption budget shared by copies and keyrings. Loading the same material again or on another process creates a separate counter: operators must rotate before aggregate use across all instances/restarts exceeds 2^32 encryptions with the same material.
func GenerateKey ¶
GenerateKey creates a key for explicit installation in a secret store. Persist its Secret before encrypting durable data; do not generate keys at each boot.
func ParseKey ¶
ParseKey accepts exactly 32 bytes encoded as canonical unpadded base64url. It performs no I/O and never logs or includes key material in errors.
func (Key) MarshalJSON ¶
MarshalJSON encodes the redaction marker instead of key material.
type KeyID ¶
type KeyID string
KeyID is a non-secret stable name persisted in encrypted envelopes. Never change the material assigned to an existing ID.
type Keyring ¶
type Keyring struct {
// contains filtered or unexported fields
}
Keyring encrypts with one active key and decrypts with its retained keys. It is immutable and safe for concurrent use. Retain old keys until every record has been re-encrypted; unknown IDs never fall back to the active key.
func NewKeyring ¶
NewKeyring constructs a bounded keyring, rejecting duplicate identifiers or key material and a missing active key.
func (*Keyring) ActiveID ¶
ActiveID returns the active key identifier, or an empty identifier for an uninitialized keyring.
func (*Keyring) Decrypt ¶
func (r *Keyring) Decrypt(ctx context.Context, binding Context, ciphertext Ciphertext) (secret.String, error)
Decrypt returns no plaintext on any failure. Missing keys and failed authentication share one error. It never accepts legacy or unauthenticated formats, retries other keys, or silently replaces a missing key.
func (*Keyring) Encrypt ¶
func (r *Keyring) Encrypt(ctx context.Context, binding Context, plaintext secret.String) (Ciphertext, error)
Encrypt owns its output and generates its nonce in Go's standard AEAD. Context checks bound entry/exit; the bounded local cipher operation is not preemptible. An admitted encryption consumes budget even if cancellation discards output.
func (Keyring) MarshalJSON ¶
MarshalJSON encodes the redaction marker instead of keyring contents.
func (*Keyring) Reencrypt ¶
func (r *Keyring) Reencrypt(ctx context.Context, binding Context, ciphertext Ciphertext) (Ciphertext, error)
Reencrypt authenticates with the retained source key and creates a fresh envelope using the active key, preserving the exact context and plaintext. Callers own atomic record replacement; this method does no persistence.
Source Files