HMAC Generator & Verifier

What is HMAC? (Hash-based Message Authentication Code)

An HMAC (Hash-based Message Authentication Code) is a specific type of message authentication code (MAC) involving a cryptographic hash function and a secret cryptographic key. It is used to simultaneously verify both the data integrity and the authenticity of a message.

Unlike standard cryptographic hashes (like SHA-256 or MD5) which only detect accidental data corruption or modifications by unauthorized third parties, an HMAC uses a symmetric pre-shared key. This key ensures that only individuals who possess the secret key can generate or verify the signature, protecting communication channels against malicious spoofing and tampering.

HMAC is defined in RFC 2104 and has been widely adopted as an internet standard (FIPS PUB 198). It forms the cryptographic foundation of secure communications, including SSL/TLS, IPsec, SSH, and API request signing protocols used by major platforms such as AWS, Stripe, GitHub, and major payment gateways.

How HMAC Works: The Cryptographic Formula

Simply hashing a message concatenated with a key (e.g., $Hash(Key + Message)$) is vulnerable to a severe cryptographic vulnerability known as a length extension attack. In a length extension attack, an attacker who intercepts the hash and the length of the message can append extra data to the message and calculate a valid hash without ever knowing the secret key.

HMAC prevents this by hashing the key and the message in a nested, two-pass structure.

The HMAC Mathematical Formula:

$$\text{HMAC}(K, m) = H((K^+ \oplus \text{opad}) \parallel H((K^+ \oplus \text{ipad}) \parallel m))$$

Where:

• $H$ is a cryptographic hash function (e.g., SHA-256, SHA-512, MD5).
• $K$ is the secret key.
• $K^+$ is the key padded with zeros to match the block size of the hash function (or hashed first if it is longer than the block size).
• $m$ is the message to be authenticated.
• $\parallel$ denotes string concatenation.
• $\oplus$ denotes bitwise exclusive-OR (XOR).
• $\text{ipad}$ is the inner padding constant (repeated byte 0x36 to fill the block size).
• $\text{opad}$ is the outer padding constant (repeated byte 0x5c to fill the block size).

Step-by-Step Breakdown of the Two-Pass Execution:

1. Key Standardizing: If the secret key $K$ is longer than the block size of the hash function (e.g., 64 bytes for SHA-256), it is first hashed to produce a shorter key. If it is shorter, it is padded with trailing zeros to match the block size.
2. Inner Hashing: The standardized key $K^+$ is XORed with the inner pad constant ($\text{ipad}$). The resulting block is concatenated with the message $m$, and the chosen hash function hashes this combination: $H((K^+ \oplus \text{ipad}) \parallel m)$.
3. Outer Hashing: The standardized key $K^+$ is XORed with the outer pad constant ($\text{opad}$). The resulting block is concatenated with the inner hash output from Step 2, and hashed again: $H((K^+ \oplus \text{opad}) \parallel \text{Inner Hash})$.

This nested mechanism mathematically breaks the length extension property of Merkle-Damgård hash functions, making HMAC highly secure against truncation and extension attacks.

HMAC vs. Standard Hashing

A common point of confusion is the difference between a standard cryptographic hash and an HMAC. The table below highlights their differences:

| Feature | Standard Hash (e.g., SHA-256) | HMAC (e.g., HMAC-SHA256) | | :--- | :--- | :--- | | Inputs | Message only ($m$) | Message ($m$) + Secret Key ($K$) | | Purpose | Verification of data integrity (detects changes) | Verification of integrity AND authenticity (identity check) | | Vulnerabilities | Vulnerable to Length Extension Attacks | Immune to Length Extension Attacks | | Key Exchange | None required | Requires secure sharing of a symmetric secret key | | Primary Use Cases | File integrity checksums, database password storage | API Request signing, webhooks, secure tokens (JWTs) |

Supported Cryptographic Algorithms

This HMAC Generator supports four of the most widely used hashing algorithms, allowing you to select the appropriate balance of speed, performance, and security:

1. HMAC-SHA256

• Hash Family: SHA-2 (Secure Hash Algorithm 2)
• Output Length: 256 bits (32 bytes / 64 hex characters)
• Block Size: 64 bytes
• Security Level: Highly secure. It is the industry standard for API request signing, OAuth verification, and secure webhooks (used by Stripe, Slack, and GitHub).

2. HMAC-SHA512

• Hash Family: SHA-2
• Output Length: 512 bits (64 bytes / 128 hex characters)
• Block Size: 128 bytes
• Security Level: Extremely secure. Used for maximum data protection, high-security enterprise systems, and cryptocurrency transactions. It is also faster than SHA-256 on 64-bit hardware architectures.

3. HMAC-SHA1

• Hash Family: SHA-1
• Output Length: 160 bits (20 bytes / 40 hex characters)
• Block Size: 64 bytes
• Security Level: Legacy. While collision vulnerabilities make SHA-1 insecure for general certificates, HMAC-SHA1 remains secure because the secret key makes collision attacks impractical. It is still used in legacy APIs and systems like Git commit verification.

4. HMAC-MD5

• Hash Family: MD5 (Message Digest 5)
• Output Length: 128 bits (16 bytes / 32 hex characters)
• Block Size: 64 bytes
• Security Level: Deprecated / Weak. Although HMAC-MD5 is not directly vulnerable to the same collision attacks as pure MD5, it should only be used for compatibility with older legacy systems. Avoid it in new applications.

Real-World Web Developer Applications

HMAC is a core component of modern web architecture. Below are the most common application patterns:

1. Webhook Signature Verification

When a third-party service (like Stripe, PayPal, or GitHub) sends a webhook payload to your server, your server needs to verify that the webhook actually came from that provider and wasn't spoofed by an attacker.

• The provider hashes the JSON request body using a secret key they shared with you.
• The resulting signature is sent in a custom header (e.g., Stripe-Signature or X-Hub-Signature).
• Upon receiving the webhook, your server calculates the HMAC of the raw request body using the same secret key and compares it to the header. If they match, the request is authentic.

2. API Request Signing (AWS-Style Signature V4)

To prevent API keys from being intercepted over the network, services like Amazon Web Services (AWS) use HMAC signatures instead of sending API keys in headers.

• The client builds a canonical string representing the request (HTTP method, URI, query parameters, headers, and body hash).
• The client generates an HMAC signature of this canonical string using their API secret key.
• The signature and request parameters are sent to the server.
• The server reconstructs the canonical string, hashes it, and verifies the signature. This ensures the request was not altered in transit (integrity) and comes from a valid user (authenticity).

3. JSON Web Token (JWT) Signatures

JWTs consist of a Header, a Payload, and a Signature separated by dots (e.g., header.payload.signature).

• When using the HS256 algorithm, the signature is computed as: $$\text{Signature} = \text{HMAC-SHA256}(\text{Base64Url}(\text{Header}) + "." + \text{Base64Url}(\text{Payload}), \text{Secret})$$
• This prevents users from altering their JWT claims (like changing their role to "admin") because doing so would invalidate the signature, which can only be recomputed by the server holding the secret key.

HMAC Best Practices for Developers

To maintain high cryptographic security, follow these best practices in your applications:

1. Use Strong Symmetric Keys: Generate keys using a cryptographically secure random number generator (CSPRNG). Ensure the key size matches or exceeds the output length of the hash function (e.g., at least 256 bits or 32 random bytes for HMAC-SHA256).
2. Prevent Timing Attacks: When verifying signatures on your server, do not use standard string comparison operators (e.g., if (signature == expectedSignature)). Normal comparisons exit early on the first mismatched character, allowing attackers to guess the signature byte-by-byte by measuring response times. Always use a constant-time comparison library (e.g., crypto.timingSafeEqual in Node.js).
3. Include Timestamps: Always sign a timestamp along with your message payload. This allows your server to reject signatures that are too old, preventing replay attacks where an attacker intercepts a valid signed request and resends it later.
4. Use Raw Request Bodies: When signing webhook or API requests, always use the raw request body string. Hashing parsed JSON objects can result in verification failures due to varying object key order, spacing, or newline normalization.
5. Rotate Secrets Regularly: Establish a policy to rotate secret signing keys periodically. In the event of a key leak, rotation limits the window of opportunity for an attacker.

Common Mistakes Developers Make

• Storing Keys in Code: Hardcoding API secrets or HMAC signing keys directly into version-controlled repositories is a major security risk. Use environment variables and store keys in secure vaults (like AWS Secrets Manager, Vault, or GCP Secret Manager).
• Using Fast Hashing for Passwords: HMAC is designed for message verification, not database password storage. Storing user passwords hashed with HMAC makes them vulnerable to rapid offline dictionary attacks. Use slow, key-derivation algorithms like Argon2id or bcrypt for password storage.
• Signing Unsanitized Inputs: If you sign concatenated strings, ensure you use a safe delimiter (like a colon or null byte) to prevent canonicalization attacks (where two different parameter configurations result in the same concatenated signature string).