HMAC Hash

An HMAC (Hash-based Message Authentication Code) is an authentication code computed from a message, a shared secret key and a cryptographic hash function, such as SHA-256. It verifies the integrity of the message and its authenticity with respect to the shared key. Unlike a plain hash, it requires a secret key to produce a valid tag.

A hash, such as SHA-256, produces a fingerprint of the message without using a secret key. An HMAC additionally uses a shared secret key to authenticate the message.

A hash alone does not protect against tampering if an attacker can modify both the message and its fingerprint at the same time.

A valid HMAC verifies the integrity of the message and its compatibility with the secret key.

HMACs are used in particular to authenticate data and requests:

— Webhooks: GitHub uses HMAC-SHA256 in the X-Hub-Signature-256 header; Stripe notably uses HMAC-SHA256 in Stripe-Signature.

— Tokens: JWTs using HS256 are signed with HMAC-SHA256.

— Cookies and sessions: to verify that signed data has not been modified, without encrypting it.

— APIs: AWS Signature Version 4 uses HMAC-SHA256 to sign requests and derive keys.

— Key derivation: PBKDF2 can use HMAC as its internal pseudorandom function.

Common variants are:

— SHA256: full 256-bit tag (32 bytes), a common choice for new applications.

— SHA512: 512-bit tag (64 bytes).

— SHA384: 384-bit tag (48 bytes).

— SHA1: still present in legacy systems, but to be avoided in new applications.

— HMAC-MD5: not recommended for new applications, even though the known MD5 collisions do not directly break HMAC-MD5.

The HMAC construction defined by RFC 2104 relies on two nested hashes:

$$ HMAC(K,M)=H((K' \oplus opad) \parallel H((K' \oplus ipad) \parallel M)) $$

— $ K $: secret key; $ K' $: key adjusted to the block size of the hash function.

— $ M $: message to authenticate.

— $ H $: hash function.

— $ \oplus $: XOR (exclusive OR); $ \parallel $: concatenation.

— $ ipad $ and $ opad $: constant byte blocks used respectively in the inner and outer hash.

In practice, prefer a cryptographic library over a manual implementation.

The result is 64 hexadecimal characters for HMAC-SHA256. In a real application, use a random, secure secret key. The message must be byte-for-byte identical when calculating and verifying.

An HMAC is not encryption: its tag does not contain the original message in a recoverable form.

Recovering the message or the key would require testing candidate values in particular.

A random 256-bit key is beyond the reach of a realistic exhaustive search.

A key derived from a weak password remains vulnerable to dictionary attacks.

Recalculate the HMAC with the same key, the same message and the same parameters, then compare the tags.

In code, prefer a constant-time comparison function.

— Length: a full HMAC-SHA256 produces 32 bytes (64 hexadecimal characters); HMAC-SHA512, 64 bytes; HMAC-SHA1, 20 bytes; HMAC-MD5, 16 bytes.

— Format: GitHub uses the 'sha256=' prefix; Stripe notably uses t= and v1= in Stripe-Signature; AWS Signature Version 4 uses fields such as Signature and SignedHeaders.

— Context: HTTP header, API parameter or field named hmac.

Prefer standard cryptographic libraries:

— Python: hmac and hashlib.

— Node.js: crypto.createHmac().

— Java: javax.crypto.Mac.

— PHP: hash_hmac().

— Rust: hmac and sha2 crates.

— OpenSSL: openssl dgst command with the -hmac option.

Anyone with the key can produce valid HMACs and forge the messages concerned.

The key must therefore remain confidential.

After a leak, revoke the compromised key.

A collision occurs when two different inputs produce the same hash. The known collisions against MD5 and SHA-1 do not, on their own, allow an HMAC to be forged directly without knowing the key.

HMAC security does not, however, depend solely on collision resistance.

HMAC has several limitations:

— Key management: the sender and the verifier must share a secret.

— Non-repudiation: since several key holders can produce a valid tag, HMAC cannot prove which one signed the message.

— Replay: an authentic message can be retransmitted. A timestamp or a nonce, along with appropriate checks, can limit this risk.

— Confidentiality: HMAC does not encrypt the message.

— Serialization: any difference in the data representation can invalidate the tag.