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

VeröffentlichtToolHMAC-Generator

Inhalt
  1. Was bei einer nicht passenden Webhook-Signatur typischerweise passiert
  2. HMAC-Werte ohne Tool selbst berechnen
  3. Vier Ursachen, die bei nicht passenden Signaturen oft übersehen werden
  4. Fazit
  5. Häufig gestellte Fragen

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.

HMAC-Generator

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:

UrsacheSymptomPrüfung
Leerzeichen oder Zeilenumbruch am Ende der NachrichtDer Text sieht gleich aus, der Wert ist aber andersSelbst prüfen, ob am Ende der Nachricht ein Leerzeichen oder Zeilenumbruch steht
Unterschiede bei Groß- und KleinschreibungNur Feldnamen oder Teile der Werte weichen abZeichen 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 AlgorithmusSchon 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

  1. Eine HMAC-Signatur wird durch drei Eingaben bestimmt: Nachricht, geheimer Schlüssel und Algorithmus. Nur wenn alle drei gleich sind, ergibt sich derselbe Wert.
  2. Schon ein einziges zusätzliches Leerzeichen oder ein Zeilenumbruch in der Nachricht verändert das Ergebnis vollständig.
  3. Unterscheiden sich die Längen der Werte, liegt es mit hoher Wahrscheinlichkeit an der Kodierung (hexadezimal/Base64) oder am Algorithmus.
  4. 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.
  5. Wenn Sie mit dem Befehl openssl dgst oder einem Browser-Tool selbst neu berechnen, können Sie eingrenzen, welche Eingabe abweicht.
HMAC-Generator

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

Ähnliche Artikel

  1. HTML-E-Mail-Vorschau: Mobil, Tablet und Desktop prüfenSo prüfen Sie HTML-E-Mail-Code im Browser auf Mobil, Tablet und Desktop. Dazu: warum Tabellen und Inline-Styles statt div nötig sind und warum Clients abweichen.
  2. HTML-Entities umwandeln: Die 5 Zeichen und ihre KodierungSo funktioniert die Umwandlung in HTML-Entities: Welche fünf Zeichen ersetzt werden, in welcher Reihenfolge und wie Sie Entities wieder dekodieren.
  3. HTML-Sonderzeichen escapen: Entities richtig umwandelnWarum &, <, >, " und ' in HTML besonders behandelt werden, und wie Sie sie mit einer 1:1-Tabelle escapen und wieder decodieren – inklusive Reihenfolge.
  4. HTML in JavaScript-String umwandeln: Maskierung und PrüfungWarum Anführungszeichen- und Backtick-Modus Zeilenumbrüche unterschiedlich behandeln und welche Syntaxfehler nach der Umwandlung von HTML in JS-Strings typisch sind.
  5. HTML Leerzeichen entfernen: Was beim Komprimieren wegfälltBeim HTML-Komprimieren fallen nur Leerraum und Kommentare weg. So bleiben script, style, pre und textarea intakt, und so wird die Ersparnis berechnet.
  6. htpasswd-Generator: .htpasswd-Datei ohne Installation erstellenSo erzeugen Sie im Browser eine .htpasswd-Zeile für Basic-Auth bei Apache und Nginx. Aufbau Benutzername:Hash und {SHA}/{SHA256} ohne htpasswd-Befehl.

Passende Tools