HMAC (Hash-based Message Authentication Code)

Why it matters

A plain hash tells you a message was not accidentally corrupted — but anyone can recompute it, so it proves nothing about who sent the message. HMAC adds a shared secret to the hash. Now only the two parties who know the key can produce a valid code, so a matching HMAC means both "unchanged" and "from someone with the key". That combination — integrity plus authenticity — is what makes it the workhorse of webhooks, API request signing and token verification.

When a service like Stripe or GitHub sends your endpoint a webhook, it signs the raw body with a secret you both hold and puts the HMAC in a header. You recompute it and compare; if they match, you know the payload is genuine and untouched. Without that check, anyone who guesses your URL can forge events.

How it is built

HMAC is a specific, careful construction — not just "hash the key and the message together" (which is vulnerable to length-extension attacks). RFC 2104 defines it as two nested hashes with the key XORed into distinct inner and outer pads: H((K ⊕ opad) || H((K ⊕ ipad) || message)). You do not implement this by hand; every crypto library provides it.

• Name it by its hash: HMAC-SHA256 is HMAC over SHA-256. Prefer SHA-256 or better; HMAC-SHA1 is legacy and should not be used for new designs.
• Output is the hash's width (32 bytes for SHA-256), rendered as hex or Base64 depending on the API.
• It is symmetric: the same secret computes and verifies. That is the crucial difference from a digital signature, where a private key signs and a public key verifies — HMAC gives no non-repudiation, because either party could have produced the code.

One implementation rule matters enormously: verify in constant time. Comparing the received and computed codes byte-by-byte with an early exit leaks timing that can be used to forge a code; use a constant-time comparison.

Common misreadings

• HMAC is not a signature. Both sides share the secret, so it cannot prove which party sent a message to a third party. When you need non-repudiation, use asymmetric signatures.
• Sign the exact bytes, not a re-serialised object. Reformatting the JSON before hashing changes the bytes and breaks verification — hash the raw received body.
• Compare in constant time. A naive == on the codes can leak timing; use the library's constant-time equality (as the tool does) to avoid a byte-at-a-time forgery.

Related terms

• Hash Function — A cryptographic hash function turns any input into a fixed-length digest such that the same input always gives the same output, a tiny change gives a completely different output, and — for a secure one — you cannot work back from the digest to the input or find two inputs that share it.
• AES-GCM — AES-GCM is a symmetric encryption mode that both hides data and detects tampering in one step — it produces ciphertext plus an authentication tag, so decryption fails loudly if even one bit of the ciphertext or its associated data was altered.
• JWT — A JWT is a compact, URL-safe token made of three Base64url parts — a header, a JSON payload of claims, and a signature — that lets a server hand a client a set of verified facts (who you are, when it expires) it can check later without a database lookup.