API:et är utformat med antagandet att varje anrop har direkt ekonomisk påverkan och kan komma åt känsliga serveruppgifter. Säkerhetskraven ligger därför klart över REST-standard.
Inbyggda skyddsmekanismer
- HMAC-SHA256: Varje förfrågan signeras med HMAC-SHA256 över metod, sökväg, tidsstämpel, nonce och body-hash. Verifiering i konstant tid (hash_equals).
- AES-256-GCM: Hemligheter lagras uteslutande som AES-256-GCM-chiffertext (libsodium). Huvudnyckeln ligger utanför databasen i /etc/kh-reseller-api/master.key.v{N}.
- Replay protection: Tidsstämpelfönster +-300s, nonce-cache 600s. En framgångsrikt signerad förfrågan kan inte skickas igen.
- Scope-based authorization: Uttrycklig behörighetslista per nyckel. Skrivande och känsliga behörigheter måste aktiveras uttryckligen.
- IP whitelist (optional): Valfri IP-vitlista per nyckel (CIDR-notation, IPv4 och IPv6).
- Rate limit: Flerskiktad: per nyckel (minut + dag) och per IP (minut). Token-bucket med burst-tolerans.
- Idempotency: Beställningar och destruktiva tjänsteåtgärder kräver en Idempotency-Key. 24h uppspelningsskydd mot nätverksåterförsök.
- Tenant isolation: Varje databasfråga filtrerar strikt på ditt konto-ID. Åtkomst mellan tenanter är konstruktionsmässigt omöjlig.
- Tamper-evident audit log: Varje förfrågan landar i granskningsloggen med chain-hash (chain_hash[n] = sha256(chain_hash[n-1] || row_n)). Retroaktiv manipulation upptäcks omedelbart via hash-brott.
- Credentials.read alerting: Varje credentials.read-anrop genererar en dedikerad granskningspost samt valfritt bekräftelsemejl till kontoägaren.
- SSRF-guarded webhooks: Webhook-URL:er kontrolleras före lagring: endast HTTPS, DNS-uppslag får uteslutande returnera publika IP-adresser (inga RFC1918, inga link-local).
Best practices på din sida
- Lagra hemligheten i en lösenordshanterare (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password), aldrig i kod, aldrig i ett git-repo.
- Rotera hemligheten regelbundet (minst årligen eller efter personalförändringar). Rotation med ett klick i kundportalen, den gamla hemligheten blir omedelbart ogiltig.
- En dedikerad nyckel per användningsfall med minimal behörighet (endast läsning om möjligt). Inga "god-mode"-nycklar.
- Om din integration körs från fasta IP-adresser (moln, bastion): sätt en IP-vitlista.
- Generera Idempotency-Key på serversidan och spara den, generera den inte slumpmässigt vid varje retry. Rekommendation: UUIDv4 per logisk beställning.
- Sätt en webhook till din egen URL, bevaka minst order.created och credentials.read som händelseström.
Säkerhets-disclosure
Rapportera säkerhetsbrister konfidentiellt till security@kernelhost.com. PGP-nyckel på begäran. Svar inom 24 timmar garanteras. Bug-bounty-program under förberedelse.
