API je navrženo s předpokladem, že každé volání má přímý finanční dopad a může přistupovat k citlivým serverovým přístupovým údajům. Bezpečnostní požadavky proto výrazně přesahují standardní úroveň REST.
Nasazená bezpečnostní opatření
- HMAC-SHA256: Každý požadavek je podepsán HMAC-SHA256 přes metodu, cestu, časové razítko, nonce a hash těla. Ověření v konstantním čase (hash_equals).
- AES-256-GCM: Tajné klíče jsou ukládány výhradně jako šifrovaný text AES-256-GCM (libsodium). Hlavní klíč leží mimo databázi v /etc/kh-reseller-api/master.key.v{N}.
- Replay protection: Časové okno +-300 s, cache nonce 600 s. Úspěšně podepsaný požadavek nelze odeslat znovu.
- Scope-based authorization: Explicitní seznam oprávnění pro každý klíč. Zapisovací a citlivá oprávnění musí být výslovně povolena.
- IP whitelist (optional): Volitelný seznam povolených IP pro každý klíč (notace CIDR, IPv4 i IPv6).
- Rate limit: Vícevrstvé: pro každý klíč (minuta a den) a pro každou IP (minuta). Token bucket s tolerancí burstu.
- Idempotency: Objednávky a destruktivní servisní akce vyžadují Idempotency-Key. Ochrana proti opakování 24 hodin proti opakovaným pokusům v síti.
- Tenant isolation: Každý databázový dotaz tvrdě filtruje podle Vašeho ID účtu. Přístup napříč nájemníky je už konstrukcí nemožný.
- Tamper-evident audit log: Každý požadavek se ukládá do auditního logu s chain hashem (chain_hash[n] = sha256(chain_hash[n-1] || row_n)). Zpětná manipulace je okamžitě detekována zlomem hashe.
- Credentials.read alerting: Každé volání credentials.read vytvoří dedikovaný auditní záznam a volitelný potvrzovací e-mail vlastníkovi účtu.
- SSRF-guarded webhooks: Webhook URL jsou před uložením prověřovány: pouze HTTPS, DNS resolution smí vracet pouze veřejné IP (žádné RFC1918, žádné link-local).
Osvědčené postupy na Vaší straně
- Tajný klíč ukládejte do správce tajných klíčů (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password), nikdy ne v kódu, nikdy ne v git repozitáři.
- Tajný klíč pravidelně obnovujte (minimálně jednou ročně nebo po personální změně). Obnova v zákaznickém portálu jedním kliknutím, starý tajný klíč je okamžitě neplatný.
- Pro každý případ použití jeden vyhrazený klíč s minimálním oprávněním (pokud možno pouze pro čtení). Žádné klíče v režimu "god-mode".
- Pokud Vaše integrace běží z pevných IP (cloud, bastion): nastavte seznam povolených IP.
- Idempotency-Key generujte na straně serveru a uchovávejte jej, neregenerujte při každém opakování. Doporučení: UUIDv4 pro každou logickou objednávku.
- Nastavte webhook na vlastní URL, sledujte minimálně order.created a credentials.read jako proud událostí.
Bezpečnostní disclosure
Bezpečnostní problémy hlaste důvěrně na security@kernelhost.com. PGP klíč na vyžádání. Reakce do 24 hodin zaručena. Bug-bounty program v přípravě.
