Salta ai contenuti

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.

Verifica della firma: Chaingateway calcola l'HMAC-SHA256 sul txid con il tuo personal secret e lo invia in X-Signature, il tuo ricevente ricalcola il valore e lo confronta in tempo costante Chaingateway firma base64( HMAC-SHA256( personal_secret, txid ) ) POST al tuo ricevente corpo JSON con txid, header X-Signature Il ricevente ricalcola l'HMAC stesso secret, stesso txid Confronto in tempo costante uguali: accetta, diversi: rifiuta con unostato di errore
Viene firmato solo il txid. Gli altri campi del payload non fanno parte della firma.

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.

Imposti o rigeneri il personal secret nelle impostazioni del profilo. Segui questi passaggi:

  1. Apri le Impostazioni del profilo.
  2. Trova la sezione denominata “Personal Secret”.
  3. 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.

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.

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 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.")

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_secret
txid: 18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988
X-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.

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.

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-Signature mancante o errato e registrale nei log.
  • Usa il txid come chiave di idempotenza. Una notifica che reinvii con POST /api/v2/{chain}/webhooks/notifications/{id}/retry porta lo stesso txid e 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.