Sicurezza dell'API blockchain: 6 consigli pratici
Sei pratiche di sicurezza per un'API blockchain: chiavi generate bene, conservazione offline, firma locale, uso degli indirizzi, token API e firma dei webhook.
Verificato da Maurice Sobiera
La sicurezza di un’API blockchain è l’insieme di pratiche che tengono le chiavi private, i token API e il traffico dei webhook lontani dagli aggressori, quando la vostra applicazione usa una blockchain tramite API. Il rischio sta nella gestione delle chiavi, nelle credenziali e nell’endpoint dei webhook, non nella blockchain in sé. Queste sei pratiche valgono per Chaingateway e per qualsiasi API simile.
Come si generano le chiavi private?
Le chiavi private vanno generate con un generatore di numeri casuali crittograficamente sicuro, in un ambiente sotto il proprio controllo. Il Cryptographic Storage Cheat Sheet di OWASP afferma che le chiavi devono provenire da una funzione crittograficamente sicura e non devono essere costruite da parole comuni o da sequenze di tasti. Una chiave debole o prevedibile può essere indovinata, e chi la indovina può spendere i fondi.
Chaingateway può creare un indirizzo tramite POST /api/v2/{blockchain}/addresses. La guida alla gestione dei wallet descrive due modalità. Con una password, la chiave privata viene conservata cifrata sul nostro lato e per inviare le transazioni si usa la password. Senza password, la risposta contiene la chiave privata in chiaro, adatta a un indirizzo temporaneo ma non a uno che si intende conservare. Per il pieno controllo, generate la chiave sulla vostra macchina o su un hardware wallet e importatela solo se necessario.
Come si conservano le chiavi private?
Le chiavi che custodiscono fondi a lungo termine vanno tenute offline, e sui server restano solo i saldi operativi. Una chiave su una macchina connessa a internet può essere rubata da chiunque comprometta quella macchina. Hardware wallet e backup offline eliminano questa esposizione, ma un hardware wallet può andare perso, quindi serve un backup di recupero testato.
Non scrivete mai chiavi o password nel codice sorgente, nei log o nei ticket. Il Secrets Management Cheat Sheet di OWASP osserva che molte organizzazioni inseriscono segreti in chiaro direttamente nel codice sorgente e nei file di configurazione, e raccomanda una memorizzazione centralizzata con controllo degli accessi e rotazione automatica.
Conviene firmare le transazioni sulla propria macchina?
Sì, quando è possibile. Una transazione firmata localmente non espone mai la chiave privata a terzi, e l’API deve solo trasmettere il risultato. Per TRON, Chaingateway supporta questo flusso: gli endpoint build restituiscono una transazione non firmata, la si firma con gli strumenti TRON descritti nella guida alla firma offline TRON, e POST /api/v2/tron/transactions/broadcast invia la transazione firmata.
Per le reti EVM, gli endpoint delle transazioni accettano la password di un indirizzo memorizzato oppure una privatekey nel corpo della richiesta. Se si usa privatekey, la chiave viaggia nella richiesta, quindi chiamate l’API solo tramite HTTPS e non registrate mai i corpi delle richieste nei log. La nostra guida alla decifratura dei keystore mostra come aprire localmente un file keystore esportato.
Si possono usare come cold wallet gli indirizzi creati tramite API?
No. Un indirizzo la cui chiave è stata creata o conservata da un servizio online è un hot wallet, comunque lo si chiami. Gli indirizzi creati tramite API vanno usati come indirizzi di deposito, i fondi in entrata vanno spostati su un cold wallet generato offline, e l’indirizzo di deposito va considerato di breve durata.
Svuotare regolarmente i depositi e usare un indirizzo nuovo per ogni cliente o ordine limita ciò che un aggressore ottiene da una singola chiave trapelata. Se si è usata la modalità senza protezione, la chiave privata è stata restituita una sola volta, quindi va conservata come una password.
Come si protegge il token API?
Il token va inviato nell’header Authorization e va tenuto fuori dagli URL, dal codice front-end e dai repository. Chaingateway usa lo schema bearer, Authorization: Bearer <token>, come definito nella RFC 6750. Quella RFC richiede TLS per ogni richiesta che porta un token bearer, perché chiunque veda il token può usarlo.
Tre abitudini riducono i danni di una fuga di dati:
- Conservare il token in una variabile d’ambiente o in un secret manager, non nel codice.
- Ruotarlo secondo un calendario e dopo ogni sospetta esposizione, come descritto nella nostra guida alla rotazione delle chiavi API.
- Limitare l’accesso per indirizzo IP, se il pannello del proprio account lo offre. Il nostro articolo sulla funzione whitelist IP spiega come funziona.
L’OWASP API Security Top 10 elenca tra i principali rischi delle API l’autenticazione difettosa, inclusa una gestione debole dei token.
Come si verificano i webhook dell’API?
Si verifica l’header X-Signature di ogni webhook prima di fidarsi del contenuto. Senza questo controllo, chiunque conosca l’URL del vostro webhook può inviare una falsa notifica di pagamento. Chaingateway firma i webhook quando impostate un segreto personale nelle impostazioni del profilo. La firma è un HMAC, come specificato nella RFC 2104, costruito a partire dall’ID della transazione e dal vostro segreto.
La guida alla sicurezza dei webhook contiene codice di verifica in Python, Java, PHP e JavaScript. Le firme vanno confrontate con una funzione a tempo costante, e la transazione va confermata sulla chain prima di accreditare un ordine. Chaingateway non ritenta automaticamente i webhook falliti. Le notifiche non riuscite sono elencate sotto /api/v2/{blockchain}/webhooks/notifications/failed, e ciascuna si può inviare di nuovo tramite /webhooks/notifications/{id}/retry, quindi controllate questo elenco quando un pagamento sembra mancare.
Servono tutte e sei?
Per tutto ciò che custodisce valore reale, sì. Le pratiche coprono punti di guasto diversi, e saltarne una lascia aperto quel punto, qualunque cosa si faccia altrove.
| Punto di guasto | Che cosa fare | Dove verificare |
|---|---|---|
| Creazione delle chiavi | Usare un generatore crittograficamente sicuro, oppure un indirizzo protetto da password | Guida alla gestione dei wallet |
| Conservazione delle chiavi | Tenere offline i fondi a lungo termine, tenere i segreti fuori da codice e log | OWASP Secrets Management Cheat Sheet |
| Firma | Firmare localmente dove l’API lo supporta, altrimenti usare solo HTTPS | POST /api/v2/tron/transactions/broadcast |
| Uso degli indirizzi | Usare indirizzi API per i depositi e svuotarli su un cold wallet | Il proprio job di svuotamento |
| Accesso all’API | Conservare il token bearer in un secret manager e ruotarlo | Guida alla rotazione delle chiavi API |
| Notifiche | Verificare X-Signature e confermare la transazione sulla chain | Guida alla sicurezza dei webhook |
Controllate la tabella prima di passare dalla testnet alla mainnet. L’header X-Network: testnet permette di eseguire l’intero flusso, inclusa la verifica dei webhook, senza fondi reali.
Come scriviamo questi articoli
Pronto a costruirlo da solo? Ottieni la tua API key — prova di 7 giorni, senza carta — oppure consulta Blockchain API per il riferimento completo degli endpoint.