API-ul este proiectat pornind de la premisa că fiecare apel are impact financiar direct și poate accesa credențiale sensibile de server. Cerințele de securitate sunt, prin urmare, mult peste standardele REST.
Măsuri implementate
- HMAC-SHA256: Fiecare cerere este semnată cu HMAC-SHA256 peste metodă, cale, marcaj temporal, nonce și hash al corpului. Verificare în timp constant (hash_equals).
- AES-256-GCM: Codurile secrete sunt stocate exclusiv ca criptograme AES-256-GCM (libsodium). Cheia master se află în afara bazei de date, la /etc/kh-reseller-api/master.key.v{N}.
- Replay protection: Fereastră de marcaj temporal +-300s, cache de nonce 600s. O cerere semnată cu succes nu poate fi retrimisă.
- Scope-based authorization: Listă explicită de permisiuni per cheie. Permisiunile de scriere și cele sensibile trebuie activate explicit.
- IP whitelist (optional): Listă albă IP opțională per cheie (notație CIDR, IPv4 și IPv6).
- Rate limit: Pe mai multe niveluri: per cheie (minut și zi) și per IP (minut). Token bucket cu toleranță la burst.
- Idempotency: Comenzile și acțiunile distructive asupra serviciilor necesită un Idempotency-Key. Protecție replay de 24h împotriva reîncercărilor de rețea.
- Tenant isolation: Fiecare interogare în baza de date filtrează strict după ID-ul contului dumneavoastră. Accesul între tenanți este imposibil prin construcție.
- Tamper-evident audit log: Fiecare cerere este înregistrată în jurnalul de audit cu hash de lanț (chain_hash[n] = sha256(chain_hash[n-1] || row_n)). Manipularea retroactivă este detectată imediat printr-o ruptură a hashului.
- Credentials.read alerting: Fiecare apel credentials.read generează o intrare dedicată în audit, plus un e-mail opțional de confirmare către proprietarul contului.
- SSRF-guarded webhooks: Adresele URL ale webhookurilor sunt verificate înainte de stocare: doar HTTPS, iar rezoluția DNS trebuie să returneze exclusiv IP-uri publice (fără RFC1918, fără link-local).
Bune practici la dumneavoastră
- Stocați codul secret într-un manager de secrete (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password), niciodată în cod, niciodată într-un depozit git.
- Rotiți codul secret periodic (cel puțin anual sau după schimbări de personal). Rotație cu un singur clic în portal, vechiul cod secret fiind invalidat imediat.
- O cheie dedicată pentru fiecare caz de utilizare, cu permisiunea minimă (doar citire, dacă este posibil). Fără chei de tip "god-mode".
- Dacă integrarea dumneavoastră rulează din IP-uri fixe (cloud, bastion): setați o listă albă IP.
- Generați Idempotency-Key pe partea de server și persistați-l; nu îl regenerați la fiecare reîncercare. Recomandare: UUIDv4 per comandă logică.
- Configurați un webhook către propria adresă URL; urmăriți cel puțin order.created și credentials.read ca flux de evenimente.
Dezvăluire de securitate
Vă rugăm să raportați problemele de securitate confidențial la security@kernelhost.com. Cheie PGP la cerere. Răspuns garantat în 24h. Program bug-bounty în pregătire.
