HMAC Generator

HMAC (Hash-based Message Authentication Code) is a way to compute a cryptographic checksum over a message using both the message and a secret key. It answers a specific question: did this message come from someone who holds the shared secret, and has it been altered in transit? A plain hash like SHA-256 answers only half that question — it detects accidental corruption, but anyone can recompute a hash, so it proves nothing about the sender. HMAC folds the secret key into the hash computation itself, so the output can only be produced (and verified) by someone who knows the key.

The construction, defined in FIPS 198 and RFC 2104, is elegantly simple: the key is used to derive two padded values (an inner and an outer key), the message is hashed with the inner key, and that result is hashed again with the outer key. This two-layer structure is what gives HMAC its security properties — it's resistant to length-extension attacks that plague naive constructions like Hash(key || message), and it remains secure even when the underlying hash function has weaknesses. The output is a fixed-size digest: 256 bits for HMAC-SHA256, regardless of whether the message is one byte or one gigabyte.

The difference between a plain hash and an HMAC is entirely about trust. A plain SHA-256 hash of a file verifies integrity — if the hash matches, the file is bit-for-bit identical to what was hashed — but it says nothing about authenticity, because SHA-256 is public and anyone can compute it. An attacker who modifies a file can simply publish the new hash alongside it. HMAC closes this gap: the digest is a function of both the message and the secret key, so an attacker without the key cannot produce a valid HMAC for a modified message, even if they know exactly how HMAC works.

This is the distinction between "has this changed?" and "did the right party send this?" In practice, the two are used together: a download page publishes a plain hash so you can verify integrity, while API requests carry an HMAC so the server can verify authenticity. Plain hashes protect against corruption; HMACs protect against forgery. Confusing them is a classic security mistake — using a plain hash where authenticity is required leaves you fully exposed to tampering.

The most widespread modern use of HMAC is webhook verification. When a service sends you a webhook — a payment notification, a deployment event, a message — it signs the payload with a secret and includes the signature in a header (GitHub's X-Hub-Signature-256, Stripe's v1 scheme). Your server recomputes the HMAC over the raw body using the same secret and compares. If it matches, the payload genuinely came from that service and wasn't altered in transit; if it doesn't, you reject it. This is how you trust an HTTP request that arrived over the network from a third party.

API authentication uses the same mechanism: the client signs each request (or a canonical representation of it — method, path, timestamp, body hash) with the API secret, and the server recomputes and compares. The timestamp in the signed payload prevents replay attacks, since an old request with a valid signature but a stale timestamp is rejected. HMAC also appears in JWT signing (HS256), in verifying downloaded artifacts, and anywhere two parties who share a secret need to prove a message's origin — the pattern is always the same: sign with the key, verify by recomputing.

The algorithms differ only in the underlying hash function: HMAC-MD5 and HMAC-SHA1 use older, weaker hashes, while HMAC-SHA256, HMAC-SHA384 and HMAC-SHA512 use the SHA-2 family. The HMAC construction itself provides the security; the hash function determines the output length and the resistance to collision attacks. HMAC-SHA512 produces 512-bit digests and is the conservative choice when you want maximum margin; HMAC-SHA256 is the default for most systems today, offering 256-bit security with broad library support and good performance.

MD5 and SHA-1 are deprecated for new systems — both have demonstrated collision attacks, and while HMAC's construction means the practical risk is lower than for the raw hashes, there's no reason to choose a weaker primitive when SHA-2 is universally available. Legacy systems still use HMAC-SHA1 (many older webhook schemes default to it), and migration paths typically accept both old and new signatures during a transition window. For new designs, HMAC-SHA256 is the standard recommendation.

The security of HMAC rests entirely on the secret key: it must be long enough to resist brute force (at least 256 bits of entropy for HMAC-SHA256), generated with a cryptographic random source, and never exposed. The key is shared between the two parties — that's the trust boundary — so key management (rotation, storage in a secrets manager rather than source code, distribution) is the real operational challenge, not the cryptography. A leaked key means an attacker can forge valid HMACs for arbitrary messages, which is indistinguishable from legitimate ones.

Two implementation details bite people regularly. First, compare signatures with a constant-time comparison, not a plain string equality — a naive comparison leaks timing information that can, over many requests, reveal a valid signature byte by byte. Second, HMAC over the exact bytes of the message, not a re-serialized version: if you parse a JSON payload and re-stringify it before verifying, formatting differences will make the signature mismatch (or worse, if you sign the re-serialized form, the verifier must do the identical re-serialization). In any language, the recipe is the same — crypto/hmac in Python, crypto.createHmac in Node.js, HMAC.swift in Swift — and the output is typically encoded as hex for debugging or Base64 for compact transport in HTTP headers.