HMAC Signature

HMAC (Hash-based Message Authentication Code) is a cryptographic technique that uses a secret key and a hash function to verify both the authenticity and integrity of a message.

How HMAC Works

HMAC = Hash(secret_key + message)

Combine secret key with message

Apply hash function (e.g., SHA-256)

Result is the HMAC signature

Recipient recalculates and compares

HMAC in API Authentication

For each API request:

const signature = HMAC_SHA256(
  api_secret,
  timestamp + "." + method + "." + path + "." + body
);

Headers sent:

X-Signature: The HMAC signature

X-Timestamp: Unix timestamp

X-API-Key: Your API key

Security Properties

PropertyDescription

|----------|-------------|

AuthenticityOnly holder of secret can create valid signature IntegrityAny change to message invalidates signature Non-repudiationSender cannot deny creating the message

Common HMAC Algorithms

AlgorithmOutput SizeSecurity

|-----------|-------------|----------|

HMAC-SHA256256 bitsRecommended HMAC-SHA384384 bitsHigher security HMAC-SHA512512 bitsMaximum security

Verification Example

const crypto = require('crypto');
function verify(message, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Best Practices

Use timing-safe comparison: Prevent timing attacks

Include timestamp: Prevent replay attacks

Keep secrets secure: Never expose in client code

Rotate secrets: Change periodically

Related Terms

API Authentication

Webhooks

Crypto Payment Gateway

Learn More

Webhook Security Guide

API Authentication Guide