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.
Wogegen schützt der Header X-Signature?
Abschnitt betitelt „Wogegen schützt der Header X-Signature?“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.
Wie lege ich das persönliche Secret fest?
Abschnitt betitelt „Wie lege ich das persönliche Secret fest?“Sie legen das persönliche Secret in Ihren Profileinstellungen fest oder generieren es neu. Gehen Sie dazu wie folgt vor:
- Öffnen Sie die Profileinstellungen.
- Suchen Sie den mit „Personal Secret“ beschrifteten Bereich.
- 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.
Wie wird der Header X-Signature aufgebaut?
Abschnitt betitelt „Wie wird der Header X-Signature aufgebaut?“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.
Wie verifiziere ich die Signatur in meinem Code?
Abschnitt betitelt „Wie verifiziere ich die Signatur in meinem Code?“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 hmacimport hashlibimport 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 usagetxid = '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.")import javax.crypto.Mac;import javax.crypto.spec.SecretKeySpec;import java.nio.charset.StandardCharsets;import java.security.MessageDigest;import java.util.Base64;
public class SignatureVerifier { public static boolean verifySignature(String txid, String receivedSignature, String personalSecret) throws Exception { Mac mac = Mac.getInstance("HmacSHA256"); SecretKeySpec secretKeySpec = new SecretKeySpec(personalSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"); mac.init(secretKeySpec);
byte[] signatureBytes = mac.doFinal(txid.getBytes(StandardCharsets.UTF_8)); String expectedSignature = Base64.getEncoder().encodeToString(signatureBytes);
// Constant-time comparison return MessageDigest.isEqual( expectedSignature.getBytes(StandardCharsets.UTF_8), receivedSignature.getBytes(StandardCharsets.UTF_8)); }
public static void main(String[] args) { try { String txid = "your_txid_here"; String receivedSignature = "received_signature_here"; String personalSecret = "your_personal_secret_here";
if (verifySignature(txid, receivedSignature, personalSecret)) { System.out.println("Signature is valid."); } else { System.out.println("Invalid signature."); } } catch (Exception e) { e.printStackTrace(); } }}<?phpfunction verifySignature($txid, $receivedSignature, $personalSecret) { // Generate the expected signature $expectedSignature = base64_encode(hash_hmac('sha256', $txid, $personalSecret, true));
// Compare the expected signature with the received signature return hash_equals($expectedSignature, $receivedSignature);}
// Example usage$txid = 'your_txid_here';$receivedSignature = 'received_signature_here';$personalSecret = 'your_personal_secret_here';
if (verifySignature($txid, $receivedSignature, $personalSecret)) { echo "Signature is valid.";} else { echo "Invalid signature.";}const crypto = require('crypto');
function verifySignature(txid, receivedSignature, personalSecret) { // Generate the expected signature const expectedSignature = crypto .createHmac('sha256', personalSecret) .update(txid) .digest('base64');
// timingSafeEqual throws if the lengths differ, so check them first const expected = Buffer.from(expectedSignature); const received = Buffer.from(receivedSignature); return expected.length === received.length && crypto.timingSafeEqual(expected, received);}
// Example usageconst txid = 'your_txid_here';const receivedSignature = 'received_signature_here';const personalSecret = 'your_personal_secret_here';
if (verifySignature(txid, receivedSignature, personalSecret)) { console.log("Signature is valid.");} else { console.log("Invalid signature.");}Wie kann ich meinen Verifizierungscode testen?
Abschnitt betitelt „Wie kann ich meinen Verifizierungscode testen?“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_secrettxid: 18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988X-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.
Was sollte ein Webhook-Empfänger sonst noch tun?
Abschnitt betitelt „Was sollte ein Webhook-Empfänger sonst noch tun?“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-Signaturemit einem Fehlerstatus ab und protokollieren Sie sie. - Verwenden Sie die
txidals Idempotenzschlüssel. Eine Benachrichtigung, die Sie mitPOST /api/v2/{chain}/webhooks/notifications/{id}/retryerneut senden, trägt dieselbetxidund 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.
Quellen
Abschnitt betitelt „Quellen“- RFC 2104, HMAC: Keyed-Hashing for Message Authentication
- NIST FIPS 198-1, The Keyed-Hash Message Authentication Code (HMAC)
- OWASP REST Security Cheat Sheet
- Die Seite Webhooks in dieser Dokumentation für den Payload und die Wiederholungs-Endpunkte.