Hash Comparison API: The Complete Guide

Need to compare hash values securely? This guide covers everything about timing-safe hash comparison via API, including why timing attacks matter, how to prevent them, and implementation examples.

Why Timing-Safe Comparison?

Standard string comparison functions (like === or ==) stop comparing as soon as they find a difference. This creates a timing side-channel that attackers can exploit.

By measuring response times, an attacker can guess the correct hash one character at a time, dramatically reducing the search space from astronomical to trivial.

How It Works

Timing-safe comparison always takes the same amount of time regardless of where (or if) the strings differ:

Constant-Time Algorithm

• Compare every byte, even after finding a difference
• Use bitwise XOR to accumulate differences
• Return result only after comparing all bytes

Using the Hash Comparison API

TinyFn provides a secure endpoint for hash comparison:

POST https://api.tinyfn.io/v1/hash/compare
Headers: X-API-Key: your-api-key
Content-Type: application/json

{
  "hash1": "5d41402abc4b2a76b9719d911017c592",
  "hash2": "5d41402abc4b2a76b9719d911017c592"
}

{
  "match": true,
  "timing_safe": true,
  "hash_length": 32
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/hash/compare',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      hash1: '5d41402abc4b2a76b9719d911017c592',
      hash2: expectedHash
    })
  }
);
const { match } = await response.json();
if (match) {
  console.log('Hash verified successfully!');
} else {
  console.log('Hash mismatch!');
}

Python

import requests

response = requests.post(
    'https://api.tinyfn.io/v1/hash/compare',
    headers={'X-API-Key': 'your-api-key'},
    json={
        'hash1': '5d41402abc4b2a76b9719d911017c592',
        'hash2': expected_hash
    }
)
result = response.json()
if result['match']:
    print('Hash verified successfully!')
else:
    print('Hash mismatch!')

cURL

curl -X POST "https://api.tinyfn.io/v1/hash/compare" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "hash1": "5d41402abc4b2a76b9719d911017c592",
    "hash2": "5d41402abc4b2a76b9719d911017c592"
  }'

Common Use Cases

• Webhook Verification: Verify webhook signatures from services like Stripe, GitHub
• API Token Validation: Securely verify API tokens against stored hashes
• File Integrity: Verify file checksums against expected values
• HMAC Verification: Validate HMAC signatures in authentication flows
• Password Reset Tokens: Verify password reset token hashes

Best Practices

1. Always use for security: Any hash comparison involving secrets should be timing-safe
2. Compare same lengths: Ensure both hashes are the same length before comparing
3. Normalize case: Hash hex strings should be compared case-insensitively
4. Log failures carefully: Don't log hash values in error messages

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-hash": {
      "url": "https://api.tinyfn.io/mcp/hash/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all hash tools available via MCP in our Hash MCP Tools for AI Agents guide.