HMAC Generator Guide: Secure Message Authentication

HMAC Algorithm (Simplified):

1. Pad the secret key to the hash block size
2. XOR the padded key with ipad (inner padding)
3. Append the message to the XORed key
4. Hash the result with the selected hash function
5. XOR the padded key with opad (outer padding)
6. Append the hash from step 4 to the XORed key
7. Hash the result with the selected hash function
8. The final hash is the HMAC value

Mathematically:
HMAC = Hash(key XOR opad, Hash(key XOR ipad, message))

Where:
- ipad is 0x36 repeated for the block size
- opad is 0x5C repeated for the block size

Algorithm        | Output Size | Speed   | Security Status | Usage
                 |             |         |                |
HMAC-MD5         | 128 bits    | Fast    | Broken          | ❌ Avoid
HMAC-SHA1        | 160 bits    | Fast    | Weak            | ⚠️ Legacy only
HMAC-SHA224      | 224 bits    | Good    | Secure          | ✓ Can use
HMAC-SHA256      | 256 bits    | Good    | Secure          | ✓ Recommended
HMAC-SHA384      | 384 bits    | Slower  | Very Secure     | ✓ Can use
HMAC-SHA512      | 512 bits    | Slower  | Very Secure     | ✓ Maximum security
HMAC-SHA3-256    | 256 bits    | Good    | Very Secure     | ✓ Future standard

// Browser: Using SubtleCrypto (WebCrypto API)
async function generateHMAC(message, secretKey) {
  // Encode strings to bytes
  const encoder = new TextEncoder();
  const messageBytes = encoder.encode(message);
  const keyBytes = encoder.encode(secretKey);

  // Import the key
  const importedKey = await crypto.subtle.importKey(
    'raw',
    keyBytes,
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );

  // Generate HMAC
  const hmacBuffer = await crypto.subtle.sign('HMAC', importedKey, messageBytes);

  // Convert to hex string
  const hmacArray = Array.from(new Uint8Array(hmacBuffer));
  return hmacArray.map(b => b.toString(16).padStart(2, '0')).join('');
}

// Usage
const secret = 'my-secret-key';
const message = 'authenticate this message';

generateHMAC(message, secret).then(hmac => {
  console.log('HMAC:', hmac);
});

// Verify HMAC
async function verifyHMAC(message, secretKey, expectedHmac) {
  const computed = await generateHMAC(message, secretKey);
  return constantTimeCompare(computed, expectedHmac);
}

import hmac
import hashlib

def generate_hmac(message, secret_key, algorithm='sha256'):
    """Generate HMAC for a message with a secret key."""
    # Encode strings to bytes if necessary
    if isinstance(message, str):
        message = message.encode('utf-8')
    if isinstance(secret_key, str):
        secret_key = secret_key.encode('utf-8')

    # Create HMAC
    h = hmac.new(secret_key, message, getattr(hashlib, algorithm))
    return h.hexdigest()

def verify_hmac(message, secret_key, expected_hmac, algorithm='sha256'):
    """Verify HMAC signature."""
    computed = generate_hmac(message, secret_key, algorithm)
    # Use constant-time comparison
    return hmac.compare_digest(computed, expected_hmac)

# Usage
secret = 'my-secret-key'
message = 'authenticate this message'

# Generate HMAC
hmac_value = generate_hmac(message, secret)
print(f'HMAC: {hmac_value}')

# Verify HMAC
is_valid = verify_hmac(message, secret, hmac_value)
print(f'Valid: {is_valid}')

# With different algorithms
hmac_sha512 = generate_hmac(message, secret, 'sha512')
print(f'HMAC-SHA512: {hmac_sha512}')

const crypto = require('crypto');

function generateHMAC(message, secretKey, algorithm = 'sha256') {
  const hmac = crypto.createHmac(algorithm, secretKey);
  hmac.update(message);
  return hmac.digest('hex');
}

function verifyHMAC(message, secretKey, expectedHmac, algorithm = 'sha256') {
  const computed = generateHMAC(message, secretKey, algorithm);
  // Use timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(expectedHmac)
  );
}

// Usage
const secret = 'my-secret-key';
const message = 'authenticate this message';

// Generate HMAC
const hmac = generateHMAC(message, secret);
console.log('HMAC:', hmac);

// Verify HMAC
try {
  const isValid = verifyHMAC(message, secret, hmac);
  console.log('Valid:', isValid);
} catch (error) {
  console.error('Invalid HMAC');
}

// Multiple algorithms
console.log('HMAC-SHA1:', generateHMAC(message, secret, 'sha1'));
console.log('HMAC-SHA512:', generateHMAC(message, secret, 'sha512'));

<?php

function generateHMAC($message, $secretKey, $algorithm = 'sha256') {
    return hash_hmac($algorithm, $message, $secretKey);
}

function verifyHMAC($message, $secretKey, $expectedHmac, $algorithm = 'sha256') {
    $computed = generateHMAC($message, $secretKey, $algorithm);
    // Use hash_equals for timing-safe comparison
    return hash_equals($computed, $expectedHmac);
}

// Usage
$secret = 'my-secret-key';
$message = 'authenticate this message';

// Generate HMAC
$hmac = generateHMAC($message, $secret);
echo "HMAC: $hmac\n";

// Verify HMAC
$isValid = verifyHMAC($message, $secret, $hmac);
echo "Valid: " . ($isValid ? 'true' : 'false') . "\n";

// Different algorithms
echo "HMAC-SHA1: " . generateHMAC($message, $secret, 'sha1') . "\n";
echo "HMAC-SHA512: " . generateHMAC($message, $secret, 'sha512') . "\n";

// Available algorithms
$algorithms = hash_algos();
echo "Available: " . implode(', ', array_filter($algorithms,
    fn($a) => strpos($a, 'sha') === 0));
?>

const crypto = require('crypto');

// Webhook receiver function
function handleWebhook(request, response) {
  const signature = request.headers['x-webhook-signature'];
  const timestamp = request.headers['x-webhook-timestamp'];
  const body = request.rawBody; // Raw request body as string
  const webhookSecret = process.env.WEBHOOK_SECRET;

  // Check timestamp (prevent replay attacks)
  const maxAge = 5 * 60; // 5 minutes in seconds
  const requestTime = parseInt(timestamp);
  const currentTime = Math.floor(Date.now() / 1000);

  if (currentTime - requestTime > maxAge) {
    return response.status(401).json({ error: 'Request too old' });
  }

  // Create signed content
  const signedContent = `${timestamp}.${body}`;

  // Generate expected signature
  const hmac = crypto.createHmac('sha256', webhookSecret);
  hmac.update(signedContent);
  const expectedSignature = hmac.digest('hex');

  // Verify signature (timing-safe)
  try {
    const isValid = crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expectedSignature)
    );

    if (!isValid) {
      return response.status(401).json({ error: 'Invalid signature' });
    }

    // Process webhook
    const data = JSON.parse(body);
    console.log('Webhook verified:', data);

    response.json({ success: true });
  } catch (error) {
    response.status(401).json({ error: 'Invalid signature' });
  }
}

// Express middleware
const express = require('express');
const app = express();

// Important: Use raw body, not parsed JSON
app.post('/webhook', express.raw({ type: 'application/json' }), handleWebhook);

const crypto = require('crypto');
const https = require('https');

function signRequest(method, path, body, apiKey, apiSecret) {
  // Create signing string
  const timestamp = Math.floor(Date.now() / 1000);
  const nonceRandom = Math.random().toString(36).substring(7);
  const bodyString = typeof body === 'string' ? body : JSON.stringify(body);

  // Build message to sign
  const message = `${method}\n${path}\n${timestamp}\n${nonceRandom}\n${bodyString}`;

  // Generate signature
  const hmac = crypto.createHmac('sha256', apiSecret);
  hmac.update(message);
  const signature = hmac.digest('base64');

  return {
    signature,
    timestamp,
    nonce: nonceRandom,
    authHeader: `HMAC-SHA256 KeyId=${apiKey} Signature=${signature}`
  };
}

function makeAuthenticatedRequest(options, body) {
  const { signature, authHeader, timestamp, nonce } = signRequest(
    options.method,
    options.path,
    body,
    process.env.API_KEY,
    process.env.API_SECRET
  );

  const request = https.request({
    ...options,
    headers: {
      ...options.headers,
      'Authorization': authHeader,
      'X-Timestamp': timestamp,
      'X-Nonce': nonce,
      'Content-Type': 'application/json'
    }
  }, (response) => {
    let data = '';
    response.on('data', chunk => data += chunk);
    response.on('end', () => console.log(data));
  });

  if (body) {
    request.write(JSON.stringify(body));
  }
  request.end();
}

// Usage
const requestBody = { action: 'transfer', amount: 100 };
makeAuthenticatedRequest(
  { method: 'POST', path: '/api/transfer', hostname: 'api.example.com' },
  requestBody
);

API Authentication Flow with HMAC:

1. CLIENT SIDE - Signing Request
   ├─ Create request body
   ├─ Generate timestamp
   ├─ Create signing string (method + path + timestamp + body)
   ├─ Generate HMAC-SHA256(signing string, secret key)
   ├─ Include HMAC in Authorization header
   └─ Send request to server

2. NETWORK
   └─ HTTPS/TLS encryption (transport security)

3. SERVER SIDE - Verifying Request
   ├─ Extract HMAC from Authorization header
   ├─ Get raw request body
   ├─ Check timestamp is within acceptable range
   ├─ Reconstruct signing string
   ├─ Generate expected HMAC-SHA256
   ├─ Compare with received HMAC (timing-safe)
   ├─ If valid: process request
   └─ If invalid: return 401 Unauthorized

Example Request:
  POST /api/transfer HTTP/1.1
  Authorization: HMAC-SHA256 KeyId=client_123 Signature=abc123...
  X-Timestamp: 1640100000
  Content-Type: application/json

  {"action": "transfer", "amount": 100}

const crypto = require('crypto');

function verifyStripeWebhook(body, signature, endpointSecret) {
  // Stripe expects raw body string, not parsed JSON

  // Create signed content (timestamp.payload)
  const parts = signature.split(',');
  const timestamp = parts[0].split('=')[1];
  const receivedSignature = parts[1].split('=')[1];

  // Reconstruct signed content
  const signedContent = `${timestamp}.${body}`;

  // Generate expected signature
  const hmac = crypto.createHmac('sha256', endpointSecret);
  hmac.update(signedContent);
  const expectedSignature = hmac.digest('hex');

  // Verify signature
  return crypto.timingSafeEqual(
    Buffer.from(receivedSignature),
    Buffer.from(expectedSignature)
  );
}

// Express middleware for Stripe webhooks
const express = require('express');
const bodyParser = require('body-parser');

const app = express();

// Important: Use raw body for Stripe
app.post('/webhook/stripe',
  bodyParser.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['stripe-signature'];
    const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;

    try {
      const event = JSON.parse(req.body);

      if (!verifyStripeWebhook(req.body, sig, endpointSecret)) {
        return res.status(401).json({ error: 'Invalid signature' });
      }

      // Handle event
      switch(event.type) {
        case 'payment_intent.succeeded':
          console.log('Payment succeeded:', event.data.object.id);
          break;
        case 'charge.refunded':
          console.log('Charge refunded:', event.data.object.id);
          break;
      }

      res.json({ received: true });
    } catch (error) {
      res.status(400).send(`Webhook error: ${error.message}`);
    }
  }
);

const crypto = require('crypto');

function awsSignatureVersion4(method, host, path, queryString, payload, accessKey, secretKey, region = 'us-east-1') {
  // Step 1: Create canonical request
  const hashedPayload = crypto
    .createHash('sha256')
    .update(payload || '')
    .digest('hex');

  const canonicalRequest = `${method}
${path}
${queryString}
host:${host}
x-amz-content-sha256:${hashedPayload}
x-amz-date:${getAmzDate()}

host;x-amz-content-sha256;x-amz-date
${hashedPayload}`;

  // Step 2: Create string to sign
  const hashedCanonical = crypto
    .createHash('sha256')
    .update(canonicalRequest)
    .digest('hex');

  const amzDate = getAmzDate();
  const dateStamp = amzDate.split('T')[0];
  const credentialScope = `${dateStamp}/${region}/s3/aws4_request`;

  const stringToSign = `AWS4-HMAC-SHA256
${amzDate}
${credentialScope}
${hashedCanonical}`;

  // Step 3: Calculate signature
  const kSecret = `AWS4${secretKey}`;
  const kDate = crypto.createHmac('sha256', kSecret)
    .update(dateStamp).digest();
  const kRegion = crypto.createHmac('sha256', kDate)
    .update(region).digest();
  const kService = crypto.createHmac('sha256', kRegion)
    .update('s3').digest();
  const kSigning = crypto.createHmac('sha256', kService)
    .update('aws4_request').digest();

  const signature = crypto.createHmac('sha256', kSigning)
    .update(stringToSign)
    .digest('hex');

  return {
    amzDate,
    dateStamp,
    credentialScope,
    signature,
    authHeader: `AWS4-HMAC-SHA256 Credential=${accessKey}/${credentialScope}, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=${signature}`
  };
}

function getAmzDate() {
  const now = new Date();
  return now.toISOString().replace(/[:-]/g, '').replace(/\.\d{3}/, '');
}

const crypto = require('crypto');

function verifyGitHubWebhook(payload, signature, secret) {
  // GitHub format: sha256=hexdigest
  const [algorithm, expected] = signature.split('=');

  if (algorithm !== 'sha256') {
    throw new Error('Unsupported signature algorithm');
  }

  // Create HMAC using raw body (string)
  const computed = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  // Use timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(expected)
  );
}

// Express endpoint for GitHub webhooks
const express = require('express');
const app = express();

app.post('/webhook/github',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-hub-signature-256'];
    const secret = process.env.GITHUB_WEBHOOK_SECRET;

    // req.body is a Buffer when using express.raw()
    const payload = req.body.toString();

    try {
      if (!verifyGitHubWebhook(payload, signature, secret)) {
        return res.status(401).json({ error: 'Invalid signature' });
      }

      const event = JSON.parse(payload);
      const eventType = req.headers['x-github-event'];

      // Handle different event types
      switch(eventType) {
        case 'push':
          console.log('Push event from', event.repository.full_name);
          console.log('Commits:', event.commits.length);
          break;
        case 'pull_request':
          console.log('PR event:', event.action, event.pull_request.number);
          break;
        case 'issues':
          console.log('Issue event:', event.action, event.issue.number);
          break;
      }

      res.json({ received: true });
    } catch (error) {
      res.status(400).json({ error: error.message });
    }
  }
);

// Complete custom API authentication system

const crypto = require('crypto');

class ApiAuthenticator {
  constructor(apiKey, apiSecret) {
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
  }

  // Sign a request
  signRequest(method, path, body = null) {
    const timestamp = Math.floor(Date.now() / 1000);
    const bodyString = body ? JSON.stringify(body) : '';

    // Create signature string
    const signatureString = `${method}\n${path}\n${timestamp}\n${bodyString}`;

    // Generate HMAC
    const signature = crypto
      .createHmac('sha256', this.apiSecret)
      .update(signatureString)
      .digest('base64');

    return {
      headers: {
        'Authorization': `Bearer ${this.apiKey}:${signature}`,
        'X-Timestamp': timestamp.toString(),
        'Content-Type': 'application/json'
      },
      body: bodyString
    };
  }

  // Verify a webhook
  verifyWebhook(body, signature, timestamp) {
    // Check timestamp freshness
    const requestTime = parseInt(timestamp);
    const currentTime = Math.floor(Date.now() / 1000);
    if (currentTime - requestTime > 300) { // 5 minutes
      return false;
    }

    // Reconstruct signature
    const signatureString = `${timestamp}\n${body}`;
    const expectedSignature = crypto
      .createHmac('sha256', this.apiSecret)
      .update(signatureString)
      .digest('base64');

    // Timing-safe comparison
    try {
      return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expectedSignature)
      );
    } catch {
      return false;
    }
  }
}

// Usage
const auth = new ApiAuthenticator('key_123', 'secret_xyz');

// Signing a request
const request = auth.signRequest('POST', '/api/users', { name: 'John' });
console.log('Authorization:', request.headers.Authorization);

// Verifying a webhook (Express middleware)
const express = require('express');
app.post('/webhook', express.json(), (req, res) => {
  const signature = req.headers['x-signature'];
  const timestamp = req.headers['x-timestamp'];
  const body = JSON.stringify(req.body);

  if (auth.verifyWebhook(body, signature, timestamp)) {
    console.log('Webhook verified');
    res.json({ success: true });
  } else {
    res.status(401).json({ error: 'Invalid signature' });
  }
});

const crypto = require('crypto');

// WRONG - Simple string comparison (vulnerable to timing attacks)
function verifyHMACWrong(computed, received) {
  return computed === received; // ❌ Don't use this!
}

// CORRECT - Timing-safe comparison (Node.js)
function verifyHMACCorrect(computed, received) {
  try {
    return crypto.timingSafeEqual(
      Buffer.from(computed),
      Buffer.from(received)
    );
  } catch {
    // Buffers have different lengths
    return false;
  }
}

// Browser environment - manual constant-time comparison
function verifyHMACBrowser(computed, received) {
  if (computed.length !== received.length) {
    return false;
  }

  let mismatch = 0;
  for (let i = 0; i < computed.length; i++) {
    mismatch |= computed.charCodeAt(i) ^ received.charCodeAt(i);
  }

  return mismatch === 0;
}

// Complete webhook verification
async function processWebhook(request, secret) {
  const receivedSignature = request.headers['x-signature'];
  const rawBody = await request.text();

  // Generate expected signature
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(rawBody);
  const expectedSignature = hmac.digest('hex');

  // Verify using constant-time comparison
  if (!verifyHMACCorrect(expectedSignature, receivedSignature)) {
    throw new Error('Invalid signature');
  }

  // Process verified webhook
  const data = JSON.parse(rawBody);
  return data;
}

// Why timing-safe comparison matters:
// Simple string comparison (=== or ==) takes less time
// when strings differ early. Attacker can exploit this
// timing difference to forge valid HMACs.

// Example vulnerable code:
function unsafeCompare(a, b) {
  return a === b; // Returns quickly if first chars differ
}

// Timing-safe implementations:

// 1. Node.js crypto.timingSafeEqual
const crypto = require('crypto');
function compareWithCrypto(a, b) {
  try {
    return crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
  } catch {
    return false; // Different lengths
  }
}

// 2. Manual implementation (browser/pure JS)
function constantTimeCompare(a, b) {
  if (a.length !== b.length) {
    return false;
  }

  let mismatch = 0;
  for (let i = 0; i < a.length; i++) {
    // XOR: different chars give 1, same chars give 0
    mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
  }

  return mismatch === 0;
}

// 3. Using subtle crypto (browser)
async function compareWithSubtle(a, b) {
  const aBuffer = new TextEncoder().encode(a);
  const bBuffer = new TextEncoder().encode(b);

  if (aBuffer.length !== bBuffer.length) {
    return false;
  }

  let result = 0;
  for (let i = 0; i < aBuffer.length; i++) {
    result |= aBuffer[i] ^ bBuffer[i];
  }

  return result === 0;
}

// Testing
const validHmac = 'abc123def456';
const invalidHmac1 = 'xyz789def456'; // Different start
const invalidHmac2 = 'abc123def457'; // Different end

console.log(constantTimeCompare(validHmac, validHmac)); // true
console.log(constantTimeCompare(validHmac, invalidHmac1)); // false
console.log(constantTimeCompare(validHmac, invalidHmac2)); // false

// 1. crypto-js (popular but deprecated for new projects)
// npm install crypto-js
import CryptoJS from 'crypto-js';

const secret = 'secret-key';
const message = 'message to sign';

const hmac = CryptoJS.HmacSHA256(message, secret);
console.log(hmac.toString()); // hex string

// 2. Node.js built-in crypto (recommended)
const crypto = require('crypto');

const hmac = crypto.createHmac('sha256', secret);
hmac.update(message);
console.log(hmac.digest('hex'));

// 3. tweetnacl-js (libsodium binding)
// npm install tweetnacl
const nacl = require('tweetnacl');

const secretKey = nacl.utils.randomBytes(32);
const msg = new TextEncoder().encode(message);
const hmacValue = nacl.sign.detached(msg, secretKey);

// 4. TweetNaCl (simpler for browser)
// Use built-in SubtleCrypto instead (see earlier examples)

// 5. bcrypt (not HMAC, but for password hashing)
// npm install bcrypt
const bcrypt = require('bcrypt');

const hash = await bcrypt.hash(password, 10);
const isValid = await bcrypt.compare(password, hash);

# 1. Built-in hmac module (recommended)
import hmac
import hashlib

secret = b'secret-key'
message = b'message to sign'

# Generate HMAC
hmac_value = hmac.new(secret, message, hashlib.sha256).hexdigest()
print(hmac_value)

# Verify HMAC
is_valid = hmac.compare_digest(hmac_value, expected_hmac)

# 2. cryptography library
# pip install cryptography
from cryptography.hazmat.primitives import hashes, hmac
from cryptography.hazmat.backends import default_backend

key = b'secret-key'
msg = b'message'

h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend())
h.update(msg)
signature = h.finalize()
print(signature.hex())

# 3. PyJWT (for JWT authentication)
# pip install pyjwt
import jwt

secret = 'secret-key'
payload = {'user_id': 123, 'username': 'john'}

token = jwt.encode(payload, secret, algorithm='HS256')
decoded = jwt.decode(token, secret, algorithms=['HS256'])

# 4. requests with auth
# pip install requests
from requests.auth import HTTPBasicAuth
import requests

# requests handles basic auth with HMAC-like behavior
response = requests.get('https://api.example.com/data',
                       auth=HTTPBasicAuth('user', 'pass'))

# 5. Flask with custom authentication
from flask import Flask, request
from functools import wraps

def verify_signature(f):
    @wraps(f)
    def decorated_function(*args, **kwargs):
        signature = request.headers.get('X-Signature')
        # Verify HMAC here
        return f(*args, **kwargs)
    return decorated_function