---
{
  "title": "Message authentication codes and HMAC",
  "summary": "Use a shared secret to verify message integrity and origin under that key.",
  "topic": "foundations",
  "level": "Intermediate",
  "updated": "2026-10-12",
  "units": [
    9
  ],
  "aliases": [],
  "sources": [
    {
      "title": "NIST: Message Authentication Codes",
      "url": "https://csrc.nist.gov/projects/message-authentication-codes"
    },
    {
      "title": "IETF RFC 2104: HMAC",
      "url": "https://www.rfc-editor.org/rfc/rfc2104.html"
    }
  ],
  "published": "2026-10-02",
  "editorialVersion": 2
}
---

## The idea

A message authentication code provides a tag computed using a secret key and message. HMAC is a construction using a cryptographic hash function. Verification checks the message under the same secret. Because both parties share the key, either can create valid tags; this differs from public-key signatures. Safe use requires key protection, appropriate parameters, and a protocol that addresses freshness when replay matters.

## In practice

Two services verify that a webhook payload was authenticated under their shared key before processing it, using the documented signing construction.

## A common misunderstanding

A bare hash is not a keyed authentication tag, and a MAC does not by itself prevent replay.

## Check your understanding

Why does HMAC not provide the same third-party verification model as a signature?

**Think it through:** Anyone holding the shared secret can produce the tag.

## Agree on the exact authenticated message

A fictional payment provider sends a webhook to a merchant service. Both hold a shared authentication secret. The receiver must verify the tag over the exact message representation defined by the provider's protocol. Reformatting JSON, changing whitespace, or selecting only some fields before verification can make the implementation disagree with that contract.

The protocol should also identify the event and its freshness. A genuine tag proves that the message matches the shared-key authentication calculation; it does not establish that the message has never been processed before. A captured valid webhook might otherwise trigger a duplicate business action. Event identifiers and appropriate replay handling belong in the surrounding design.

Shared keys create shared authority. Either holder can calculate a valid tag, so HMAC is not a way to prove to an unrelated third party which holder authored a disputed message. Use the right mechanism for the required trust model rather than treating every cryptographic authenticator as interchangeable.

## Trace verification before processing

For a local exercise, draw receipt of a dummy webhook, authentication verification, freshness checks, and the business update. State what happens if verification fails, if the event was already accepted, and if the event is valid but refers to an unknown order. Each case needs a deliberate outcome.

Keep secrets out of application logs and define a rotation procedure that handles legitimate messages during the transition. Use a maintained implementation and its supported comparison routine rather than creating a custom tag construction. The useful assurance comes from the complete message contract, protected key lifecycle, and controlled processing behavior, not simply from including a hash value beside a request.

## Keep exploring

- [[hashing]]
- [[digital-signatures]]
- [[replay-attacks]]
- [[key-management]]