How to Use HMAC for Authentication

Problem

You need to prove that a message or API request was sent by someone who knows a shared secret key, and that it was not modified in transit.

Prerequisites

• Understanding of hash functions
• Knowledge of shared secret keys

Steps

1. 1. Prepare the message and key

   Define the message to authenticate (e.g., an API request body or a timestamp + payload). Agree on a secret key with the other party. The key should be at least as long as the hash output (32 bytes for HMAC-SHA256).

   Input

   message: 'payload' | key: 'secret'

   Output

   ready to sign

2. 2. Compute the HMAC

   Run HMAC-SHA256 with the key and message. HMAC wraps the hash function with key mixing, producing a tag that only someone with the key can compute. The tag is typically sent as a hex or Base64 string alongside the message.

   Input

   HMAC-SHA256(key, message)

   Output

   tag: a1b2c3...

3. 3. Verify on the receiving end

   The recipient recomputes the HMAC with the same key and message and compares it to the received tag using a constant-time comparison. If they match, the message is authentic and unmodified. If they differ, reject the message.

   Input

   recomputed tag == received tag

   Output

   verified ✓

Expected result

An HMAC tag that authenticates the message source and integrity, verifiable by anyone with the shared key.

Common errors

Comparing tags with a non-constant-time comparison

Use a constant-time comparison (e.g., crypto.timingSafeEqual) to prevent timing attacks that leak the tag byte by byte.

Including the key in the message

The key is never sent. Only the message and the HMAC tag are transmitted. The key stays on both sides.

Troubleshooting

• If verification fails, check that the message is byte-identical on both sides (no encoding differences).
• Include a timestamp or nonce in the message to prevent replay attacks.

Security limits

• HMAC security depends on the secrecy of the key and the collision resistance of the underlying hash. Use SHA-256 or stronger.
• All computation is local.