hot.dev/hot-std / ::hot::hmac

HMAC (Hash-based Message Authentication Code) functions for message authentication and API signing.

Functions

hmac-sha256 core

fn (key: Str | Bytes, data: Str | Bytes): Str

HMAC-SHA256 message authentication code. Returns hex-encoded 64-character string. Essential for AWS Signature v4, webhook verification, and API authentication.

Example

hmac-sha256("secret-key", "message to sign")
// 64-character hex string

// AWS Signature v4 key derivation chain
k-date hmac-sha256-bytes(`AWS4${secret}`, date)
k-region hmac-sha256-bytes(k-date, region)
k-service hmac-sha256-bytes(k-region, service)
k-signing hmac-sha256-bytes(k-service, "aws4_request")

hmac-sha256-bytes core

fn (key: Str | Bytes, data: Str | Bytes): Bytes

HMAC-SHA256 returning raw bytes instead of hex. Useful for chained HMAC operations like AWS Signature v4.

Example

// Chain HMACs for key derivation
k-date hmac-sha256-bytes(`AWS4${secret}`, "20231215")
k-region hmac-sha256-bytes(k-date, "us-east-1")

hmac-verify core

fn (key: Str | Bytes, data: Str | Bytes, expected: Str, algorithm: Str): Bool

Verify HMAC in constant time to prevent timing attacks. Returns true if the computed HMAC matches the expected value.

Example

// Verify a webhook signature
is-valid hmac-verify(secret, payload, signature, "sha256")

// Supported algorithms: "sha256", "sha512", "sha1"

hmac-sha1

fn (key: Str | Bytes, data: Str | Bytes): Str

HMAC-SHA1 (legacy). Use only for compatibility with existing systems. NOT recommended for new applications.

Example

// GitHub webhook signature verification
hmac-sha1(webhook-secret, payload)

hmac-sha512

fn (key: Str | Bytes, data: Str | Bytes): Str

HMAC-SHA512 message authentication code. Returns hex-encoded 128-character string.

Example

hmac-sha512("secret-key", "message")
// 128-character hex string

hmac-verify-base64

fn (key: Str | Bytes, data: Str | Bytes, expected-b64: Str, algorithm: Str): Bool

Verify a base64-encoded HMAC signature (base64 of the raw digest) over data using constant-time comparison. algorithm is "sha256", "sha512", or "sha1". A malformed or empty signature returns false.

The recipe behind Shopify-, HubSpot-, and Twilio-style webhook signatures.

Example

::hot::hmac/hmac-verify-base64(secret, request.body-raw, signature-b64, "sha256")

hmac-verify-hex

fn (key: Str | Bytes, data: Str | Bytes, expected-hex: Str, algorithm: Str): Bool

Verify a hex-encoded HMAC signature over data using constant-time comparison. algorithm is "sha256", "sha512", or "sha1". Comparison is case-insensitive; a malformed or empty signature returns false rather than erroring — safe for attacker-controlled input (unlike hmac-verify, which errors on invalid hex).

The recipe behind GitHub- and Meta-style webhook signatures.

Example

::hot::hmac/hmac-verify-hex(secret, request.body-raw, signature-hex, "sha256")