Zum Inhalt springen

Webhook-Signaturen mit HMAC verifizieren

Der Header X-Signature eines Chaingateway-Webhooks erlaubt Ihnen zu prüfen, dass eine Anfrage wirklich von Chaingateway stammt. Er enthält den Base64-kodierten HMAC-SHA256 der Transaktions-ID (txid) aus dem Payload, mit Ihrem persönlichen Secret als Schlüssel. Ihr Empfänger berechnet den Wert neu und vergleicht ihn mit dem Header. Der Header wird gesendet, sobald Sie ein persönliches Secret gesetzt haben.

Signaturprüfung: Chaingateway berechnet HMAC-SHA256 über die txid mit Ihrem persönlichen Secret und sendet das Ergebnis in X-Signature, Ihr Empfänger berechnet den Wert neu und vergleicht ihn in konstanter Zeit Chaingateway signiert base64( HMAC-SHA256( personal_secret, txid ) ) POST an Ihren Empfänger JSON-Body mit txid, Header X-Signature Empfänger berechnet den HMAC neu dasselbe Secret, dieselbe txid Vergleich in konstanter Zeit gleich: annehmen, verschieden: mitFehlerstatus ablehnen
Nur die txid wird signiert. Die übrigen Payload-Felder sind nicht Teil der Signatur.

Er schützt vor gefälschten Anfragen: Jeder kann eine POST-Anfrage an Ihre öffentliche Empfänger-URL senden, aber nur ein Sender, der das persönliche Secret kennt, kann eine passende Signatur erzeugen. HMAC, definiert in RFC 2104, kombiniert eine Hashfunktion mit einem geheimen Schlüssel, hier SHA-256. NIST FIPS 198-1 spezifiziert dieselbe Konstruktion als Keyed-Hash Message Authentication Code.

Die Signatur deckt die txid ab und sonst nichts. Der Betrag, die Adressen und die Token-Felder im Body sind nicht signiert. Ein gültiges Paar aus txid und Signatur beweist daher nicht, dass der Rest des Bodys unverändert ist. Behandeln Sie die txid nach der Prüfung als Suchschlüssel: Lesen Sie die Transaktion mit GET /api/v2/{chain}/transactions/{txid} und buchen Sie die Zahlung anhand der Daten, die die API zurückgibt, nicht anhand des Betrags im Benachrichtigungs-Body.

Sie legen das persönliche Secret in Ihren Profileinstellungen fest oder generieren es neu. Gehen Sie dazu wie folgt vor:

  1. Öffnen Sie die Profileinstellungen.
  2. Suchen Sie den mit „Personal Secret“ beschrifteten Bereich.
  3. Ist noch kein Secret festgelegt, klicken Sie auf „Set Personal Secret“, um eines zu generieren. Ist bereits ein Secret vorhanden, klicken Sie auf „Regenerate Secret“, um es zu ersetzen.

Zwei Details sind für ein laufendes System wichtig. Wenn Sie noch kein persönliches Secret haben, aktiviert das Hinzufügen den Header X-Signature für alle ausgehenden Webhooks. Setzen Sie vorher einen Empfänger ein, der den Header akzeptiert und prüft. Wenn Sie ein vorhandenes Secret neu generieren, gilt das neue Secret sofort für Webhook-Benachrichtigungen. Aktualisieren Sie den Empfänger gleichzeitig, sonst lehnt er gültige Anfragen ab.

Chaingateway liest die txid aus dem Payload, berechnet darüber mit der Hashfunktion SHA-256 einen HMAC, verwendet dabei das persönliche Secret als Schlüssel und kodiert die 32 Ergebnis-Bytes mit Base64. Die txid ist die eindeutige Transaktionskennung, die bereits im Webhook-Body steht, daher hat der Empfänger alles, was er zum Neuberechnen braucht. Das Secret teilen nur Chaingateway und Sie.

Berechnen Sie den HMAC aus der txid im Body neu und vergleichen Sie ihn mit dem Wert des Headers. Verwenden Sie eine Vergleichsfunktion mit konstanter Laufzeit, damit die Vergleichsdauer nichts über den erwarteten Wert verrät. Die folgenden Beispiele tun das in Python, Java, PHP und JavaScript.

import hmac
import hashlib
import base64
def verify_signature(txid, received_signature, personal_secret):
# Generate the expected signature
expected_signature = base64.b64encode(hmac.new(
personal_secret.encode(),
txid.encode(),
hashlib.sha256
).digest()).decode()
# Compare the expected signature with the received signature
return hmac.compare_digest(expected_signature, received_signature)
# Example usage
txid = 'your_txid_here'
received_signature = 'received_signature_here'
personal_secret = 'your_personal_secret_here'
if verify_signature(txid, received_signature, personal_secret):
print("Signature is valid.")
else:
print("Invalid signature.")

Testen Sie die Funktion mit einer festen Eingabe, bevor Sie sie mit Live-Traffic verbinden. Die folgenden Werte sind ein Testvektor, den Sie mit jedem HMAC-SHA256-Werkzeug reproduzieren können. Das Secret ist ein Platzhalter, kein echtes persönliches Secret. Liefert Ihre Funktion für diese Eingabe einen anderen Wert, liegt der Fehler in Ihrem Code und nicht im Webhook.

personal_secret: my_personal_secret
txid: 18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988
X-Signature: t2vU2mYBCv/UvpKprNJB7qbgrCpPXKb6NWgL77xsZgQ=

Häufige Fehler sind, den ganzen JSON-Body statt der txid zu hashen, den Hex-Digest statt Base64 zu verwenden und mit == zu vergleichen, was nicht in konstanter Zeit läuft. Denken Sie außerdem daran, dass das persönliche Secret für das ganze Konto gilt. Ein Secret, das Sie in den Profileinstellungen neu generieren, ändert die Signatur aller Webhooks des Kontos auf einmal.

Was tue ich, wenn die Signatur nicht übereinstimmt?

Abschnitt betitelt „Was tue ich, wenn die Signatur nicht übereinstimmt?“

Lehnen Sie die Anfrage mit einem Fehlerstatus wie 401 oder 403 ab und verarbeiten Sie den Body nicht. Protokollieren Sie die txid, den empfangenen Header und die Quelladresse, damit Sie ein falsch konfiguriertes Secret von einer gefälschten Anfrage unterscheiden können. Wenn derselbe Sender direkt nach dem Neugenerieren des Secrets Abweichungen erzeugt, verwendet der Empfänger noch das alte. Eine gefälschte Anfrage, die nur eine txid errät, kann ohne das Secret keine gültige Signatur erzeugen.

Die Signaturprüfung ist eine Schicht. Die folgenden Maßnahmen decken den Rest des Weges ab.

  • Stellen Sie den Empfänger über HTTPS bereit, damit der Payload auf dem Transportweg verschlüsselt ist. Das REST Security Cheat Sheet von OWASP empfiehlt HTTPS für jeden Endpunkt, der sensible Daten verarbeitet.
  • Lehnen Sie Anfragen mit fehlendem oder falschem X-Signature mit einem Fehlerstatus ab und protokollieren Sie sie.
  • Verwenden Sie die txid als Idempotenzschlüssel. Eine Benachrichtigung, die Sie mit POST /api/v2/{chain}/webhooks/notifications/{id}/retry erneut senden, trägt dieselbe txid und darf eine Zahlung nicht zweimal gutschreiben.
  • Bewahren Sie das persönliche Secret in einem Secrets-Speicher auf, niemals im Repository, und wechseln Sie es, wenn es möglicherweise abgeflossen ist. Chaingateway wiederholt fehlgeschlagene Zustellungen nicht von selbst, planen Sie die Aktualisierung von Empfänger und Secret daher als einen Schritt und senden Sie verpasste Benachrichtigungen danach aus der Liste der fehlgeschlagenen erneut.