L'API è progettata partendo dal presupposto che ogni chiamata abbia un impatto finanziario diretto e possa accedere a credenziali server sensibili. I requisiti di sicurezza sono quindi nettamente superiori agli standard REST.
Controlli implementati
- HMAC-SHA256: Ogni richiesta è firmata con HMAC-SHA256 su metodo, percorso, timestamp, nonce e hash del body. Verifica a tempo costante (hash_equals).
- AES-256-GCM: I segreti vengono persistiti esclusivamente come ciphertext AES-256-GCM (libsodium). La master key risiede al di fuori del DB in /etc/kh-reseller-api/master.key.v{N}.
- Replay protection: Finestra timestamp +-300s, cache nonce 600s. Una richiesta firmata correttamente non può essere replicata.
- Scope-based authorization: Per ogni chiave una lista esplicita di permessi. I permessi di scrittura e quelli sensibili devono essere abilitati esplicitamente.
- IP whitelist (optional): Lista IP autorizzati opzionale per ogni chiave (notazione CIDR, IPv4 e IPv6).
- Rate limit: Multi-livello: per chiave (minuto e giorno) e per IP (minuto). Token bucket con tolleranza burst.
- Idempotency: Ordini e azioni di servizio distruttive richiedono una Idempotency-Key. Protezione replay 24h contro i retry di rete.
- Tenant isolation: Ogni query al DB filtra rigorosamente sul suo account id. L'accesso cross-tenant è impossibile per costruzione.
- Tamper-evident audit log: Ogni richiesta finisce nell'audit log con chain hash (chain_hash[n] = sha256(chain_hash[n-1] || row_n)). Le manomissioni retroattive vengono rilevate dalla rottura della catena hash.
- Credentials.read alerting: Ogni chiamata credentials.read produce una voce di audit dedicata più un'email di conferma opzionale al titolare dell'account.
- SSRF-guarded webhooks: Gli URL webhook vengono verificati prima della memorizzazione: solo HTTPS, la risoluzione DNS deve restituire esclusivamente IP pubblici (niente RFC1918, niente link-local).
Best practice dal suo lato
- Conservi il segreto in un gestore di segreti (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password), mai nel codice, mai in un repository git.
- Ruoti il segreto regolarmente (almeno annualmente oppure dopo cambi di personale). Rotazione con un clic nel portale, il vecchio segreto viene invalidato immediatamente.
- Una chiave dedicata per ogni caso d'uso con il permesso minimo (sola lettura se possibile). Niente chiavi "god-mode".
- Se la sua integrazione gira da IP fissi (cloud, bastion): imposti una lista IP autorizzati.
- Generi la Idempotency-Key lato server e la persista; non la generi nuovamente ad ogni retry. Raccomandazione: UUIDv4 per ogni ordine logico.
- Imposti un webhook verso il suo URL; monitori almeno order.created e credentials.read come flusso di eventi.
Disclosure di sicurezza
Segnali le problematiche di sicurezza in modo riservato a security@kernelhost.com. Chiave PGP su richiesta. Risposta garantita entro 24h. Programma bug bounty in preparazione.
