Documentation
¶
Overview ¶
Package tokenseal seals and opens a byte slice as an "enc:v1" envelope (AES-256-GCM, random 96-bit nonce, HKDF-derived record key and key id) for values stored at rest, such as the upstream OAuth records in config.db.
Envelope: enc:v1:<kid>:<base64(nonce[12] || ciphertext || tag[16])>
kid = 16 lower-case hex characters, derived from the configured key AAD = "mcpproxy-oauth-token" 0x00 "v1" 0x00 kid 0x00 bucket 0x00 bucketKey
The AAD binds the version, the key id, the bucket and the bucket key, so an envelope copied under another key or bucket fails authentication.
The package is a leaf: it imports only the standard library (Spec 123, FR-006) and must stay that way so internal/storage can depend on it.
Index ¶
Constants ¶
const MaxPlaintextLen = 1 << 20
MaxPlaintextLen is the largest plaintext Seal accepts. An OAuth record is a few kilobytes of JSON; the bound keeps Seal's buffer sizes from overflowing.
Variables ¶
var ErrContextNUL = errors.New("tokenseal: bucket and bucket key must not contain NUL")
ErrContextNUL is returned by Seal for a bucket or bucket key containing a NUL byte: the AAD is NUL-separated, so such a pair could collide with a different (bucket, key) pair.
var ErrInvalidKey = errors.New("is not a base64-encoded 32-byte key")
ErrInvalidKey is the only error ParseKey returns. Its text is fixed so that no input, path or reference can leak through it.
var ErrPlaintextTooLarge = errors.New("tokenseal: plaintext is larger than 1 MiB")
ErrPlaintextTooLarge is returned by Seal for a plaintext over MaxPlaintextLen.
Functions ¶
This section is empty.
Types ¶
type Key ¶
type Key struct {
// contains filtered or unexported fields
}
Key is a configured sealing key. It has no exported field and never prints key material. A nil *Key means "no key configured".
func ParseKey ¶
ParseKey parses a standard-alphabet base64 string (padding optional, surrounding whitespace ignored) that decodes to exactly 32 bytes.
func (*Key) Open ¶
Open authenticates and decrypts an enc:v1 envelope. A nil key is allowed and yields ReasonNoKey for a well-formed envelope. Every failure is an *OpenError. Open does not accept plaintext values: callers Classify first.
type OpenError ¶
type OpenError struct {
Reason Reason
RowKID string // kid found in the stored value's prefix ("" if none)
KeyKID string // kid of the configured key ("" if none)
}
OpenError is the error Open returns. It carries key ids only, never key material or payload bytes.
type Shape ¶
type Shape int
Shape is the outer form of a stored value.
const ( ShapeMalformed Shape = iota // empty, unknown prefix or damaged enc:v1 header ShapePlaintext // first byte '{' (a JSON object) ShapeSealedV1 // enc:v1:<kid>:<payload> ShapeUnsupported // enc:<other version>:... )
Value shapes returned by Classify.