hmac

hmac

Русский перевод · Module guide

HTTP Message Signatures using standard RFC 9421 Signature-Input and Signature fields and hmac-sha256. HTTP middleware and gRPC interceptors share the same verification core.

Supported components and parameters

The package supports request signatures covering exactly @method and @path, in either order. gRPC uses method POST and its full RPC path. HTTP uses the case-sensitive method and percent-encoded path, preserving escapes. Query, authority, headers, body, responses, other algorithms, and signatures with other covered-component sets are not supported.

created (integer) and keyid (nonempty string) are required. alg, when supplied, must be hmac-sha256; otherwise the verifier's configured algorithm applies. expires, when supplied, is checked. nonce is required when replay protection is enabled. Standard parameter types are validated; a standard string tag can be included. Other signature metadata participates in canonical serialization but has no additional local policy meaning.

The signer emits one sig1 signature with created, keyid, alg, and a cryptographically random nonce. The verifier accepts multiple labels and verifies supported candidates independently. It rejects ambiguous duplicate labels and mismatched label sets. Structured Fields parsing, string escaping, and canonical serialization use github.com/dunglas/httpsfv; MAC generation/comparison use Go's crypto/hmac.

Method/path signatures do not authenticate request content or bind a request to a host. Use TLS, distinct service keys, and application authorization. Do not use these signatures as end-to-end body integrity across intermediaries that can change unsigned content.

HTTP example

verifier, err := hmac.New(
    hmac.WithKeyring(hmac.StaticKeyring{"example-client": secret}),
    hmac.WithNonceStore(hmac.NewMemoryNonceStore()),
)
if err != nil {
    return err
}
handler := verifier.Middleware(applicationHandler)
signer, err := hmac.NewSigner("example-client", secret)
if err != nil {
    return err
}
client := &http.Client{Transport: signer.RoundTripper(http.DefaultTransport)}

secret must come from application secret management; applicationHandler supplies routes. The executable TLS example makes a signed request and reads the authenticated Caller.KeyID in a real handler.

Signer.Sign(method, encodedPath) returns field values. Signer.SignRequest(r) sets/replaces fields after method and URL are finalized. RoundTripper(base) clones requests before signing, preserves the caller's headers, and closes the body if signing fails. A nil base uses http.DefaultTransport.

Verification failure returns HTTP 403 with a generic body. The response does not include a WWW-Authenticate challenge. HTTPBinding(method, encodedPath) defines exact route policies; method case and encoded path matter.

gRPC integration

serverOptions := []grpc.ServerOption{
    grpc.ChainUnaryInterceptor(verifier.UnaryServerInterceptor()),
    grpc.ChainStreamInterceptor(verifier.StreamServerInterceptor()),
}
clientOptions := []grpc.DialOption{
    grpc.WithChainUnaryInterceptor(signer.UnaryClientInterceptor()),
    grpc.WithChainStreamInterceptor(signer.StreamClientInterceptor()),
}

Pass these options to grpc-go or the chassis adapters alongside explicit TLS credentials. Outgoing interceptors replace existing signature metadata and preserve unrelated metadata. Incoming failures return Unauthenticated. Stream signatures authenticate stream opening, not individual messages. Retrying a request must produce a new signature/nonce; do not reuse a signed context with replay protection.

Policies, keys, and replay

Required() is the default and the zero-value Policy. Skip() accepts unsigned calls without adding a caller. WithPolicies(Policies{binding: policy}) merges overrides. Health/reflection methods use the same policies; configure unsigned access explicitly when needed. With Skip() as the default and no required overrides, a keyring is unnecessary.

StaticKeyring maps key IDs to secrets. Configure it before serving and treat the map and byte slices as immutable; use an application-owned synchronized Keyring for live rotation. SharedSecretKeyring authenticates possession of one shared secret, not distinct caller identities: any holder can choose any nonempty key ID. Use separate secrets when identity matters. Empty secrets are rejected. NewSigner copies its secret.

Without a NonceStore, a captured signature can be replayed throughout its timestamp window. MemoryNonceStore (also usable at zero value) atomically records nonces for one process, scoped internally to key ID. A nonce is stored only after successful MAC validation and retained through the remaining accepted lifetime. Lazy cleanup avoids a background worker. Multiple replicas or restarts need an application-provided shared store. Shared stores must perform atomic check-and-insert and fail closed on storage failure using the interface's boolean result.

FromContext(ctx) returns (Caller, bool). Caller contains KeyID; authorization beyond key possession remains application-owned. ErrMissingSignature, ErrUnknownKey, ErrStaleTimestamp, ErrBadSignature, and ErrReplay describe internal verification failures; adapters expose generic failures.

Tests and references

Tests and protocol tests cover HTTP/gRPC/stream adapters, policy defaults, escaping, signature labels, timestamp overflow/expiry, key/nonce isolation, concurrent replay detection, and an RFC 4231 HMAC vector. FuzzSignatureFields exercises malformed fields. See RFC 9421, Structured Fields RFC 9651, and RFC 4231.