Documentation
¶
Overview ¶
Package auth implements Herald's request authentication policy. It provides a replay-resistant HMAC v2/v3 schemes binding method, path, query, timestamp, nonce, service, key id, and the raw body digest. Version 3 also binds the idempotency header. Each valid nonce is consumed once via Redis SET NX EX.
Design goals (see security hardening plan, Phase 4):
- v2 canonical string prevents cross-endpoint / cross-body replay.
- Nonce is verified BEFORE being written so a forged signature cannot burn a victim's nonce, and the nonce is stored under a keyed digest.
- No silent downgrade: a present-but-invalid v2 signature is rejected, never falling back to API key.
- No random default key id; the default must be configured explicitly.
Index ¶
- Constants
- Variables
- func AuthorizeService(policies serviceauth.ServicePolicies, action string) fiber.Handler
- func New(cfg Config) fiber.Handler
- func SignV2(secret string, r CanonicalRequest) string
- func SignV3(secret string, r CanonicalRequest) string
- func TimestampWithinDrift(timestamp string, now time.Time, drift time.Duration) bool
- func VerifiedHMACIdentity(c fiber.Ctx) (service, keyID string, ok bool)
- func VerifyV2(secret, providedSig string, r CanonicalRequest) bool
- func VerifyV3(secret, providedSig string, r CanonicalRequest) bool
- type CanonicalRequest
- type Clock
- type Config
- type KeyProvider
- type Mode
- type NonceStore
Constants ¶
const ( HeaderSignature = "X-Signature" HeaderSignatureVersion = "X-Signature-Version" HeaderTimestamp = "X-Timestamp" HeaderNonce = "X-Nonce" HeaderService = "X-Service" HeaderKeyID = "X-Key-Id" )
Headers used by the v2 scheme.
const ( ModeHMACV2 = serviceauth.ModeHMACV2 ModeAPIKey = serviceauth.ModeAPIKey ModeNone = serviceauth.ModeNone )
const SignatureVersionV2 = "v2"
SignatureVersionV2 is the value of the X-Signature-Version header selecting the v2 scheme.
const SignatureVersionV3 = "v3"
SignatureVersionV3 binds idempotency in addition to the v2 fields.
Variables ¶
ErrNonceStoreUnavailable is returned when the nonce backend fails. Callers must fail closed (reject the request) rather than allowing a replay window.
Functions ¶
func AuthorizeService ¶ added in v1.4.0
func AuthorizeService(policies serviceauth.ServicePolicies, action string) fiber.Handler
AuthorizeService checks an authenticated HMAC identity before a route runs.
func New ¶
New builds the Herald request-auth middleware. It never downgrades from a present-but-invalid HMAC to API-key auth.
func SignV2 ¶
func SignV2(secret string, r CanonicalRequest) string
SignV2 computes the hex HMAC-SHA256 v2 signature for the canonical request using the provided secret.
func SignV3 ¶ added in v1.3.7
func SignV3(secret string, r CanonicalRequest) string
SignV3 signs the header-bound canonical request.
func TimestampWithinDrift ¶
TimestampWithinDrift reports whether the given unix-seconds timestamp string is within +/- drift of now.
func VerifiedHMACIdentity ¶ added in v1.3.13
VerifiedHMACIdentity returns the signed service and the actual key used for verification. The wire key-ID field remains unchanged in the signed request.
func VerifyV2 ¶
func VerifyV2(secret, providedSig string, r CanonicalRequest) bool
VerifyV2 checks the provided signature against the expected v2 signature in constant time.
func VerifyV3 ¶ added in v1.3.7
func VerifyV3(secret, providedSig string, r CanonicalRequest) bool
VerifyV3 compares a v3 signature in constant time.
Types ¶
type CanonicalRequest ¶
type CanonicalRequest struct {
Method string
Path string
Query string
Timestamp string
Nonce string
Service string
KeyID string
IdempotencyKey string
Body []byte
}
CanonicalRequest holds the fields bound into v2/v3 signatures.
func (CanonicalRequest) Canonical ¶
func (r CanonicalRequest) Canonical() string
Canonical returns the canonical string that is signed for v2. The raw body is hashed (never included verbatim) so large bodies do not blow up the signed material and binary bodies are handled safely.
func (CanonicalRequest) CanonicalV3 ¶ added in v1.3.7
func (r CanonicalRequest) CanonicalV3() string
CanonicalV3 binds the idempotency header, including its absence. Hashing the header keeps its bytes out of the newline-delimited field structure.
type Config ¶
type Config struct {
// RequireV3 rejects older HMAC schemes on routes whose side effects depend on idempotency.
RequireV3 bool
// RequireKeyID rejects omitted wire key IDs in v2/v3 requests. Key maps
// enable this so a changed default cannot reinterpret a signed request.
RequireKeyID bool
// ServicePolicies binds a key to its configured service after signature verification.
ServicePolicies serviceauth.ServicePolicies
Mode Mode
// KeyProvider resolves HMAC secrets by key id (required for ModeHMACV2).
KeyProvider KeyProvider
// DefaultKeyID is used when X-Key-Id is absent and RequireKeyID is false;
// empty means X-Key-Id is mandatory.
DefaultKeyID string
// APIKey is the expected API key for ModeAPIKey.
APIKey string
// NonceStore consumes single-use nonces (required for ModeHMACV2).
NonceStore *NonceStore
// MaxDrift bounds accepted timestamp skew (default 60s).
MaxDrift time.Duration
// V1Enabled allows the legacy v1 fallback when a request explicitly selects
// it (no recognized v2/v3 version) AND V1Handler is set.
V1Enabled bool
// V1Handler runs the legacy v1 verification (delegated to middleware-kit).
V1Handler fiber.Handler
// Clock is injectable for tests; defaults to time.Now.
Clock Clock
}
Config configures the Herald auth middleware.
type KeyProvider ¶
KeyProvider returns the shared secret for a key id, or "" if unknown.
func LegacyKeyProvider ¶ added in v1.7.0
func LegacyKeyProvider(next KeyProvider) KeyProvider
LegacyKeyProvider wraps a key provider for the legacy v1 handler, which answers an unknown key ID with its own reason before it looks at the signature. A non-empty key ID the provider does not know resolves to the same per-process secret the v2/v3 path uses for unknown keys. The handler then runs its timestamp check and signature comparison as it does for a configured key, and the request ends as invalid_signature: no caller can hold that secret. An empty key ID is passed through unchanged, so a request that names no key is still answered by the provider's default.
type Mode ¶
type Mode = serviceauth.Mode
Mode selects the request-body authentication scheme.
func ParseModeStrict ¶ added in v1.4.0
ParseModeStrict rejects unrecognized authentication modes.
type NonceStore ¶
type NonceStore struct {
// contains filtered or unexported fields
}
NonceStore consumes single-use nonces via Redis SET NX EX. The nonce is stored under a keyed digest so the raw nonce (which may be attacker-chosen) never lands verbatim in Redis and one service cannot probe another's nonces.
func NewNonceStore ¶
func NewNonceStore(client *redis.Client, prefix string, secret []byte, ttl time.Duration) *NonceStore
NewNonceStore creates a NonceStore. New raises short TTLs to cover the full timestamp acceptance window (2*MaxDrift plus a margin) before using the store.
func (*NonceStore) Consume ¶
Consume atomically claims the nonce. It returns:
- (true, nil) when the nonce was fresh and is now consumed.
- (false, nil) when the nonce was already used (replay).
- (false, ErrNonceStoreUnavailable) on backend failure (fail closed).
IMPORTANT: callers MUST verify the signature BEFORE calling Consume so that an invalid request cannot burn a legitimate nonce.