Module hmac_auth 

HMAC request-signing authentication plugin (hmac-auth).

Port of APISIX’s hmac-auth plugin (3.17). A client proves possession of a shared secret_key by signing a canonical signing string built from the request and sending the base64 signature alongside the access_key that identifies the credential. featherbit recomputes the signature with the matching secret and compares; a mismatch, an unknown key, a stale Date, or a missing required signed header is rejected as 401 HMAC_INVALID through the node’s error port.

Wire format

The signature parameters are read from either:

• an Authorization header of the form Signature keyId="<access_key>",algorithm="hmac-sha256",headers="date @request-target",signature="<base64>" (APISIX 3.17’s format — keyId is the featherbit access_key), or
• the discrete headers X-HMAC-ACCESS-KEY, X-HMAC-ALGORITHM, X-HMAC-SIGNED-HEADERS (space-separated), and X-HMAC-SIGNATURE.

The Date header (RFC 1123 / GMT) carries the timestamp checked against clock_skew.

Signing string

Mirrors APISIX’s generate_signature: the access key on the first line, then one line per signed header, terminated by a trailing newline:

<access_key>\n
<h1>: <value1>\n
<h2>: <value2>\n

The pseudo-header @request-target is rendered as <METHOD> <request-uri> instead of a header lookup. signature = base64(HMAC(secret_key, signing_string)).

Deviations from APISIX

• Consumer credentials use the field names access_key / secret_key (featherbit’s hmac-auth consumer index is keyed on access_key), whereas APISIX names them key_id / secret_key.
• A single algorithm is accepted per node (default hmac-sha256) rather than APISIX’s allowed_algorithms list; the client’s declared algorithm must match it.
• @request-target’s request URI is reconstructed from the parsed path plus a sorted key=value query string (the original query byte order is not retained), so a client signing @request-target must canonicalise its query the same way.
• Only the RFC 1123 (Sun, 06 Nov 1994 08:49:37 GMT) Date format is parsed for clock-skew checks.
• Request-body digest validation (validate_request_body) is not implemented.

Structs

HmacAuthPlugin

Authenticates requests by verifying an HMAC signature over a canonical signing string.

HmacParams 🔒

Signature parameters extracted from the request.

Enums

HmacAlgorithm 🔒

Supported HMAC algorithms.

Constants

HDR_ACCESS_KEY 🔒

The X-HMAC-* header names (lowercased) used as the alternative to the Authorization: Signature ... presentation.

HDR_ALGORITHM 🔒

HDR_SIGNATURE 🔒

HDR_SIGNED_HEADERS 🔒

Functions

now 🔒

Current unix timestamp in seconds.

parse_http_date 🔒

Parses an RFC 1123 HTTP date (Sun, 06 Nov 1994 08:49:37 GMT) into a unix timestamp. Returns None on any malformed component.