HMAC Generator

How HMAC works

HMAC (hash-based message authentication code, RFC 2104) combines a cryptographic hash with a secret key. Only someone who knows the key can produce the right value for a message, so a matching HMAC proves two things at once: the message was not changed, and it came from a holder of the key.

The construction is H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ message)). The key is hashed first if it is longer than the hash's block size (64 bytes for MD5, SHA-1 and SHA-256, 128 for SHA-384 and SHA-512), padded with zeros to that size, then XORed with ipad (0x36 bytes) for an inner hash over the message and with opad (0x5c bytes) for an outer hash over the inner result. A naive SHA-256(key ‖ message) has no outer hash, so anyone who sees one tag can append data to the message and compute a valid new tag without the key (a length-extension attack).

The output has the length of the underlying hash: 32 bytes, or 64 hex characters, for HMAC-SHA256. RFC 2104 recommends a key at least that long, and the random Base64 generator makes suitable ones.

Where HMAC signatures are used

• GitHub webhooks. The X-Hub-Signature-256 header is sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with the webhook secret. You can paste the whole header value into Compare with; the sha256= prefix is ignored.
• Stripe webhooks. The Stripe-Signature header carries a timestamp t and a signature v1: the hex HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with the endpoint secret (whsec_...) used as text.
• Shopify webhooks. X-Shopify-Hmac-Sha256 holds the HMAC-SHA256 of the raw body in Base64, keyed with the app's client secret, so choose Base64 output or paste the header value into Compare with.
• AWS Signature Version 4. The signing key is derived by chaining HMAC-SHA256: the date keyed with AWS4 plus the secret access key, then the region, the service and aws4_request, each keyed with the previous result. Set the key format to Hex to feed one step's output into the next.
• JSON Web Tokens. HS256, HS384 and HS512 are HMAC-SHA256, -384 and -512 over the encoded header, a dot and the encoded payload. The third part of the token is that HMAC in URL-safe Base64, which Compare with accepts as it is. The JWT decoder verifies whole tokens.

Always compute the HMAC over the raw body exactly as it was received. Parsing JSON and serializing it again changes spacing or key order, and even one extra newline gives a completely different HMAC.

HMAC in code

# Python
import hmac, hashlib
sig = hmac.new(b'key', b'message', hashlib.sha256).hexdigest()
hmac.compare_digest(sig, received)        # constant-time comparison

// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', 'key').update('message').digest('hex');
// timingSafeEqual throws if the lengths differ, so check them first
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(received));

// PHP: the message comes before the key
$sig = hash_hmac('sha256', 'message', 'key');
hash_equals($sig, $received);

# OpenSSL: a text key, then the same key given as hex
printf '%s' 'message' | openssl dgst -sha256 -hmac 'key'
printf '%s' 'message' | openssl dgst -sha256 -mac HMAC -macopt hexkey:6b6579

# Test vector: key "key", message "The quick brown fox jumps over the lazy dog"
# HMAC-SHA256 = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8

When you verify a signature in your own code, use a constant-time comparison like the ones above. A plain == stops at the first differing character, and that timing difference can let an attacker find a valid signature byte by byte. For timestamped schemes such as Stripe's, also reject requests whose timestamp is more than a few minutes old, which blocks replays.