HMAC-Generator

So funktioniert HMAC

HMAC (Hash-based Message Authentication Code, RFC 2104) kombiniert eine kryptografische Hashfunktion mit einem geheimen Schlüssel. Nur wer den Schlüssel kennt, kann für eine Nachricht den richtigen Wert erzeugen. Ein übereinstimmender HMAC belegt daher zweierlei: Die Nachricht wurde nicht verändert, und sie stammt von jemandem, der den Schlüssel besitzt.

Die Konstruktion lautet H((K ⊕ opad) ‖ H((K ⊕ ipad) ‖ message)). Ist der Schlüssel länger als die Blockgröße der Hashfunktion (64 Bytes bei MD5, SHA-1 und SHA-256, 128 bei SHA-384 und SHA-512), wird er zuerst gehasht. Dann wird er mit Nullen auf diese Größe aufgefüllt und per XOR einmal mit ipad (Bytes mit dem Wert 0x36) für einen inneren Hashwert über die Nachricht und einmal mit opad (Bytes mit dem Wert 0x5c) für einen äußeren Hashwert über das innere Ergebnis verknüpft. Einem naiven SHA-256(key ‖ message) fehlt dieser äußere Hashwert: Wer ein einziges Tag sieht, kann Daten an die Nachricht anhängen und ohne den Schlüssel ein gültiges neues Tag berechnen (Length-Extension-Angriff).

Die Ausgabe ist so lang wie der zugrunde liegende Hashwert: 32 Bytes oder 64 Hex-Zeichen bei HMAC-SHA256. RFC 2104 empfiehlt einen mindestens ebenso langen Schlüssel, und der Zufalls-Base64-Generator erzeugt passende Schlüssel.

Wo HMAC-Signaturen verwendet werden

• GitHub-Webhooks. Der Header X-Hub-Signature-256 besteht aus sha256=, gefolgt vom HMAC-SHA256 des rohen Request-Bodys in Hex, berechnet mit dem Webhook-Secret als Schlüssel. Sie können den gesamten Header-Wert unter „Vergleichen mit“ einfügen; das Präfix sha256= wird ignoriert.
• Stripe-Webhooks. Der Header Stripe-Signature enthält einen Zeitstempel t und eine Signatur v1: den HMAC-SHA256 in Hex über den Zeitstempel, einen Punkt und den rohen Body, berechnet mit dem Endpoint-Secret (whsec_...) als Text-Schlüssel.
• Shopify-Webhooks. X-Shopify-Hmac-Sha256 enthält den HMAC-SHA256 des rohen Bodys in Base64, berechnet mit dem Client-Secret der App als Schlüssel. Wählen Sie also unter „Ausgabe als“ „Base64“ oder fügen Sie den Header-Wert unter „Vergleichen mit“ ein.
• AWS Signature Version 4. Der Signaturschlüssel wird durch verkettetes HMAC-SHA256 abgeleitet: zuerst über das Datum mit AWS4 plus dem Secret Access Key als Schlüssel, dann über die Region, den Dienst und aws4_request, jeweils mit dem vorherigen Ergebnis als Schlüssel. Stellen Sie das „Schlüsselformat“ auf „Hex“, um die Ausgabe eines Schritts in den nächsten zu übernehmen.
• JSON Web Tokens. HS256, HS384 und HS512 sind HMAC-SHA256, -384 und -512 über den kodierten Header, einen Punkt und die kodierte Payload. Der dritte Teil des Tokens ist dieser HMAC in URL-sicherem Base64, den „Vergleichen mit“ unverändert akzeptiert. Der JWT-Decoder prüft vollständige Token.

Berechnen Sie den HMAC immer über den rohen Body, genau so, wie er empfangen wurde. Wird JSON geparst und erneut serialisiert, ändern sich Leerzeichen oder die Reihenfolge der Schlüssel, und schon ein zusätzlicher Zeilenumbruch ergibt einen völlig anderen HMAC.

HMAC im Code

# Python
import hmac, hashlib
sig = hmac.new(b'key', b'message', hashlib.sha256).hexdigest()
hmac.compare_digest(sig, received)        # Vergleich in konstanter Zeit

// Node.js
const crypto = require('crypto');
const sig = crypto.createHmac('sha256', 'key').update('message').digest('hex');
// timingSafeEqual wirft bei unterschiedlichen Längen einen Fehler, daher zuerst prüfen
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(received));

// PHP: die Nachricht steht vor dem Schlüssel
$sig = hash_hmac('sha256', 'message', 'key');
hash_equals($sig, $received);

# OpenSSL: ein Text-Schlüssel, dann derselbe Schlüssel als Hex
printf '%s' 'message' | openssl dgst -sha256 -hmac 'key'
printf '%s' 'message' | openssl dgst -sha256 -mac HMAC -macopt hexkey:6b6579

# Testvektor: Schlüssel "key", Nachricht "The quick brown fox jumps over the lazy dog"
# HMAC-SHA256 = f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8

Wenn Sie eine Signatur in Ihrem eigenen Code prüfen, verwenden Sie einen Vergleich in konstanter Zeit wie in den Beispielen oben. Ein einfaches == bricht beim ersten abweichenden Zeichen ab, und dieser Zeitunterschied kann es einem Angreifer ermöglichen, eine gültige Signatur Byte für Byte zu ermitteln. Lehnen Sie bei Verfahren mit Zeitstempel wie dem von Stripe außerdem Anfragen ab, deren Zeitstempel älter als einige Minuten ist; das verhindert Replay-Angriffe.