Hash based message authentication code

How it works

HMAC is a construction, not a single hash. You choose a hash function — often SHA-256 in new work — and a secret key both sides already share. The construction pads and mixes the key, hashes the message with an inner key, then hashes that digest with an outer key. The output is a tag the same length as that hash’s digest. Send the message and the tag. The receiver, who has the same key, computes the tag again and compares. If the tags match, the message matches what the sender tagged, as far as that key and hash are concerned.

The comparison should not leak how far the tags matched. A straight byte-by-byte exit on the first difference can turn a tag into a guessing aid. Use the compare the library documents for MAC tags. Do not write your own “almost equal” on hex strings in a page you will ship.

HMAC does not hide the message. Anyone who can read the bytes can read the message. Confidentiality is encryption, a different job. HMAC answers a different question: “did this come from someone with the key, and is this still the same bytes?” A hash alone, without a key, does not answer that. Anyone can recompute a bare hash of a forged message. Anyone without the key cannot recompute the HMAC tag.

What HMAC is for, and what it is not

API request signing, cookie integrity, webhook verification, and some token formats use HMAC so a server can reject a tweaked payload. The key lives on the parties who are allowed to tag. It does not live in the browser page you ship to the world if that page is supposed to be the only checker. A secret in a public script is not a secret.

Integrity: a flipped bit in the message should fail the tag check. Authenticity, assuming the key stayed secret: a stranger should not be able to mint a valid tag. Not encryption: the payload can still be readable.

Not a password hash for storing logins: password storage has its own slow, salted constructions. HMAC is the wrong shape for that shelf. Key handling is the whole sport. If the key leaks, anyone who has it can tag anything. If you reuse one key for many jobs, a leak in one job is a leak in all of them. If you put the key in a repository, a ticket, or a screenshot, treat it as burned and mint another. Truncating a tag shortens the check. Libraries let you do it; do not truncate into a toy length and call it the same protection.

Hash choice and a tag you can verify

The hash you pair with HMAC should still be a hash you would trust as a hash. SHA-256 is a common pair, written HMAC-SHA256. Older pairs exist because old systems exist. Do not invent a homemade mix of a hash and a key “like HMAC” by concatenating the key and the message once. That homemade mix is a different construction with a long history of getting the mix wrong. Use the HMAC function in a maintained library. Feed it the key, the message bytes, and the hash name. Take the tag it returns.

HMAC is a seal, not an envelope. Anyone can read the letter. Only the key can stamp it, and only the key can tell a forged stamp from a real one. Document the pieces together: hash name, how the message bytes are built (headers, body, a timestamp, a nonce), and where the tag travels. A tag computed over a different byte string than the receiver rebuilds will fail forever, and that failure looks like “HMAC is broken” when the real bug is a missing newline. Canonicalize the bytes. Then tag them. Then compare tags with the function meant for tags.