Documentation
¶
Overview ¶
Package securecookie encodes and decodes cookie values with HMAC-SHA256 signing and optional AES-GCM encryption using Go standard library crypto only.
ref: gorilla/securecookie — HMAC+AES codec pattern ref: gofiber/fiber — stdlib-only cookie security approach
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrHashKeyTooShort = errcode.New(errcode.KindInvalid, errcode.ErrSecureCookieHashKeyTooShort, "securecookie: hashKey must be at least 32 bytes") ErrInvalidBlockKey = errcode.New(errcode.KindInvalid, errcode.ErrSecureCookieInvalidBlockKey, "securecookie: blockKey must be 16, 24, or 32 bytes (or nil)") ErrEncodingTooShort = errcode.New(errcode.KindInvalid, errcode.ErrSecureCookieEncodingTooShort, "securecookie: encoded value too short") ErrHMACInvalid = errcode.New(errcode.KindInvalid, errcode.ErrSecureCookieHMACInvalid, "securecookie: HMAC verification failed") ErrExpired = errcode.New(errcode.KindInvalid, errcode.ErrSecureCookieExpired, "securecookie: cookie has expired") ErrDecryptFailed = errcode.New(errcode.KindInvalid, errcode.ErrSecureCookieDecryptFailed, "securecookie: decryption failed") ErrClockRequired = errcode.New(errcode.KindInvalid, errcode.ErrValidationFailed, "securecookie: clock is required (nil or typed-nil rejected)") ErrMaxAgeRequired = errcode.New(errcode.KindInvalid, errcode.ErrValidationFailed, "securecookie: MaxAge must be greater than zero") )
Functions ¶
This section is empty.
Types ¶
type Clock ¶
Clock abstracts the wall-clock reads this package needs to time-stamp cookies and check expiry. It is intentionally local: pkg/ may not import kernel/, so SecureCookie defines the minimal Now() interface that any kernel/clock.Clock satisfies structurally. Callers in higher layers pass their injected clock.Clock through Config.
type Config ¶
type Config struct {
// HashKey is the HMAC-SHA256 signing key. It must be at least 32 bytes.
HashKey []byte
// BlockKey optionally enables AES-GCM encryption. nil means signing only;
// non-nil values must be 16, 24, or 32 bytes.
BlockKey []byte
// Clock is required for timestamps and expiry checks.
Clock Clock
// MaxAge is required and must be greater than zero.
MaxAge int
}
Config contains all required SecureCookie construction inputs.
type SecureCookie ¶
type SecureCookie struct {
// contains filtered or unexported fields
}
SecureCookie encodes and decodes cookie values with HMAC-SHA256 signing and optional AES-GCM encryption.
func New ¶
func New(cfg Config) (*SecureCookie, error)
New creates a SecureCookie from cfg. Returns ErrClockRequired if cfg.Clock is nil or a typed-nil (interface wrapping a nil pointer) — making this the single, error-style fail-fast point for clock injection (no panic anywhere in the package).
HashKey is required (min 32 bytes). BlockKey may be nil (signing only) or 16/24/32 bytes (AES-128/192/256-GCM). Clock is required: pass the caller's injected clock.Clock at the composition root, or a clockmock.FakeClock in tests. MaxAge is required and must be greater than zero.
func (*SecureCookie) Decode ¶
func (sc *SecureCookie) Decode(name, encoded string) ([]byte, error)
Decode verifies signature, checks freshness, decrypts, and returns the original value.
func (*SecureCookie) Encode ¶
func (sc *SecureCookie) Encode(name string, value []byte) (string, error)
Encode signs (and optionally encrypts) value, returning a base64url string.
Format: base64url( timestamp(8) | [nonce(12) | ciphertext(N)] or payload(N) | hmac(32) ) HMAC input: len(name)(4) | name | timestamp | nonce | payload.
Source Files