Die API ist mit der Annahme entworfen, dass jeder Aufruf direkten finanziellen Einfluss hat und auf sensible Server-Credentials zugreifen kann. Sicherheits-Anforderungen liegen daher deutlich über dem REST-Standard.
Eingesetzte Schutz-Mechanismen
- HMAC-SHA256: Jede Anfrage wird mit HMAC-SHA256 über Methode, Pfad, Timestamp, Nonce und Body-Hash signiert. Verifikation in Konstant-Zeit (hash_equals).
- AES-256-GCM: Secrets werden ausschließlich AES-256-GCM-verschlüsselt persistiert (libsodium). Master-Key liegt außerhalb der Datenbank in /etc/kh-reseller-api/master.key.v{N}.
- Replay protection: Timestamp-Fenster +-300s, Nonce-Cache 600s. Eine erfolgreich signierte Anfrage kann nicht erneut gesendet werden.
- Scope-based authorization: Pro Key explizite Scope-Liste. Schreibende und sensible Scopes müssen ausdrücklich aktiviert werden.
- IP whitelist (optional): Optionale IP-Whitelist pro Key (CIDR-Notation, IPv4 und IPv6).
- Rate limit: Mehrschichtig: pro Key (Minute + Tag) und pro IP (Minute). Token-Bucket mit Burst-Toleranz.
- Idempotency: Bestellungen und destruktive Service-Aktionen verlangen einen Idempotency-Key. 24h Replay-Schutz gegen Netzwerk-Retries.
- Tenant isolation: Jede Datenbank-Abfrage filtert hart auf Ihre Account-ID. Cross-Tenant-Zugriff ist konstruktionsbedingt unmöglich.
- Tamper-evident audit log: Jeder Request landet im Audit-Log mit Chain-Hash (chain_hash[n] = sha256(chain_hash[n-1] || row_n)). Retroaktive Manipulation wird durch Hash-Bruch sofort erkannt.
- Credentials.read alerting: Jeder credentials.read Aufruf erzeugt einen dedizierten Audit-Eintrag plus optionale Bestätigungs-Mail an den Account-Owner.
- SSRF-guarded webhooks: Webhook-URLs werden vor Speichern geprüft: HTTPS only, DNS-Resolution darf ausschließlich öffentliche IPs liefern (keine RFC1918, keine Link-Local).
Best Practices auf Reseller-Seite
- Secret in einem Secret-Manager speichern (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password), nie im Code, nie im Git-Repo.
- Secret regelmäßig rotieren (mindestens jährlich oder nach Personalwechsel). Rotation im Kundenportal mit einem Klick, altes Secret wird sofort ungültig.
- Pro Anwendungsfall einen eigenen Key mit minimalem Scope (read-only wenn möglich). Keine "God-Mode"-Keys.
- Wenn Ihre Integration aus festen IPs läuft (Cloud, Bastion): IP-Whitelist setzen.
- Idempotency-Key serverseitig generieren und persistieren, nicht zufällig pro Retry neu. Empfehlung: UUIDv4 pro logischer Bestellung.
- Webhook auf eigene URL setzen, mind. order.created und credentials.read als Event-Stream beobachten.
Sicherheits-Disclosure
Sicherheits-Lücken bitte vertraulich melden an security@kernelhost.com. PGP-Key auf Anfrage. Reaktion in 24h zugesichert. Bug-Bounty-Programm in Vorbereitung.
