What is HMAC? Understanding Hash-Based Message Authentication

The Problem with Simple Hashes

Imagine you are building a webhook system. Your server needs to send a notification to a client whenever a payment is processed. You decide to send the data as a JSON payload: {"payment_id": 123, "status": "paid"}.

To ensure the data isn't tampered with in transit, you might think to include a SHA-256 hash of the payload. But there's a fatal flaw: an attacker acting as a man-in-the-middle could intercept the request, change the status to "refunded", calculate a new SHA-256 hash, and send the modified payload to the client. The client would see that the payload matches the hash, completely unaware of the tampering.

Standard hashes provide integrity against accidental corruption, but they do not provide authenticity against malicious tampering. This is exactly the problem HMAC solves.

Enter HMAC

HMAC stands for Hash-based Message Authentication Code. It is a specific type of MAC involving a cryptographic hash function and a secret cryptographic key.

By combining the data payload with a secret key known only to the sender and the receiver, HMAC ensures two things simultaneously:

1. Integrity: The message has not been altered in transit.
2. Authenticity: The message definitely came from someone who possesses the secret key.

Because the attacker does not know the secret key, they cannot calculate a valid HMAC for their forged "refunded" payload. When the client receives the forged payload, the HMAC validation will fail, and the request will be rejected.

How HMAC Works (The Math)

You might wonder, why not just append the secret to the message and hash it together? Like this: Hash(Key + Message).

Early attempts at MACs did exactly this, but it led to a vulnerability known as a length extension attack. If an attacker sees Hash(Key + Message), certain hash functions (like MD5, SHA-1, and SHA-256) allow the attacker to append extra data and calculate a valid Hash(Key + Message + ExtraData) without ever knowing the key.

HMAC fixes this by hashing the data twice with mathematical padding. The exact formula is:

Where H is the hash function, K is the key, m is the message, ⊕ is XOR, ∥ is concatenation, and opad/ipad are specific padding constants.

Common Use Cases for HMAC

• Webhooks (Stripe, GitHub, etc.): When these services send data to your servers, they include an HMAC signature in the HTTP headers (e.g., Stripe-Signature). Your server uses your webhook secret to calculate the HMAC of the incoming payload. If it matches the header, you know Stripe sent it.
• JSON Web Tokens (JWTs): When a JWT is signed using symmetric encryption (algorithms like HS256), the signature portion of the token is literally an HMAC-SHA256 signature of the header and payload.
• Amazon Web Services (AWS) API Requests: Every API request you send to AWS must be signed using AWS Signature Version 4, which heavily relies on nested HMAC-SHA256 calculations using your AWS Secret Key.