Documentation
¶
Overview ¶
Package cryptoadapter wraps go-jose/v4's parsing/signing option structs and header extraction with strict allowlist enforcement and a constant-time generic error surface. Keeping wire-format specifics (header types, option structs) inside this package limits — but does not eliminate — a future library swap's blast radius; algorithm-identifier types (jose.SignatureAlgorithm, jose.KeyAlgorithm, jose.ContentEncryption) are still referenced directly from the parent jose package.
Index ¶
- Variables
- func CheckExtra(extra map[string]any) error
- func Encrypt(payload []byte, key *rsa.PublicKey, opts *EncryptOptions) (string, error)
- func Sign(payload []byte, key *rsa.PrivateKey, opts *SignOptions) (string, error)
- type DecryptOptions
- type EncryptOptions
- type Header
- type SignOptions
- type VerifyOptions
Constants ¶
This section is empty.
Variables ¶
var ( ErrParseEncrypted = errors.New("cryptoadapter: parse encrypted failed") ErrParseSigned = errors.New("cryptoadapter: parse signed failed") ErrKidMissing = errors.New("cryptoadapter: header missing kid") ErrKidMismatch = errors.New("cryptoadapter: header kid does not match expected") ErrDecryptFailed = errors.New("cryptoadapter: decrypt failed") ErrVerifyFailed = errors.New("cryptoadapter: signature verification failed") ErrSignFailed = errors.New("cryptoadapter: sign failed") ErrEncryptFailed = errors.New("cryptoadapter: encrypt failed") ErrEncrypterCreation = errors.New("cryptoadapter: encrypter creation failed") ErrSignerCreation = errors.New("cryptoadapter: signer creation failed") )
Sentinel errors for the adapter layer; the parent jose package wraps these in *jose.Error with full diagnostic context.
var ( // ErrExtraCollision is returned by Sign/Encrypt when Extra names an adapter-owned or // JOSE-reserved param. ErrExtraCollision = errors.New("cryptoadapter: extra header collides with a reserved param") // ErrExtraAbsent is returned by the typed accessors when the header is not present. ErrExtraAbsent = errors.New("cryptoadapter: extra header absent") // ErrExtraMalformed is returned by the typed accessors when the header has the wrong shape. ErrExtraMalformed = errors.New("cryptoadapter: extra header malformed") // ErrPeekMalformed is returned by PeekProtectedHeader when the input is not a compact // serialization whose first segment is a base64url-encoded JSON object. ErrPeekMalformed = errors.New("cryptoadapter: protected header peek failed") )
Sentinel errors for the extra-header seam and the pre-verify peek.
Functions ¶
func CheckExtra ¶ added in v0.64.0
CheckExtra rejects Extra entries that name an adapter-owned or JOSE-reserved param. Sign and Encrypt run it themselves; the parent jose package also runs it at policy validation time so a bad protected-header map fails at startup rather than per request.
func Sign ¶
func Sign(payload []byte, key *rsa.PrivateKey, opts *SignOptions) (string, error)
Sign produces a compact JWS over payload using the private key.
Types ¶
type DecryptOptions ¶
type DecryptOptions struct {
ExpectedKid string
AllowedKeyAlgs []jose.KeyAlgorithm
AllowedContentEnc []jose.ContentEncryption
}
DecryptOptions controls strict header validation during JWE decrypt.
type EncryptOptions ¶
type EncryptOptions struct {
Kid string
KeyAlg jose.KeyAlgorithm
Enc jose.ContentEncryption
Cty string
Typ string
// Extra is written into the protected header verbatim; same collision rule as SignOptions.
Extra map[string]any
}
EncryptOptions controls JWE production.
type Header ¶
type Header struct {
Kid string
Alg string
Enc string
Cty string
Typ string
// Extra holds every protected-header param the adapter does not own (alg, enc, kid,
// cty, typ are excluded). Values keep go-jose's decoded shapes: numbers are float64,
// arrays are []any — use the typed accessors. From PeekProtectedHeader the contents are
// UNAUTHENTICATED wire bytes until Verify succeeds: never log them by value.
Extra map[string]any
}
Header contains the fields we extract from a parsed JOSE object for diagnostic logging. Never includes plaintext.
func Decrypt ¶
func Decrypt(compact string, key *rsa.PrivateKey, opts *DecryptOptions) ([]byte, Header, error)
Decrypt parses a compact JWE, validates its protected header against the allowlists, and decrypts using the supplied private key.
func PeekProtectedHeader ¶ added in v0.63.0
PeekProtectedHeader decodes segment 0 of a compact JWS/JWE into a Header WITHOUT verifying or decrypting. No key material is touched; callers use it to run header rules (typ, alg, key resolution) before choosing a key for Verify/Decrypt. The returned header is unauthenticated until Verify succeeds.
func Verify ¶
Verify parses a compact JWS, validates the protected header, and verifies the signature using the supplied public key. Reads the Protected header (signed) rather than the merged Header (which mixes unsigned values).
func (*Header) ExtraInt64 ¶ added in v0.63.0
ExtraInt64 returns the named extra header as an int64. JSON numbers decode as float64, so a non-integral value, a magnitude beyond 2^53 (no longer exact), or a non-number is ErrExtraMalformed; a missing header is ErrExtraAbsent.
func (*Header) ExtraString ¶ added in v0.63.0
ExtraString returns the named extra header when it is present and a string.
type SignOptions ¶
type SignOptions struct {
Kid string
SigAlg jose.SignatureAlgorithm
Cty string
Typ string
// Extra is written into the protected header verbatim. Naming an adapter-owned param
// (alg, enc, kid, cty, typ) or a JOSE-reserved one (crit, b64, zip, jwk, …) is
// ErrExtraCollision, never an overwrite. The map must not be mutated during the call.
Extra map[string]any
}
SignOptions controls JWS production.
type VerifyOptions ¶
type VerifyOptions struct {
ExpectedKid string
AllowedSigAlgs []jose.SignatureAlgorithm
}
VerifyOptions controls strict header validation during JWS verify.
Source Files