HMAC-SHA256-Signatur prüfen: Abweichende Werte richtig finden

Inhalt
Wenn die HMAC-Signatur, die per Webhook oder in einer API-Antwort bei Ihnen ankommt, von Ihrem selbst berechneten Wert abweicht, steckt dahinter meist kein Sicherheitsvorfall. Fast immer unterscheidet sich eine der drei Eingaben minimal: Nachricht, geheimer Schlüssel oder Hash-Algorithmus. Nur wenn alle drei exakt übereinstimmen, entsteht dieselbe Signatur.
In diesem Beitrag zeige ich anhand tatsächlich berechneter Werte, was Sie bei einer nicht passenden Signatur zuerst prüfen sollten. Dafür braucht es keine Expertenbeurteilung: Sie geben dieselben Eingaben noch einmal ein und vergleichen mit bloßem Auge, ob derselbe Wert herauskommt.
Zusammenfassung ① Eine HMAC-Signatur wird aus drei Eingaben berechnet: Nachricht, geheimer Schlüssel und Hash-Algorithmus. Nur wenn alle drei exakt gleich sind, ergibt sich derselbe Wert. ② Abweichungen entstehen meist durch Leerzeichen und Zeilenumbrüche, Groß- und Kleinschreibung, die Kodierung (hexadezimal/Base64) oder die Wahl des Algorithmus. ③ Die Überprüfung besteht darin, mit derselben Nachricht, demselben Schlüssel und demselben Algorithmus selbst neu zu berechnen und das Ergebnis Zeichen für Zeichen zu vergleichen.
Was bei einer nicht passenden Webhook-Signatur typischerweise passiert
Wenn ein externer Dienst per Webhook über Ereignisse wie einen abgeschlossenen Zahlungsvorgang oder eine geänderte Bestellung informiert, sendet er häufig zusammen mit dem Request-Body (Payload) eine HMAC-Signatur im Header mit, die aus genau diesem Body berechnet wurde. Der Empfänger berechnet die Signatur mit demselben geheimen Schlüssel selbst und vergleicht sie mit dem Wert aus dem Header.
Schlägt dieser Vergleich fehl, vermutet man schnell einen Fehler im Code oder eine gefälschte Anfrage. In der Praxis wird oft aber nicht der Original-Payload verwendet, sondern er wird einmal geparst und anschließend wieder in einen String umgewandelt. Dabei kommt es häufig vor, dass ein zusätzliches Leerzeichen oder ein Zeilenumbruch hinzukommt.
HMAC ist bewusst so konzipiert, dass es auf solche winzigen Unterschiede empfindlich reagiert. Schon ein einziges Zeichen in der Nachricht, ein einziger Groß- oder Kleinbuchstabe im geheimen Schlüssel oder ein anderer Hash-Algorithmus führt dazu, dass der Ergebniswert von vorn bis hinten völlig anders aussieht.
HMAC-Werte ohne Tool selbst berechnen
HMAC ist ein in RFC 2104 standardisiertes Berechnungsverfahren, das eine Nachricht mithilfe eines geheimen Schlüssels und eines Hash-Algorithmus signiert. Die Berechnung lässt sich ohne spezielle Software direkt im Terminal nachvollziehen.
Unter macOS und Linux ist OpenSSL standardmäßig installiert. Mit dem folgenden Befehl führen Sie dieselbe Berechnung durch:
echo -n "order:1001,amount:5000" | openssl dgst -sha256 -hmac "mySecretKey"
Die Ausführung liefert dieses Ergebnis:
SHA2-256(stdin)= 148bec9dd63667edc6b3d37f9e7f5607c75144bd267159d843ec898b0667cea4
Das ist der Wert für die Nachricht order:1001,amount:5000, den Schlüssel mySecretKey und den Algorithmus SHA-256. Mit denselben drei Eingaben erhalten Sie unabhängig von Betriebssystem oder Programmiersprache immer genau diesen Wert.
Prüfen, ob andere Sprachen denselben Wert liefern
Auch mit dem hmac-Modul von Python habe ich dieselbe Nachricht mit demselben Schlüssel berechnet und denselben Wert erhalten:
import hmac, hashlib
hmac.new(b"mySecretKey", b"order:1001,amount:5000", hashlib.sha256).hexdigest()
Lassen Sie bei echo die Option -n weg, wird automatisch ein Zeilenumbruch an das Ende der Nachricht gehängt. Dann entsteht trotz gleicher Nachricht, gleichem Schlüssel und gleichem Algorithmus ein völlig anderer Wert. Dieses Problem zeige ich im nächsten Abschnitt noch einmal mit echten Werten.
Probieren wir es mit unserem Tool aus.
Die Berechnung läuft direkt im Browser über die Web Crypto API. Nachricht und geheimer Schlüssel werden nicht an einen Server übertragen.

Vier Ursachen, die bei nicht passenden Signaturen oft übersehen werden
Berechnet man den SHA-256-Wert für dieselbe Nachricht order:1001,amount:5000 mit demselben geheimen Schlüssel mySecretKey und ändert nur jeweils eine winzige Kleinigkeit, ergeben sich folgende Ergebnisse:
Original: order:1001,amount:5000
SHA-256-Ergebnis: 148bec9dd63667edc6b3d37f9e7f5607c75144bd267159d843ec898b0667cea4
Zeilenumbruch am Ende: order:1001,amount:5000 (1 Zeilenumbruchzeichen am Ende)
SHA-256-Ergebnis: 015bc2c0bf5cc82fd005e37b7a2b0ae8777e41a109bae303b263aaa162f32cff
Nur erster Buchstabe groß: Order:1001,amount:5000
SHA-256-Ergebnis: 11c1403b448d39601f4a14119514f6a44b16bdcb378f384d767ffafc0054ffb2
Die Nachricht selbst weicht minimal ab
Die Nachrichten sehen auf den ersten Blick fast gleich aus, die Ergebnisse unterscheiden sich aber schon ab der ersten Stelle vollständig. Genau das steckt häufig hinter dem Problem „Die Signatur stimmt nicht". Weder wurde der geheime Schlüssel kompromittiert, noch ist die Logik fehlerhaft: Die beiden Strings, die verglichen werden, sind tatsächlich verschieden.
Kodierung und Algorithmus unterscheiden sich
Auch dieselbe Signatur sieht anders aus, wenn das Darstellungsformat ein anderes ist. Das Ergebnis des Original-Beispiels von oben lautet in Base64 FIvsndY2Z+3Gs9N/nn9WB8dRRL0mcVnYQ+yJiwZnzqQ=. Das ist dieselbe Signatur, nur in Base64 statt hexadezimal geschrieben.
Ist der Wert aus dem Header hexadezimal und Ihre eigene Berechnung liegt in Base64 vor, wirken die Werte beim Vergleich zwangsläufig verschieden.
Bei einem anderen Algorithmus unterscheidet sich schon die Länge des Werts. Bei gleicher Nachricht und gleichem Schlüssel ergibt SHA-1 einen hexadezimalen String mit 40 Zeichen, SHA-256 mit 64, SHA-384 mit 96 und SHA-512 mit 128 Zeichen.
Berechnet man die obige Nachricht mit SHA-1, erhält man d67244f34d44c077a2a3dada4528c8284c2951cb – Länge und Wert weichen von SHA-256 ab. Die vier Ursachen im Überblick:
| Ursache | Symptom | Prüfung |
|---|---|---|
| Leerzeichen oder Zeilenumbruch am Ende der Nachricht | Der Text sieht gleich aus, der Wert ist aber anders | Selbst prüfen, ob am Ende der Nachricht ein Leerzeichen oder Zeilenumbruch steht |
| Unterschiede bei Groß- und Kleinschreibung | Nur Feldnamen oder Teile der Werte weichen ab | Zeichen für Zeichen abgleichen, ob der Original-Payload unverändert kopiert wurde |
| Unterschiedliche Kodierung (hexadezimal/Base64) | Länge und Zeichen des Werts unterscheiden sich (Base64 enthält +, / und =) | Zuerst klären, ob die Vergleichssignatur hexadezimal oder Base64 ist |
| Nicht übereinstimmender Algorithmus | Schon die Länge des Werts ist anders (40/64/96/128 Zeichen) | Prüfen, ob der vom Absender angegebene Algorithmus dem gewählten entspricht |
Fazit
- Eine HMAC-Signatur wird durch drei Eingaben bestimmt: Nachricht, geheimer Schlüssel und Algorithmus. Nur wenn alle drei gleich sind, ergibt sich derselbe Wert.
- Schon ein einziges zusätzliches Leerzeichen oder ein Zeilenumbruch in der Nachricht verändert das Ergebnis vollständig.
- Unterscheiden sich die Längen der Werte, liegt es mit hoher Wahrscheinlichkeit an der Kodierung (hexadezimal/Base64) oder am Algorithmus.
- Zur Überprüfung genügt es, mit denselben drei Eingaben neu zu berechnen und das Ergebnis Zeichen für Zeichen mit dem erhaltenen Wert zu vergleichen.
- Wenn Sie mit dem Befehl openssl dgst oder einem Browser-Tool selbst neu berechnen, können Sie eingrenzen, welche Eingabe abweicht.
Die Berechnung läuft direkt im Browser über die Web Crypto API. Nachricht und geheimer Schlüssel werden nicht an einen Server übertragen.
Häufig gestellte Fragen
Bei gleicher Nachricht und gleichem Schlüssel kommt jedes Mal ein anderer Wert heraus. Ist das normal?
Nein. HMAC ist eine deterministische Berechnung: Sind Nachricht, geheimer Schlüssel und Algorithmus gleich, entsteht immer derselbe Wert, egal wann und wo Sie rechnen. Ändert sich der Wert ständig, verändert sich tatsächlich eine der drei Eingaben. Häufig steckt in der Nachricht ein Wert, der sich bei jedem Aufruf ändert, etwa die aktuelle Uhrzeit.
Welches Format ist richtig: hexadezimal oder Base64?
Beide stellen lediglich dieselben Ergebnis-Bytes dar, keines ist das „richtige". Entscheidend ist, in welchem Format der Absender die Signatur kodiert hat. Besteht der Wert nur aus den Zeichen 0-9 und a-f, ist er hexadezimal; kommen die Zeichen +, / und = vor, handelt es sich um Base64.
Wie finde ich den Algorithmus heraus, wenn ich ihn nicht kenne?
Lassen Sie Nachricht und Schlüssel unverändert und berechnen Sie den Wert nacheinander mit SHA-256, SHA-384, SHA-512 und SHA-1. Vergleichen Sie dann zuerst mit dem Algorithmus, dessen Ergebnis dieselbe Länge wie der erhaltene Wert hat. Oft ist der Algorithmus in der Dokumentation oder API-Spezifikation angegeben; ein Blick dorthin ist die sicherste Methode.
Ändert sich der Wert, wenn die Nachricht Umlaute oder Sonderzeichen enthält?
Bei gleicher Kodierung (zum Beispiel UTF-8) wird derselbe String immer in dieselben Bytes umgewandelt und ergibt denselben Wert. Ändert sich die Zeichenkodierung jedoch beim Speichern oder Übertragen (etwa UTF-8 auf der einen, EUC-KR auf der anderen Seite), unterscheiden sich die tatsächlichen Bytes trotz gleich aussehender Zeichen, und das Ergebnis kann abweichen.
Dieser Artikel basiert auf unserem koreanischen Original. Koreanisches Original lesen