Verificare le firme dei webhook con HMAC
L’header X-Signature di un webhook Chaingateway ti permette di verificare che una richiesta provenga davvero da Chaingateway. Contiene l’HMAC-SHA256, codificato in base64, dell’id di transazione (txid) del payload, calcolato con il tuo personal secret. Il tuo ricevente ricalcola il valore e lo confronta con l’header. L’header viene inviato dopo che hai impostato un personal secret.
Da cosa protegge l’header X-Signature?
Sezione intitolata “Da cosa protegge l’header X-Signature?”Protegge dalle richieste falsificate: chiunque può inviare una richiesta POST all’URL pubblico del tuo ricevente, ma solo un mittente che conosce il personal secret può produrre una firma corrispondente. L’HMAC, definito in RFC 2104, combina una funzione di hash con una chiave segreta, qui SHA-256. NIST FIPS 198-1 specifica la stessa costruzione come Keyed-Hash Message Authentication Code.
La firma copre il txid e nient’altro. L’importo, gli indirizzi e i campi del token nel corpo non sono firmati. Una coppia valida di txid e firma non dimostra quindi che il resto del corpo sia invariato. Dopo la verifica, tratta il txid come chiave di ricerca: leggi la transazione con GET /api/v2/{chain}/transactions/{txid} e accredita il pagamento in base ai dati restituiti dall’API, non all’importo nel corpo della notifica.
Come imposto il personal secret?
Sezione intitolata “Come imposto il personal secret?”Imposti o rigeneri il personal secret nelle impostazioni del profilo. Segui questi passaggi:
- Apri le Impostazioni del profilo.
- Trova la sezione denominata “Personal Secret”.
- Se non è impostato alcun secret, clicca su “Set Personal Secret” per generarne uno. Se esiste già un secret, clicca su “Regenerate Secret” per sostituirlo.
Due dettagli contano per un sistema in produzione. Se non hai ancora un personal secret, aggiungerne uno attiva l’header X-Signature su tutti i webhook in uscita. Metti in produzione un ricevente che accetta e verifica l’header prima di farlo. Se rigeneri un secret esistente, il nuovo secret si applica subito alle notifiche webhook. Aggiorna il ricevente nello stesso momento, altrimenti rifiuta richieste valide.
Come viene costruito l’header X-Signature?
Sezione intitolata “Come viene costruito l’header X-Signature?”Chaingateway legge il txid dal payload, calcola su di esso un HMAC con la funzione di hash SHA-256 usando il personal secret come chiave e codifica in base64 i 32 byte del risultato. Il txid è l’identificativo univoco della transazione che compare già nel corpo del webhook, quindi il ricevente ha tutto ciò che serve per ricalcolare il valore. Il secret è condiviso solo tra Chaingateway e te.
Come verifico la firma nel mio codice?
Sezione intitolata “Come verifico la firma nel mio codice?”Ricalcola l’HMAC dal txid nel corpo e confrontalo con il valore dell’header. Usa una funzione di confronto in tempo costante, in modo che il tempo di confronto non riveli nulla sul valore atteso. Gli esempi seguenti lo fanno in Python, Java, PHP e 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.");}Come posso testare il mio codice di verifica?
Sezione intitolata “Come posso testare il mio codice di verifica?”Testa la funzione con un input fisso prima di collegarla al traffico reale. I valori seguenti sono un vettore di test che puoi riprodurre con qualsiasi strumento HMAC-SHA256. Il secret è un segnaposto, non un vero personal secret. Se la tua funzione restituisce un valore diverso per questo input, l’errore è nel tuo codice e non nel webhook.
personal_secret: my_personal_secrettxid: 18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988X-Signature: t2vU2mYBCv/UvpKprNJB7qbgrCpPXKb6NWgL77xsZgQ=Errori comuni sono calcolare l’hash dell’intero corpo JSON invece del txid, usare il digest esadecimale invece del base64 e confrontare con ==, che non è in tempo costante. Ricorda inoltre che il personal secret vale per l’intero account. Un secret che rigeneri nelle impostazioni del profilo cambia in un colpo solo la firma di ogni webhook dell’account.
Cosa devo fare quando la firma non corrisponde?
Sezione intitolata “Cosa devo fare quando la firma non corrisponde?”Rifiuta la richiesta con uno stato di errore come 401 o 403 e non elaborare il corpo. Registra il txid, l’header ricevuto e l’indirizzo di origine, così da distinguere un secret configurato male da una richiesta falsificata. Se lo stesso mittente produce discrepanze subito dopo che hai rigenerato il secret, il ricevente usa ancora il vecchio. Una richiesta falsificata che si limita a indovinare un txid non può produrre una firma valida senza il secret.
Cos’altro deve fare un ricevente di webhook?
Sezione intitolata “Cos’altro deve fare un ricevente di webhook?”La verifica della firma è un solo livello. Le misure seguenti coprono il resto del percorso.
- Esponi il ricevente su HTTPS, così il payload è cifrato in transito. La REST Security Cheat Sheet di OWASP raccomanda HTTPS per ogni endpoint che tratta dati sensibili.
- Rifiuta con uno stato di errore le richieste con
X-Signaturemancante o errato e registrale nei log. - Usa il
txidcome chiave di idempotenza. Una notifica che reinvii conPOST /api/v2/{chain}/webhooks/notifications/{id}/retryporta lo stessotxide non deve accreditare un pagamento due volte. - Conserva il personal secret in un archivio di segreti, mai nel repository, e ruotalo se potrebbe essere trapelato. Chaingateway non ritenta da solo le consegne fallite, quindi pianifica l’aggiornamento del ricevente e del secret come un unico passaggio, e reinvia poi le notifiche perse dall’elenco delle fallite.
- RFC 2104, HMAC: Keyed-Hashing for Message Authentication
- NIST FIPS 198-1, The Keyed-Hash Message Authentication Code (HMAC)
- OWASP REST Security Cheat Sheet
- Webhook in questa documentazione per il payload e gli endpoint di nuovo tentativo.