On this page
- What is a hash-based message authentication code?
- Why can't a plain hash prove who sent a message?
- How does HMAC work?
- How does HMAC authentication sign webhooks and APIs?
- How do you choose and store an HMAC key?
- How to generate an HMAC-SHA256 online
- How to share an HMAC key safely
- Frequently asked questions
What is a hash-based message authentication code?
An HMAC takes three things: a message, a secret key and a hash function such as SHA-256. It returns a fixed-length tag. The sender attaches the tag to the message. The receiver, who holds the same key, computes the tag again and compares the two.
If the tags match, the receiver knows two things:
- Integrity: the message is unchanged, because a single altered byte gives a completely different tag.
- Origin: the tag was made by someone who holds the key, because nobody else can compute it.
HMAC was defined in RFC 2104 and later standardised by NIST in FIPS 198-1. It does not hide the message. The content stays readable, and if it needs to stay private you encrypt it as well. Our guide to hashing, encoding and encryption covers where each of those fits.
Why can't a plain hash prove who sent a message?
A hash has no secret in it. If an attacker changes a message, they can run the same public algorithm on the new version and swap in the new hash. The receiver sees a message and a hash that match perfectly.
So a plain hash only catches accidents, such as a corrupted download. It works when you get the hash from a trusted place, and it says nothing about who produced the data.
Plain hash
No key
Anyone can compute it, so it detects accidental change only.
HMAC
One shared secret key
Only key holders can create or check it, so it detects forgery too.
Digital signature
Private and public key pair
Anyone can check it, but only one party can create it.
That last card marks the main limit of HMAC. Both sides hold the same key, so either could have made the tag. An HMAC convinces the receiver, but it cannot prove to a third party which of the two wrote the message.
Why not just hash the key and the message together?
Computing SHA-256(key + message) looks like an obvious shortcut, and it is broken. Hashes such as MD5, SHA-1 and SHA-256 process data in blocks, and their output is their full internal state. An attacker who sees one tag can continue hashing from that state, adding data to the end and getting a valid tag without ever learning the key. This is called a length extension attack, and the HMAC construction exists to avoid it.
How does HMAC work?
HMAC runs the hash twice, using two different versions of the key. Written out, the formula looks like this:
HMAC(key, message) = H( (K xor opad) + H( (K xor ipad) + message ) )In steps:
- Fit the key to the block size. A key shorter than the hash block is padded with zero bytes. A longer one is hashed first. The block is 64 bytes for SHA-256 and 128 bytes for SHA-512.
- Make the inner padded key. XOR the key with ipad, the byte 0x36 repeated across the block.
- Run the inner hash. Hash the inner padded key followed by the message.
- Make the outer padded key. XOR the key with opad, the byte 0x5c repeated across the block.
- Run the outer hash. Hash the outer padded key followed by the inner result. This is the tag.
The outer hash is what stops length extension. An attacker never sees the inner hash output, only the result of hashing it again under a key they do not know, so there is nothing to continue from.
How does HMAC authentication sign webhooks and APIs?
HMAC authentication means the caller proves it holds a shared key by signing each request, without ever sending the key itself. Webhooks are the most common example. A service sends your server an HTTP request when something happens, and your endpoint is a public URL, so anyone could post fake events to it. The signature tells real events from fake ones.
- The provider gives you a signing secret when you create the webhook.
- For each event, it computes an HMAC of the request body with that secret and puts the result in a header.
- Your server computes the same HMAC over the raw body it received.
- If the values differ, your server rejects the request.
GitHub, for example, sends the tag in an X-Hub-Signature-256 header with a sha256= prefix, and its documentation walks through validation. Stripe signs a timestamp together with the body. AWS uses HMAC-SHA256 in its Signature Version 4 scheme for API requests.
A minimal check in Python looks like this:
import hashlib
import hmac
def is_valid(secret: bytes, raw_body: bytes, received_hex: str) -> bool:
expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received_hex)What are the most common HMAC verification mistakes?
- Comparing with ==. Normal string comparison can stop at the first wrong character, which leaks timing information. Use a constant-time function such as hmac.compare_digest.
- Signing parsed data. Parsing JSON and serialising it again can change spacing or key order. Always verify the raw bytes.
- Ignoring replays. A valid signed request stays valid if someone resends it. Sign a timestamp too and reject old requests.
- Skipping the check on failure paths. Verify before doing any work, not after.
How do you choose and store an HMAC key?
An HMAC is exactly as strong as its key, so the key should be random, not a word or phrase someone chose. RFC 2104 recommends a key at least as long as the hash output: 32 bytes for HMAC-SHA256 and 64 bytes for HMAC-SHA512. Longer keys add little, and any key beyond the block size is hashed down anyway.
Generate it from a cryptographic random source. This command prints 32 random bytes as hex:
openssl rand -hex 32Then treat it like a password:
- Keep it in a secrets manager or environment variable, never in source code. Our guide to secrets management covers the options.
- Use a separate HMAC key per service or environment, so one leak stays contained.
- Plan for rotation. During a change-over, accept both the old and new key for a short period.
- Replace the key if it has ever appeared in a log, a ticket or a chat.
Which HMAC algorithm should you use?
| Variant | Tag size | Hex characters | When to use it |
|---|---|---|---|
| HMAC-SHA256 | 256 bits | 64 | The default for new work |
| HMAC-SHA384 | 384 bits | 96 | When a spec or policy asks for it |
| HMAC-SHA512 | 512 bits | 128 | When you want a longer tag |
| HMAC-SHA224 | 224 bits | 56 | Only where a shorter tag is required |
| HMAC-SHA1 | 160 bits | 40 | Older systems only |
| HMAC-MD5 | 128 bits | 32 | Older systems only, never new designs |
Collisions broke MD5 and SHA-1 as plain hashes, but HMAC does not rely on collision resistance in the same way, so HMAC-SHA1 has not fallen like SHA-1 itself. Still, there is no reason to choose either for something new.
How to generate an HMAC-SHA256 online
You can reproduce a published test value in the HMAC tab of our hash generator. The key and message below come from test case 2 of RFC 4231, so you can compare the result with the standard itself.
- Open the hash generator and choose the HMAC tab.
- Type Jefe in the Secret key field.
- Type what do ya want for nothing? in the Message field, with no line break at the end.
- Leave the Algorithm dropdown on HMAC-SHA256.
- Read the HMAC output box, which updates as you type, and use Copy to take the value.
The result should be:
5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843Change the "J" in the key to lowercase and the whole value changes. The same happens if you add a space to the message. Open the Algorithm dropdown to try HMAC-SHA1, HMAC-SHA224, HMAC-SHA384, HMAC-SHA512 and HMAC-MD5 with the same input. The Output format buttons switch between hex, uppercase HEX and Base64. The tag stays the same and only its written form changes, which helps when a provider sends its signature in Base64.
The key field takes plain text
The tool uses exactly the characters you type as the key. If a provider gives you a hex or Base64 secret and expects it to be decoded to raw bytes first, your result will not match theirs. A trailing line break in the message also changes the tag, a common reason a webhook check fails while debugging.
The computation runs in your browser, and neither the key nor the message is sent to our server. Even so, test with sample keys where you can, and treat any real key you use as you would a password.
How to share an HMAC key safely
Both sides need the same key, so at some point it has to travel. A chat message or email is the wrong route, because the key stays in the history, in search and on every device of everyone in the thread. Anyone who reads it later can forge valid signatures.
A one-time link leaves no such copy. In SecretNote you paste the key, click Encrypt & Create Link and send the link. The note is encrypted in your browser with AES-256, and the decryption key sits in the part of the link after the # sign, which browsers do not send to the server. With delete after read switched on, as it is by default, the note is removed once it is opened. You can also set how long an unopened note lasts, from 1 hour to 30 days.
This also tells you if something went wrong. If your colleague opens the link and the note is already gone, someone else got there first, so generate a new key and replace the old one.
Send a signing key onceShare it in a link that deletes itself after readingNeed to debug a webhook signature?
Compute an HMAC with your test key and payload, then compare it with the header value in hex or Base64.
Frequently asked questions
A hash uses only the input, so anyone can compute it and it detects accidental change. An HMAC also uses a secret key, so only key holders can produce or verify it. That means an HMAC detects deliberate tampering and shows the message came from someone who has the key.
Use a random key at least as long as the hash output, as RFC 2104 recommends: 32 bytes for HMAC-SHA256 and 64 bytes for HMAC-SHA512. Shorter keys weaken the security. Keys longer than the hash block are hashed down first, so very long keys add little practical strength.
No. Encryption hides content and can be reversed with a key. An HMAC hides nothing and cannot be reversed. The message stays readable, and the tag only proves it is genuine and unchanged. Many secure systems use both, encrypting for privacy and authenticating to detect tampering.
Webhook endpoints are public URLs, so anyone can post to them. HMAC-SHA256 lets the receiver confirm each request came from the provider and was not altered, without the key ever crossing the network. It is fast, widely supported in every major language and needs only one shared secret per endpoint.
No. There is no known way to work backwards from a tag to the key when the hash is sound. However, an attacker with a message and its tag can guess keys offline, so a short or human-chosen key can be cracked. A long random key makes guessing impractical.