Aller au contenu

PD-36 — Plan d'implémentation

📚 Navigation User Story | Document | | | ---------- | -- | | 📋 [Spécification](PD-36-specification.md) | | | 🛠️ **Plan d'implémentation** | *(ce document)* | | ✅ [Critères d'acceptation](PD-36-acceptability.md) | | | 📝 [Retour d'expérience](PD-36-rex.md) | | [← Retour à crypto-proof](../PD-189-epic.md) · [↑ Index User Story](index.md)

Objectif

Implémenter un client HSM Cloud compatible PKCS#11 pour les opérations cryptographiques sensibles.

Choix techniques retenus

  • HSM : AWS CloudHSM (FIPS 140-2 Level 3)
  • Interface : PKCS#11 via pkcs11js
  • Connectivité : VPN Site-to-Site OVH ↔ AWS
  • Lifecycle : NestJS OnModuleInit/OnModuleDestroy

Architecture ciblée

src/modules/crypto/hsm/
├── hsm.module.ts                    # Module NestJS
├── hsm.service.ts                   # Service principal
├── hsm.config.ts                    # Configuration
├── interfaces/
│   └── pkcs11.interface.ts          # Types PKCS#11
└── providers/
    ├── cloudhsm-pkcs11.provider.ts  # Provider réel
    └── pkcs11-mock.provider.ts      # Mock pour tests

Découpage technique

Phase 1 : Configuration

  1. Définir variables d'environnement :
  2. CLOUDHSM_LIBRARY_PATH
  3. CLOUDHSM_PIN
  4. CLOUDHSM_SLOT
  5. CLOUDHSM_USER
  6. CLOUDHSM_SESSION_TIMEOUT

  7. CLOUDHSM_MAX_SESSIONS

  8. Créer HsmConfig avec validation

Phase 2 : Interfaces PKCS#11

  1. Définir types :
  2. IPkcs11Session
  3. KeyAttributes
  4. SignatureAlgorithm
  5. SignatureResult
  6. VerificationResult
  7. KeyType (ECDSA_P256, RSA_4096)

Phase 3 : Provider CloudHSM

  1. CloudHsmPkcs11Provider :
  2. initialize() : Charger libcloudhsm_pkcs11.so
  3. createSession() : Ouvrir session slot

  4. finalize() : Fermer proprement

  5. CloudHsmPkcs11Operations :

  6. sign(data, keyLabel, algorithm)
  7. verify(data, signature, keyLabel, algorithm)
  8. generateKeyPair(keyType, attributes)
  9. findKey(label)
  10. deleteKey(label)
  11. listKeys()

Phase 4 : HSM Service

  1. Lifecycle NestJS :
  2. onModuleInit() : Initialize provider

  3. onModuleDestroy() : Finalize provider

  4. Méthodes publiques :

  5. sign(), verify()
  6. generateKeyPair()
  7. findKey(), listKeys()
  8. isEnabled(), isSessionActive()

Phase 5 : Gestion certificats

  1. createCsr(subject, keyLabel) :
  2. Générer CSR avec clé HSM

  3. Retourner PEM

  4. storeCertificate(cert, keyLabel) :

  5. Importer certificat signé

  6. Lier à la clé

  7. getCertificate(keyLabel) :

  8. Récupérer certificat DER

Phase 6 : mTLS

  1. buildMtlsAgent(config) :
  2. Créer https.Agent avec cert HSM
  3. Signature déléguée au HSM
  4. Clé privée jamais exposée

Phase 7 : Rotation clés

  1. rotateKey(currentLabel, newLabel, keyType) :
  2. Générer nouvelle clé
  3. Archiver ancienne (rename)
  4. Retourner résultat

Phase 8 : Tests

  1. Tests unitaires avec mock provider
  2. Tests intégration avec CloudHSM réel
  3. Tests signature/vérification
  4. Tests gestion erreurs

Points de vigilance

  • HSM obligatoire : Pas de fallback, erreur si indisponible
  • VPN : Vérifier connectivité OVH ↔ AWS
  • Session timeout : Renouveler avant expiration
  • Logs : Jamais de clés ou données sensibles

Hors périmètre

  • Provisioning HSM (→ Terraform)
  • Création clés initiales (→ procédure manuelle)
  • Signature audit logs (→ PD-37)

Annexes