HMAC Generator & Signature Verifier

The Cryptographic Foundations of HMAC (RFC 2104)

A Keyed-Hash Message Authentication Code (HMAC) is a cryptographic construction defined in RFC 2104 and NIST FIPS 198-1. It provides a mechanism for verifying both the data integrity and the authenticity of a message using a shared secret key and an underlying cryptographic hash function (such as SHA-256 or SHA-512).

1. Why Simple Concatenation ($H(key \parallel message)$) Fails

A common mistake made by junior developers is attempting to build an authentication code by hashing the key prepended to the message: $\text{MAC} = H(K \parallel M)$.

For hash functions based on the Merkle-Damgård construction (including MD5, SHA-1, SHA-256, and SHA-512), this naive approach is vulnerable to a catastrophic attack known as the Length Extension Attack:

• An attacker who intercepts $M$ and $\text{MAC} = H(K \parallel M)$ does not know the secret key $K$.
• However, because the hash output represents the internal state of the compression function after processing $K \parallel M$, an attacker can append their own malicious suffix $M'$ and calculate the valid hash of $K \parallel M \parallel \text{padding} \parallel M'$ without ever knowing the secret key.

2. The Inner & Outer Padding Formula

To mathematically defeat length extension attacks, RFC 2104 defines a two-pass nested hashing algorithm:

$$\text{HMAC}(K, m) = H\Big((K' \oplus \text{opad}) \parallel H\big((K' \oplus \text{ipad}) \parallel m\big)\Big)$$

Where:

• $H$ is the underlying cryptographic hash function (e.g. SHA-256).
• $B$ is the block size of the hash function (64 bytes for SHA-256, 128 bytes for SHA-512).
• $K'$ is the key normalized to length $B$: if $K$ is longer than $B$, it is hashed ($K' = H(K)$); if shorter, it is zero-padded on the right to $B$ bytes.
• $\text{ipad}$ is the inner pad byte repeated $B$ times: 0x36 (binary 00110110).
• $\text{opad}$ is the outer pad byte repeated $B$ times: 0x5C (binary 01011100).
• $\oplus$ denotes bitwise XOR.

3. Defending Webhooks Against Timing Attacks

When verifying incoming webhook signatures (such as Stripe, GitHub, or Shopify signatures) in your backend application, never use standard string equality (e.g. signature === calculated or signature == expected):

Standard string comparison operators terminate as soon as the first non-matching byte is encountered. An attacker measuring execution latency with microsecond accuracy can determine which characters matched, allowing them to brute-force a valid HMAC byte-by-byte.

Always use a constant-time comparison primitive:

• Node.js: crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
• Python: hmac.compare_digest(sig, expected)
• Go: hmac.Equal([]byte(sig), []byte(expected))
• PHP: hash_equals($expected, $sig)

Frequently Asked Questions

Is HMAC reversible or can the secret key be extracted?

No. HMAC is a one-way cryptographic function. Given an HMAC digest and the original message, it is computationally infeasible to recover the secret key, provided the key has sufficient entropy (at least 128 to 256 bits of randomness).

Should I use Hex or Base64 encoding for HMAC signatures?

Hexadecimal is most common in webhook headers (e.g., GitHub X-Hub-Signature-256: sha256=HEX...), while Base64URL is standard in JSON Web Signatures (JWT / JWS).

Are my secret keys sent to your servers?

Never. HMAC computations utilize the browser's hardware-accelerated Web Cryptography API (crypto.subtle.sign). No keys or payloads ever leave your device.