Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 40 ยท Authentication and Keys

MACs and HMAC

Learn how message authentication codes prove a message is genuine, build HMAC by hand, use hmac.compare_digest, and see a timing attack and tag forgery.

Encryption keeps a message secret. But in many situations the content is not secret at all; what matters is that it is genuine and unchanged. A cookie that says user=42 must not be editable by the user; an API request must come from the client who owns the account; a downloaded update must not have been swapped on the way. A hash alone cannot do this, because anyone can compute a hash of a modified message. What you need is a hash-like fingerprint that only someone holding a secret key can produce.

That tool is the message authentication code (MAC). This lesson explains what a MAC promises, builds HMAC (the standard MAC based on hash functions) from scratch and checks it against Python's hmac module, then shows two classic ways to get MACs wrong: comparing tags with ==, and using tags that are too short.

What a MAC does

A MAC is a function tag = MAC(key, message). The sender and the receiver share the same secret key. The sender attaches the tag to the message. The receiver recomputes the tag on the message it received and compares. If they match, the message was produced by someone who knows the key and has not been modified.

flowchart LR
    M["Message"] --> S["MAC(key, message)"]
    K["Shared key"] --> S
    S --> T["Tag"]
    M --> V["Receiver recomputes<br/>and compares"]
    T --> V
    K --> V
    V --> R["Accept or reject"]

The tag travels with the message. Only a holder of the key can create a valid one.

The security goal is called unforgeability: even after seeing many valid (message, tag) pairs, an attacker must not be able to produce a valid tag for any new message. Unlike an encryption scheme, a MAC does not hide the message, and unlike a digital signature, anyone who can verify a MAC can also create one (they share the key), so a MAC cannot prove to a third party who sent a message.

HMAC

The obvious design, SHA256(key || message), is broken for hash functions in the SHA-2 family because of length extension: knowing H(key || m) lets an attacker compute H(key || m || padding || extra) without the key (the hash attacks lesson shows how). HMAC, designed by Bellare, Canetti and Krawczyk, avoids the problem by hashing twice with two keys derived from the original:

HMAC(K, m) = H( (K' XOR opad) || H( (K' XOR ipad) || m ) )

where K' is the key padded with zeros to the hash's block size (64 bytes for SHA-256; a longer key is hashed first), ipad is the byte 0x36 repeated and opad is 0x5c repeated. The inner hash result is hidden inside the outer hash, so an attacker never sees an intermediate value to extend.

flowchart TD
    A["key XOR ipad"] --> I["Inner hash<br/>H(key XOR ipad || message)"]
    M["message"] --> I
    I --> O["Outer hash<br/>H(key XOR opad || inner result)"]
    B["key XOR opad"] --> O
    O --> T["HMAC tag"]

HMAC is two nested hashes with two differently masked copies of the key.

The program below writes HMAC in six lines, compares it with the standard library, and uses the hmac.new(...) interface you will use in real code.

Python HMAC from scratch versus the hmac module

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Your six-line version produces the same 256-bit tag as the library. In production, always use the library: it handles every key length correctly and works in constant time.

Note: HMAC remains secure even when the underlying hash has some collision weaknesses, which is why HMAC-SHA1 was still acceptable long after SHA-1 stopped being safe for signatures. Today use HMAC-SHA-256 or better. The key should be at least 16 random bytes (32 is better).

Compare tags in constant time

Verification looks innocent: if tag == expected:. But Python's == on bytes stops at the first byte that differs. Comparing a tag that is wrong in the very first byte returns slightly faster than one that is right for the first 20 bytes. If an attacker can measure response times, even over a network after averaging many requests, she can recover a valid tag byte by byte: try all 256 values for the first byte, keep the one that takes longest, then move on to the second byte, and so on. A 32-byte tag needs only 32 x 256 guesses instead of 2256.

Real timing differences are tiny and noisy, so the program below counts comparison steps instead of measuring time. The attacker is only allowed to ask "how many bytes did the comparison examine?", which models a perfectly measured timing channel.

Python A timing attack on tag comparison

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The attacker forged a valid tag for a message she never had a tag for, using at most 2,048 queries (fewer here, since the last byte stops as soon as the server accepts). hmac.compare_digest(a, b) always examines every byte (and secrets.compare_digest is the same function), so its running time does not depend on where the first difference is. Use it for every comparison of secrets: MAC tags, session tokens, API keys.

Tag length and brute-force forgery

A tag does not have to be 32 bytes, and shortening it saves space. But the tag's length sets a floor on forgery: an attacker who simply guesses a k-bit tag is right with probability 2-k. If the server accepts unlimited attempts, she needs about 2k tries on average. A 16-bit tag falls after tens of thousands of requests, an 8-bit tag after a few hundred.

Python Guessing short tags

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The expected number of guesses is half the tag space. Truncating HMAC-SHA-256 to 16 bytes (128 bits) is standard and safe; going below 64 bits is risky unless the number of verification attempts is strictly limited.

What a MAC does not prevent: replay

A valid tag stays valid forever. If an attacker records a perfectly legitimate message, "pay Bob 10", and sends it again tomorrow, the MAC verifies fine. Authenticity does not mean freshness. Protect against this by putting something unique inside the authenticated bytes: a counter, a timestamp with an expiry, or a one-time ID that the server remembers. Because the extra field is covered by the tag, the attacker cannot change it. This is exactly what the nonce and the sequence number do in the authenticated encryption schemes you saw before, where a MAC is the building block of the tag.

Finally, one more rule: never reuse one key for different purposes, such as using the same key for HMAC and for encryption. Derive separate keys from a master key; key derivation covers that later in the tutorial.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a valid MAC tag prove to the receiver?

    A MAC proves integrity and origin among the key holders. It does not hide the message, does not give non-repudiation (both sides hold the key) and does not stop replay.
  2. 2. Why is SHA256(key || message) a poor MAC while HMAC-SHA256 is fine?

    With SHA-256's Merkle-Damgard design, H(key || m) lets an attacker continue hashing and compute a valid tag for an extended message. HMAC hides the inner hash inside an outer hash.
  3. 3. What is the correct way to compare a received tag with the expected one?

    compare_digest takes the same time whether the tags differ in the first byte or the last, so timing cannot be used to guess the tag byte by byte.
  4. 4. An attacker records a valid message and tag and sends them again a week later. What defends against this replay?

    A tag stays valid forever. Including a fresh, authenticated value lets the receiver reject old messages, and the attacker cannot alter it without breaking the tag.

Summary

  • A MAC is a keyed fingerprint: only key holders can create a tag that verifies, so it proves integrity and origin among them.
  • HMAC wraps a hash in two keyed layers to avoid length extension; use hmac.new(key, msg, hashlib.sha256).
  • Always verify with hmac.compare_digest; early-exit comparison lets an attacker recover a tag byte by byte.
  • Keep tags at 128 bits or more, and add counters or timestamps to defeat replay.

Next: Password Hashing: PBKDF2, scrypt and Argon2, where hashing meets low-entropy secrets.