The Mathematical Architecture of HMAC & Message Authentication: RFC 2104, Keyed Hashes & Replay Attacks

[ Raw Secret Key K ] ──► [ Key Normalization Engine: Yields K' (length = B) ]
                                      │
            ┌─────────────────────────┴─────────────────────────┐
            ▼                                                   ▼
    [ K' XOR ipad (0x36) ]                              [ K' XOR opad (0x5C) ]
            │                                                   │
            ▼                                                   │
    [ Concatenate Message M ]                                   │
            │                                                   │
            ▼                                                   │
   [ Inner Hash H(K_in || M) ]                                  │
            │                                                   │
            └─────────────────────────┬─────────────────────────┘
                                      ▼
                        [ Concatenate Inner Hash ]
                                      │
                                      ▼
                        [ Outer Hash H(K_out || InnerHash) ]
                                      │
                                      ▼
                       [ Final HMAC Output: 256/512 bits ]

[ Attacker intercepts valid: Message M and Signature = H(K || M) ]
                               │
                               ▼
[ Attacker extracts internal state S_n directly from the Hash value! ]
                               │
                               ▼
[ Attacker appends malicious payload M_evil using valid padding ]
                               │
                               ▼
[ Attacker computes H(K || M || padding || M_evil) WITHOUT KNOWING KEY K! ]

POST /api/webhooks/stripe HTTP/1.1
Host: innoxtools.com
Stripe-Signature: t=1700000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Content-Type: application/json

{"id": "evt_3MjjZ2LkdIwHu7ix0r", "type": "payment_intent.succeeded", "amount": 29900}

// FATAL SECURITY BUG: Never verify signature on re-stringified JSON!
const payload = req.body; // Parsed JSON Object
const reconstructedString = JSON.stringify(payload);
const expectedSig = crypto.createHmac('sha256', secret).update(reconstructedString).digest('hex');

// Standard Insecure String Equality (Vulnerable to Timing Attacks)
int insecure_equals(const char* a, const char* b, size_t len) {
    for (size_t i = 0; i < len; i++) {
        if (a[i] != b[i]) {
            return 0; // Exits immediately on first byte mismatch!
        }
    }
    return 1;
}

// Cryptographically Secure Constant-Time Comparison
int timing_safe_equal(const uint8_t* a, const uint8_t* b, size_t len) {
    uint8_t result = 0;
    for (size_t i = 0; i < len; i++) {
        result |= (a[i] ^ b[i]); // Bitwise OR of XOR differences
    }
    return (result == 0); // Always iterates through all 'len' bytes!
}

import crypto from "crypto";

interface VerifyWebhookOptions {
  rawBody: Buffer;
  signatureHeader: string;
  secret: string;
  toleranceSeconds?: number;
}

export function verifyWebhookSignature({
  rawBody,
  signatureHeader,
  secret,
  toleranceSeconds = 300,
}: VerifyWebhookOptions): boolean {
  // 1. Parse header components (e.g., "t=1700000000,v1=5257a8...")
  const parts = signatureHeader.split(",");
  let timestamp = 0;
  let signatureHex = "";

  for (const part of parts) {
    const [key, value] = part.split("=");
    if (key === "t") timestamp = parseInt(value, 10);
    if (key === "v1") signatureHex = value;
  }

  if (!timestamp || !signatureHex) return false;

  // 2. Enforce Timestamp Window (Replay Attack Defense)
  const currentTimestamp = Math.floor(Date.now() / 1000);
  if (Math.abs(currentTimestamp - timestamp) > toleranceSeconds) {
    return false; // Request expired or future clock skew
  }

  // 3. Reconstruct Canonical Signed Payload
  const signedPayload = Buffer.concat([
    Buffer.from(timestamp.toString() + "."),
    rawBody,
  ]);

  // 4. Compute Expected HMAC-SHA256 Digest
  const expectedHmac = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest();

  const receivedHmac = Buffer.from(signatureHex, "hex");

  // 5. Constant-Time Cryptographic Comparison (Timing Attack Defense)
  if (expectedHmac.length !== receivedHmac.length) return false;
  return crypto.timingSafeEqual(expectedHmac, receivedHmac);
}