HMAC-generator

Zo werkt HMAC

HMAC (hash-based message authentication code, RFC 2104) combineert een cryptografische hash met een geheime sleutel. Alleen wie de sleutel kent, kan de juiste waarde voor een bericht berekenen. Een overeenkomende HMAC bewijst dus twee dingen tegelijk: het bericht is niet gewijzigd, en het komt van iemand die de sleutel heeft.

De constructie is H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ message)). De sleutel wordt eerst gehasht als hij langer is dan de blokgrootte van de hash (64 bytes voor MD5, SHA-1 en SHA-256, 128 voor SHA-384 en SHA-512), dan met nullen aangevuld tot die grootte, en vervolgens met XOR gecombineerd met ipad (bytes 0x36) voor een binnenste hash over het bericht en met opad (bytes 0x5c) voor een buitenste hash over het binnenste resultaat. Een naïeve constructie als SHA-256(key ‖ message) heeft geen buitenste hash. Wie één tag ziet, kan dan gegevens aan het bericht toevoegen en zonder de sleutel een geldige nieuwe tag berekenen (een length-extension-aanval).

De uitvoer heeft de lengte van de onderliggende hash: 32 bytes, of 64 hextekens, voor HMAC-SHA256. RFC 2104 raadt een sleutel aan die minstens zo lang is, en de generator voor willekeurige Base64 maakt geschikte sleutels.

Waar HMAC-handtekeningen worden gebruikt

• GitHub-webhooks. De header X-Hub-Signature-256 bestaat uit sha256=, gevolgd door de HMAC-SHA256 in hex van de ruwe body van het verzoek, met het webhookgeheim als sleutel. Je kunt de volledige headerwaarde in het veld Vergelijken met plakken; het voorvoegsel sha256= wordt genegeerd.
• Stripe-webhooks. De header Stripe-Signature bevat een tijdstempel t en een handtekening v1: de HMAC-SHA256 in hex van de tijdstempel, een punt en de ruwe body, met als sleutel het endpointgeheim (whsec_...), ingevoerd als tekst.
• Shopify-webhooks. X-Shopify-Hmac-Sha256 bevat de HMAC-SHA256 van de ruwe body in Base64, met het client secret van de app als sleutel. Kies dus Base64 als uitvoer of plak de headerwaarde in het veld Vergelijken met.
• AWS Signature Version 4. De ondertekeningssleutel wordt afgeleid door HMAC-SHA256 aan elkaar te schakelen: eerst de datum, met als sleutel AWS4 plus de secret access key, en daarna de regio, de service en aws4_request, telkens met het vorige resultaat als sleutel. Zet Sleutelformaat op Hex om de uitvoer van de ene stap in de volgende te gebruiken.
• JSON Web Tokens. HS256, HS384 en HS512 zijn HMAC-SHA256, -384 en -512 over de gecodeerde header, een punt en de gecodeerde payload. Het derde deel van het token is die HMAC in URL-veilige Base64, en het veld Vergelijken met accepteert die ongewijzigd. De JWT-decoder verifieert volledige tokens.

Bereken de HMAC altijd over de ruwe body, precies zoals die is ontvangen. JSON parsen en opnieuw serialiseren verandert de spaties of de volgorde van de sleutels, en zelfs één extra regeleinde geeft een totaal andere HMAC.

HMAC berekenen in code

# Python
import hmac, hashlib
sig = hmac.new(b'key', b'message', hashlib.sha256).hexdigest()
hmac.compare_digest(sig, received)        # vergelijking in constante tijd

// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', 'key').update('message').digest('hex');
// timingSafeEqual geeft een fout als de lengtes verschillen, controleer die dus eerst
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(received));

// PHP: het bericht komt vóór de sleutel
$sig = hash_hmac('sha256', 'message', 'key');
hash_equals($sig, $received);

# OpenSSL: een sleutel als tekst, daarna dezelfde sleutel als hex
printf '%s' 'message' | openssl dgst -sha256 -hmac 'key'
printf '%s' 'message' | openssl dgst -sha256 -mac HMAC -macopt hexkey:6b6579

# Testvector: sleutel "key", bericht "The quick brown fox jumps over the lazy dog"
# HMAC-SHA256 = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8

Gebruik een vergelijking in constante tijd zoals hierboven als je in je eigen code een handtekening verifieert. Een gewone == stopt bij het eerste teken dat verschilt, en met dat tijdsverschil kan een aanvaller byte voor byte een geldige handtekening vinden. Weiger bij schema's met een tijdstempel, zoals dat van Stripe, ook verzoeken waarvan de tijdstempel meer dan een paar minuten oud is; zo blokkeer je replay-aanvallen.