L'API est conçue en partant du principe que chaque appel a un impact financier direct et peut accéder à des identifiants de serveur sensibles. Les exigences de sécurité dépassent donc nettement les normes REST.
Contrôles en place
- HMAC-SHA256: Chaque requête est signée en HMAC-SHA256 sur méthode, chemin, horodatage, nonce et empreinte du corps. Vérification à temps constant (hash_equals).
- AES-256-GCM: Les secrets sont uniquement persistés sous forme de cryptogrammes AES-256-GCM (libsodium). La clé maîtresse réside hors de la base de données dans /etc/kh-reseller-api/master.key.v{N}.
- Replay protection: Fenêtre d'horodatage de +-300s, cache de nonce 600s. Une requête correctement signée ne peut pas être rejouée.
- Scope-based authorization: Liste de permissions explicite par clé. Les permissions d'écriture et sensibles doivent être activées explicitement.
- IP whitelist (optional): Liste blanche d'adresses IP optionnelle par clé (notation CIDR, IPv4 et IPv6).
- Rate limit: Multi-couches : par clé (minute et jour) et par IP (minute). Seau à jetons avec tolérance aux rafales.
- Idempotency: Les commandes et les actions de service destructrices exigent un Idempotency-Key. Protection anti-rejeu de 24h contre les nouvelles tentatives réseau.
- Tenant isolation: Chaque requête en base filtre strictement sur votre identifiant de compte. L'accès entre locataires est impossible par construction.
- Tamper-evident audit log: Chaque requête atterrit dans le journal d'audit avec un hachage chaîné (chain_hash[n] = sha256(chain_hash[n-1] || row_n)). Toute altération rétroactive est détectée par rupture de hachage.
- Credentials.read alerting: Chaque appel credentials.read produit une entrée d'audit dédiée plus un e-mail de confirmation optionnel au titulaire du compte.
- SSRF-guarded webhooks: Les URL de webhook sont vérifiées avant stockage : HTTPS uniquement, la résolution DNS ne doit renvoyer que des IP publiques (pas de RFC1918, pas de lien local).
Bonnes pratiques de votre côté
- Stockez le secret dans un gestionnaire de secrets (HashiCorp Vault, AWS Secrets Manager, Doppler, 1Password), jamais dans le code, jamais dans un dépôt Git.
- Faites tourner le secret régulièrement (au moins une fois par an ou après un changement de personnel). Rotation en un clic dans le portail, l'ancien secret est invalidé immédiatement.
- Une clé dédiée par cas d'usage avec la permission minimale (lecture seule si possible). Pas de clés "tout-puissant".
- Si votre intégration s'exécute depuis des IP fixes (cloud, bastion) : configurez une liste blanche d'adresses IP.
- Générez l'Idempotency-Key côté serveur et persistez-le ; ne le régénérez pas à chaque réessai. Recommandation : UUIDv4 par commande logique.
- Définissez un webhook vers votre propre URL ; surveillez au minimum order.created et credentials.read comme flux d'événements.
Divulgation de sécurité
Veuillez signaler les problèmes de sécurité de manière confidentielle à security@kernelhost.com. Clé PGP sur demande. Réponse garantie sous 24h. Programme bug-bounty en préparation.
