De API is ontworpen vanuit de aanname dat elke aanroep directe financiële impact heeft en toegang kan geven tot gevoelige servergegevens. De beveiligingseisen liggen daarom duidelijk boven de REST-standaard.
Toegepaste beschermingsmaatregelen
- HMAC-SHA256: Elke aanvraag wordt met HMAC-SHA256 ondertekend over methode, pad, tijdstempel, nonce en body-hash. Verificatie in constante tijd (hash_equals).
- AES-256-GCM: Geheime sleutels worden uitsluitend AES-256-GCM-versleuteld opgeslagen (libsodium). De hoofdsleutel ligt buiten de database in /etc/kh-reseller-api/master.key.v{N}.
- Replay protection: Tijdstempelvenster +-300s, nonce-cache 600s. Een succesvol ondertekende aanvraag kan niet opnieuw worden verzonden.
- Scope-based authorization: Per sleutel een expliciete lijst met machtigingen. Schrijvende en gevoelige machtigingen moeten uitdrukkelijk worden ingeschakeld.
- IP whitelist (optional): Optionele IP-toegangslijst per sleutel (CIDR-notatie, IPv4 en IPv6).
- Rate limit: Meerlaags: per sleutel (minuut plus dag) en per IP (minuut). Token-bucket met burst-tolerantie.
- Idempotency: Bestellingen en destructieve service-acties vereisen een Idempotency-Key. 24 uur replay-bescherming tegen netwerk-retries.
- Tenant isolation: Elke databasequery filtert hard op uw account-id. Toegang tussen klanten is door de constructie onmogelijk.
- Tamper-evident audit log: Elke aanvraag belandt in het auditlogboek met chain-hash (chain_hash[n] = sha256(chain_hash[n-1] || row_n)). Achteraf manipuleren wordt direct herkend door breuk in de hashketen.
- Credentials.read alerting: Elke credentials.read-aanroep genereert een aparte audit-vermelding plus optionele bevestigingsmail aan de accounthouder.
- SSRF-guarded webhooks: Webhook-URL's worden vóór opslag gecontroleerd: uitsluitend HTTPS, DNS-resolutie mag alleen publieke IP-adressen opleveren (geen RFC1918, geen link-local).
Best practices aan uw kant
- Bewaar de geheime sleutel in een secret-manager (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password), nooit in code, nooit in een git-repo.
- Roteer de geheime sleutel regelmatig (minimaal jaarlijks of na personeelswisselingen). Rotatie in het klantenportaal met één klik, de oude geheime sleutel is direct ongeldig.
- Per use-case één eigen sleutel met de minimale machtigingen (alleen-lezen indien mogelijk). Geen "god-mode"-sleutels.
- Draait uw integratie vanaf vaste IP-adressen (cloud, bastion), stel dan een IP-toegangslijst in.
- Genereer de Idempotency-Key serverzijdig en bewaar deze, niet willekeurig opnieuw per retry. Aanbeveling: UUIDv4 per logische bestelling.
- Stel een webhook naar uw eigen URL in en bewaak minimaal order.created en credentials.read als event-stream.
Beveiligings-disclosure
Meld beveiligingsproblemen vertrouwelijk aan security@kernelhost.com. PGP-sleutel op aanvraag. Reactie binnen 24 uur gegarandeerd. Bug-bounty-programma in voorbereiding.
