Introduction
APIs and webhook consumers often need to know that a message came from a party sharing a secret and was not altered in transit. A plain hash detects accidental change but an attacker can replace both the message and its hash.
HMAC combines a secret key with a cryptographic hash to create a message authentication code. Payment webhooks, cloud APIs, signed cookies and internal service calls use it extensively. The utily.tools HMAC Generator calculates signatures in hex, Base64 and Base64url for test and debugging workflows.
A keyed construction around a hash function
HMAC normalizes the key to the hash block size and combines it with two fixed pads. Conceptually, HMAC(K,m) = H((K ⊕ opad) || H((K ⊕ ipad) || m)). The inner and outer layers avoid structural weaknesses that would affect naive constructions such as H(K || m).
Security depends on a strong secret key and a suitable hash. The same message and key always produce the same tag. Anyone with the key can generate valid tags, so HMAC provides shared-secret authenticity rather than non-repudiation.
Technical foundations and behavior
Both sides must authenticate exactly the same bytes. Method, path, timestamp, body encoding and line endings may be part of a canonical request. A one-character difference produces a completely different tag.
Canonicalization
Define field order, separators, character encoding and JSON handling before signing. Re-serializing a JSON object may change whitespace or key order, so webhook verification often signs the raw request body captured before parsing.
Replay protection
A valid HMAC does not prove freshness. Include a timestamp or nonce in the signed data, enforce a short acceptance window and record used identifiers where replay would be harmful.
Constant-time comparison and key storage
Verification should compare tags in constant time to reduce timing leakage. Secrets belong in a managed secret store, should be rotated and must never be exposed in URLs, client-side bundles or logs.
Real-world applications
Webhook verification
A commerce platform signs the raw event body and timestamp; the receiver verifies both before processing a refund or order update.
API request signing
A client signs the HTTP method, canonical path, headers and body digest so intermediaries cannot alter the request undetected.
Signed state
An application attaches an HMAC to a compact state value to detect client-side tampering without encrypting the content.
Standards and deeper technical reference
RFC 2104 construction
HMAC was defined by Bellare, Canetti and Krawczyk and published as RFC 2104. For hash H, block-sized normalized key K, inner pad ipad=0x36 and outer pad opad=0x5c, it computes H((K xor opad) || H((K xor ipad) || message)). The two domains prevent the naive secret-prefix weaknesses of Merkle-Damgård hashes.
Keys longer than the hash block size are first hashed; shorter keys are zero-padded for the construction. Security cannot exceed key entropy or digest strength. For HMAC-SHA-256, a uniformly random 256-bit key is a straightforward default.
Encoding and protocol canonicalization
Both parties must MAC identical bytes. HTTP methods, paths, query ordering, header case, newline choice, timestamp representation and JSON serialization all need a canonical signing specification. Signing visually equivalent but byte-different content produces a different tag.
A robust envelope includes a key identifier, algorithm identifier fixed by policy, timestamp, nonce and the authenticated payload. Bind contextual fields such as tenant, endpoint and content type to prevent a valid tag from being replayed in another protocol location.
Verification, truncation and key lifecycle
Compare received and expected tags with a constant-time primitive after validating a fixed encoded length. Ordinary string equality can leak the first differing position through timing. RFC 2104 permits truncation, but the protocol must define one fixed length; longer tags increase forgery resistance.
Rotate keys with explicit identifiers, accept old keys only for a bounded migration interval and never reuse one HMAC key across unrelated protocols. HMAC authenticates parties that share a key, but it cannot prove which holder produced a message and therefore does not provide non-repudiation.
Primary specifications and references
- RFC 2104: HMAC Keyed-Hashing for Message AuthenticationIETF / RFC Editor
- FIPS 198-1: The Keyed-Hash Message Authentication CodeNIST
- RFC 4231: HMAC-SHA Test CasesIETF / RFC Editor
Conclusion
HMAC adds secret-key authenticity to a cryptographic hash. Correct byte canonicalization, replay controls, constant-time comparison and disciplined secret management are as important as the algorithm.
I view HMAC-SHA-256 as an excellent primitive for controlled integrations because it is efficient and widely supported, but protocol details must be documented precisely. Test known values with the utily.tools HMAC Generator and continue with the hash and JWE articles.