Hashed Message Authentication Code (HMAC): How It Works and Why It Matters
A hashed message authentication code, more commonly called a hash-based message authentication code (HMAC), is a cryptographic method for confirming that a message has not changed and came from someone who possesses a shared secret. HMAC is widely used in API authentication, signed webhooks, cloud-service requests, token systems, and secure data exchanges. It does not encrypt the underlying data. Instead, it creates a short authentication value—often called a tag or signature—that the receiver can verify.
What Is a Hashed Message Authentication Code?
An HMAC combines three elements:
- A message, such as an API request body or timestamped payload
- A secret key shared by the sender and receiver
- A cryptographic hash function, such as SHA-256
The sender calculates an HMAC tag from the message and secret key, then sends the message with that tag. The receiver independently calculates its own tag using the same secret key and message. If the two values match, the message is considered authentic and intact.
What Does HMAC Protect?
Hashed Message Authentication Code provides two core security properties:
- Integrity – It detects changes to a message. Even a one-character modification produces a different HMAC value.
- Authentication – It demonstrates that the sender knew the shared secret key. An attacker who does not know the key should not be able to generate a valid tag for a modified or fabricated message.
For example, a payment platform may send a webhook payload to an online store along with an HMAC signature. Before processing the event, the store calculates its own signature from the received payload and compares it to the signature supplied by the platform. A mismatch indicates that the payload should not be trusted.
How Does HMAC Work?
At a high level, the HMAC process follows four steps:
- The sender and receiver securely share a secret key.
- The sender combines the secret key and message with a hash algorithm, such as SHA-256.
- The sender sends the message together with the resulting HMAC tag.
- The receiver recalculates the HMAC using the received message and its copy of the secret key.
If both tags match, verification succeeds.
The HMAC algorithm uses an inner and outer hash operation rather than simply hashing secret + message. This construction is intentionally designed to avoid weaknesses that can affect naïve keyed-hash implementations.
Hashed Message Authentication Code Example
Imagine an application sends this request body:
amount=125.00¤cy=USD&invoice=INV-1042Using a shared secret and HMAC-SHA-256, the sender generates a tag such as:
a1b2c3d4...The exact result is not important to the recipient until it recalculates the tag. If the request body is changed to amount=12.50, the recalculated HMAC will be entirely different. The recipient can reject the altered request.
HMAC vs. Hashing, Encryption, and Digital Signatures
These terms are often confused, but they solve different problems.
| Method | Main purpose | Uses a secret key? | Hides data? |
|---|---|---|---|
| Hash function | Detect accidental or intentional changes | No | No |
| HMAC | Verify integrity and a shared-secret sender | Yes | No |
| Encryption | Keep data confidential | Yes | Yes |
| Digital signature | Verify integrity and a public-key signer | Private key for signing | No |
A plain hash is not enough for authenticating API requests because anyone can calculate a hash of a modified message. HMAC solves this issue by requiring a secret key.
Hashed Message Authentication Code also differs from encryption. It proves that data has not been changed, but the message remains readable unless it is separately encrypted—for example, in transit with HTTPS.
Common Uses of Hashed Message Authentication Code
- API request signing – Many APIs require each request to include an HMAC signature. The signature is usually calculated from selected request fields, such as the HTTP method, URL path, timestamp, body, and a nonce. This helps services detect tampering and reject unauthorized requests.
- Webhook verification – Webhook providers commonly attach an HMAC signature in an HTTP header. The receiving application verifies the raw request body with its configured secret before acting on the event.
- Message queues and service-to-service communication – Distributed systems can use HMAC to confirm that messages crossing a queue, event bus, or internal service boundary were not modified by an unauthorized party.
- Token and cookie protection – Some systems use HMAC to make tamper-evident tokens, signed URLs, or session-related values. The verifier can check whether the value was issued by a trusted service without storing every issued token.
Which HMAC Algorithm Should You Use?
For most new applications, HMAC-SHA-256 is a sensible default. It is broadly supported, efficient, and well suited to modern security requirements.
Avoid choosing outdated hash algorithms for new designs. For instance, MD5 and SHA-1 have known cryptographic weaknesses and should generally be replaced in modern systems. NIST’s HMAC materials describe the construction and its relationship to approved hash functions.
HMAC Security Best Practices
Using Hashed Message Authentication Code correctly requires more than selecting a hash algorithm.
- Use strong, randomly generated secrets – Generate keys with a cryptographically secure random number generator. Do not use short passwords, predictable strings, source-code constants, or publicly visible identifiers as HMAC keys.
- Protect keys like passwords – Store HMAC secrets in a secrets manager or protected environment configuration. Never expose them in client-side applications, public repositories, logs, or error messages.
- Compare tags in constant time – When verifying an HMAC, use a constant-time comparison function provided by the platform’s cryptographic library. Ordinary equality comparisons may reveal timing information that can help attackers guess a valid tag.
- Sign the exact bytes you verify – For webhook verification, calculate the HMAC over the original raw request body. Parsing and reserializing JSON can change whitespace, field order, or character encoding, causing valid signatures to fail.
- Prevent replay attacks – HMAC alone does not stop an attacker from replaying a valid captured request. Include a timestamp, nonce, request ID, or sequence number in the signed data, then reject expired or previously used values.
- Rotate keys safely – Support key rotation by allowing a temporary overlap between an active key and its replacement. Identify the key version in the request when practical, and retire old keys on a defined schedule.
Final Takeaway
A hashed message authentication code is a practical, proven way to protect the integrity and authenticity of data shared between parties that hold the same secret. HMAC-SHA-256, strong secret management, constant-time verification, and replay protection provide a dependable foundation for signed API requests, webhooks, and service-to-service messages.