Cryptographie et secrets

Toutes les primitives cryptographiques du backend sont regroupées dans backend/src/utils/crypto.util.ts et reposent sur le module crypto de Node.js. Les secrets viennent exclusivement de l'environnement et sont validés au démarrage par backend/src/config/env.config.ts. Cette page décrit ce qui est chiffré, ce qui est haché, comment les secrets sont contrôlés et comment les faire tourner.

#Inventaire

#Chiffrement AES-256-GCM

#Clé

ENCRYPTION_KEY contient 64 caractères hexadécimaux, soit 32 octets. Le schéma d'environnement refuse toute autre forme. La clé est chargée une fois au démarrage par Buffer.from(env.ENCRYPTION_KEY, 'hex').

#Format v2:

v2:<iv en base64url>:<étiquette en base64url>:<texte chiffré en base64url>

L'IV de 12 octets est la taille recommandée pour GCM. Il est tiré au hasard pour chaque valeur ; avec quelques milliers de valeurs chiffrées sous une même clé, le risque de collision est négligeable. L'étiquette rend le chiffrement authentifié : une valeur modifiée en base ou déchiffrée avec une autre clé fait échouer decipher.final() au lieu de produire une clé privée erronée.

#Format binaire des pièces d'identité

Les images des pièces d'identité sont stockées dans des colonnes BYTEA de IdentityDocument sous une forme binaire, sans préfixe de version :

<iv : 12 octets><étiquette : 16 octets><image chiffrée>

encryptBuffer tire un IV par image, et decryptBuffer refuse une valeur trop courte puis vérifie l'étiquette. Les deux faces sont chiffrées séparément. Le déchiffrement n'a lieu que dans GET /api/admin/identity-verifications/:id, tant que la demande est en attente ; l'image déchiffrée part au navigateur de l'agent en data: URL avec Cache-Control: no-store. La décision remet les deux colonnes à NULL.

#Ancien format CBC

decryptText accepte encore, en lecture seule, l'ancien format iv:données en hexadécimal chiffré en AES-256-CBC. Ce format n'est plus jamais écrit. Il est non authentifié ; le garder en lecture permet de relire d'anciennes valeurs, mais aucune donnée du schéma actuel ne devrait plus l'utiliser. readTotpSecret de backend/src/api/auth/auth.services.ts accepte aussi un secret TOTP en clair s'il ne porte pas le préfixe v2:, pour la même raison de compatibilité.

#Hachage

bcrypt est fourni par bcryptjs, une implémentation en JavaScript pur : un hachage au coût 12 consomme le processeur du processus Node.js pendant plusieurs centaines de millisecondes, partagées avec toutes les autres requêtes. La limite de 30 requêtes en 10 minutes par adresse IP sur les routes d'authentification borne cette charge, mais une attaque distribuée sur /signin ralentirait toute l'API. Une implémentation native (bcrypt) ou un hachage dans un thread de travail l'éviterait.

#Aléa et comparaisons

Aucun appel à Math.random n'intervient dans une valeur de sécurité. Il sert seulement à étaler les durées de cache (withJitter de backend/src/config/redis.config.ts).

#Secrets refusés en production

Quand NODE_ENV vaut production, la validation superRefine du schéma d'environnement arrête le processus si l'une de ces conditions est vraie :

Le processus écrit la liste des problèmes sur la sortie d'erreur puis s'arrête avec le code 1 :

Configuration invalide, démarrage interrompu :
  - JWT_SECRET : JWT_SECRET utilise la valeur de développement, interdite en production

Toutes les variables sont aussi vérifiées en forme dans tous les environnements : JWT_SECRET d'au moins 16 caractères, ENCRYPTION_KEY de 64 caractères hexadécimaux, RELAYER_PRIVATE_KEY au format 0x suivi de 64 caractères hexadécimaux, WEBHOOK_SECRET d'au moins 8 caractères.

Le fichier docker-compose.yml lance le backend avec NODE_ENV: production et transmet ${JWT_SECRET:-} : sans valeur dans l'environnement de l'hôte, la variable est une chaîne vide, que la longueur minimale refuse. La stack en conteneurs ne démarre donc pas sans secrets explicites. La procédure est décrite dans Stack complète en conteneurs.

La liste complète des variables est sur la page Variables d'environnement. Le fichier backend/.env.example est comparé au schéma par npm run env:check en CI.

#Stockage des secrets

#Rotation

Il n'existe pas d'outil de rotation automatisé. Le tableau donne l'effet de chaque rotation manuelle et le travail qu'elle demande.

La sauvegarde de ENCRYPTION_KEY est aussi critique que celle de la base : l'une sans l'autre ne permet pas de restaurer les portefeuilles. Voir Sauvegardes et reprise.

#Limites connues