CloudHSM Integration Tests - Guide d'Exécution¶
PD-36 : Client HSM Cloud PKCS#11
Ce document explique comment exécuter les tests d'intégration CloudHSM.
⚠️ Prérequis¶
1. Infrastructure AWS¶
- ✅ CloudHSM Cluster actif (eu-west-3)
- ✅ Au moins 1 HSM actif dans le cluster
- ✅ VPN site-to-site configuré (OVH ↔ AWS)
2. CloudHSM Client SDK¶
Sur le serveur/machine de test :
# Ubuntu 22.04
wget https://s3.amazonaws.com/cloudhsmv2-software/CloudHsmClient/Ubuntu2204/cloudhsm-client_latest_amd64.deb
sudo dpkg -i cloudhsm-client_latest_amd64.deb
# Vérification installation
ls -la /opt/cloudhsm/lib/libcloudhsm_pkcs11.so
3. Configuration CloudHSM¶
# Configuration cluster
sudo /opt/cloudhsm/bin/configure -a <cluster-ip>
# Vérification
/opt/cloudhsm/bin/cloudhsm_mgmt_util
# Dans l'utilitaire: listUsers
4. Crypto User (CU)¶
Créer un Crypto User si nécessaire :
/opt/cloudhsm/bin/cloudhsm_mgmt_util
# Se connecter en tant que CO (Crypto Officer)
loginHSM CO <username> <password>
# Créer CU
createUser CU <username> <password>
# Lister utilisateurs
listUsers
# Déconnexion
quit
🔧 Configuration Environnement¶
Variables d'Environnement¶
Créer .env.integration :
# CloudHSM Configuration
CLOUDHSM_ENABLED=true
CLOUDHSM_LIBRARY_PATH=/opt/cloudhsm/lib/libcloudhsm_pkcs11.so
CLOUDHSM_PIN=<crypto-user-password>
CLOUDHSM_SLOT=0
CLOUDHSM_USER=crypto_user
# Session Configuration
CLOUDHSM_SESSION_TIMEOUT=300000
CLOUDHSM_MAX_SESSIONS=10
⚠️ IMPORTANT : Ne JAMAIS commit .env.integration dans Git !
Chargement Variables¶
# Option 1 : Export manuel
export $(cat .env.integration | xargs)
# Option 2 : dotenv
npm install --save-dev dotenv-cli
npx dotenv -e .env.integration -- npm run test:integration
🧪 Exécution Tests¶
Tests Complets¶
# Tous les tests d'intégration CloudHSM
CLOUDHSM_ENABLED=true \
CLOUDHSM_LIBRARY_PATH=/opt/cloudhsm/lib/libcloudhsm_pkcs11.so \
CLOUDHSM_PIN=<pin> \
npm run test:integration -- cloudhsm
Tests Spécifiques¶
# Provider initialization seulement
npm run test:integration -- cloudhsm -t "Provider Initialization"
# ECDSA operations seulement
npm run test:integration -- cloudhsm -t "ECDSA Operations"
# RSA operations seulement
npm run test:integration -- cloudhsm -t "RSA-PSS Operations"
# Error handling seulement
npm run test:integration -- cloudhsm -t "Error Handling"
# Performance benchmarks seulement
npm run test:integration -- cloudhsm -t "Performance Benchmarks"
Tests avec Verbose Output¶
📊 Tests Disponibles¶
1. Provider Initialization (4 tests)¶
- ✅ Load CloudHSM PKCS#11 library
- ✅ Get library info
- ✅ Get slot info
- ✅ Create and close session
Durée estimée : ~5-10 secondes
2. ECDSA Operations (6 tests)¶
- ✅ Generate ECDSA P-256 key pair
- ✅ Find generated key
- ✅ Sign data with ECDSA-SHA256
- ✅ Verify valid signature
- ✅ Reject invalid signature
- ✅ List keys
Durée estimée : ~30-60 secondes
3. RSA-PSS Operations (3 tests)¶
- ✅ Generate RSA 4096 key pair
- ✅ Sign data with RSA-PSS-SHA256
- ✅ Verify RSA-PSS signature
Durée estimée : ~60-120 secondes (génération RSA lente)
4. Error Handling (3 tests)¶
- ✅ Handle non-existent key gracefully
- ✅ Throw error when signing with non-existent key
- ✅ Return error when verifying with non-existent key
Durée estimée : ~5 secondes
5. Performance Benchmarks (2 tests)¶
- ✅ Measure sign performance (100 iterations)
- ✅ Measure verify performance (100 iterations)
Durée estimée : ~2-4 minutes
🎯 Résultats Attendus¶
Tests Passants¶
PASS src/modules/crypto/hsm/providers/cloudhsm-pkcs11.provider.integration.spec.ts
Provider Initialization
✓ should load CloudHSM PKCS#11 library (234ms)
✓ should get CloudHSM library info (156ms)
✓ should get CloudHSM slot info (134ms)
✓ should create and close session (178ms)
ECDSA Operations
✓ should generate ECDSA P-256 key pair on CloudHSM (4521ms)
✓ should find generated ECDSA key (123ms)
✓ should sign data with ECDSA-SHA256 on CloudHSM (187ms)
✓ should verify ECDSA signature on CloudHSM (145ms)
✓ should reject invalid ECDSA signature (156ms)
✓ should list keys including test key (234ms)
RSA-PSS Operations
✓ should generate RSA 4096 key pair on CloudHSM (25643ms)
✓ should sign data with RSA-PSS-SHA256 on CloudHSM (298ms)
✓ should verify RSA-PSS signature on CloudHSM (267ms)
Error Handling
✓ should handle non-existent key gracefully (89ms)
✓ should throw error when signing with non-existent key (112ms)
✓ should return error when verifying with non-existent key (98ms)
Performance Benchmarks
✓ should measure sign performance (100 iterations) (18765ms)
✓ should measure verify performance (100 iterations) (14532ms)
Test Suites: 1 passed, 1 total
Tests: 18 passed, 18 total
Time: 65.432 s
Logs de Performance¶
📊 CloudHSM Library Info: {
cryptokiVersion: '2.40',
manufacturerID: 'Cavium Networks',
libraryDescription: 'CloudHSM PKCS#11 Library'
}
📊 CloudHSM Slot Info: {
slotDescription: 'CloudHSM Slot 0',
manufacturerID: 'Cavium',
hardwareVersion: '3.2',
firmwareVersion: '3.2.1'
}
⏱️ ECDSA Key Generation: 4521ms
⏱️ ECDSA Sign: 187ms
📏 Signature size: 64 bytes
⏱️ ECDSA Verify: 145ms
⏱️ RSA 4096 Key Generation: 25643ms
⏱️ RSA-PSS Sign: 298ms
📏 Signature size: 512 bytes
⏱️ RSA-PSS Verify: 267ms
📋 Total keys in HSM: 3
📊 ECDSA Sign Performance (100 iterations):
Average: 192.34ms
Min: 145ms
Max: 456ms
📊 ECDSA Verify Performance (100 iterations):
Average: 151.67ms
Min: 123ms
Max: 289ms
🚫 Tests Skippés¶
Si CLOUDHSM_ENABLED !== 'true', tous les tests sont automatiquement skippés :
⏭️ Skipping CloudHSM integration tests (CLOUDHSM_ENABLED !== true)
Test Suites: 1 skipped, 0 of 1 total
Tests: 18 skipped, 18 total
C'est le comportement par défaut pour permettre les tests unitaires sans CloudHSM.
🐛 Troubleshooting¶
Erreur: Library not found¶
Solution :
# Vérifier installation SDK
ls -la /opt/cloudhsm/lib/libcloudhsm_pkcs11.so
# Vérifier path dans .env
CLOUDHSM_LIBRARY_PATH=/opt/cloudhsm/lib/libcloudhsm_pkcs11.so
Erreur: PIN incorrect¶
Solution : - Vérifier CLOUDHSM_PIN correspond au mot de passe CU - Se connecter avec cloudhsm_mgmt_util pour reset PIN si nécessaire
Erreur: No HSM slots available¶
Solution :
# Vérifier cluster actif
/opt/cloudhsm/bin/cloudhsm_mgmt_util
listUsers
# Vérifier configuration
cat /opt/cloudhsm/etc/cloudhsm_client.cfg
Erreur: Session timeout¶
Solution : - Augmenter CLOUDHSM_SESSION_TIMEOUT - Vérifier connexion réseau VPS → CloudHSM
Erreur: Permission denied¶
Solution :
🔐 Sécurité¶
Gestion PIN¶
❌ Ne PAS faire :
✅ Faire :
# Ansible Vault
ansible-vault encrypt_string 'MySecretPin123' --name 'vault_cloudhsm_pin'
# GitLab CI/CD Variables (masked, protected)
CLOUDHSM_PIN=***
# Variable d'environnement système
export CLOUDHSM_PIN=$(vault kv get -field=pin secret/cloudhsm)
Cleanup Test Keys¶
Les tests créent des clés temporaires : - integration-test-ecdsa-<timestamp> - integration-test-rsa-<timestamp> - benchmark-key-<timestamp>
Cleanup automatique : Les tests suppriment les clés dans afterAll()
Cleanup manuel (si tests interrompus) :
/opt/cloudhsm/bin/key_mgmt_util
# Login
loginHSM -u CU -s <username> -p <password>
# Lister clés
findKey -l integration-test
# Supprimer clé
deleteKey -k <key-handle>
📈 Monitoring¶
Métriques à Collecter¶
- Latence sign/verify
- Nombre de clés générées
- Taux d'erreur
- Durée sessions
Logs CloudHSM¶
# Logs Client SDK
tail -f /opt/cloudhsm/run/cloudhsm-client.log
# Logs PKCS#11
tail -f /opt/cloudhsm/run/pkcs11-trace.log
✅ Checklist Avant Exécution¶
- CloudHSM Cluster actif
- CloudHSM Client SDK installé
- VPN configuré (OVH ↔ AWS)
- Crypto User (CU) créé
- Variables d'environnement configurées
-
.env.integrationcréé (non committé) - Connexion HSM testée (
cloudhsm_mgmt_util)
📞 Support¶
Erreurs CloudHSM : Consulter AWS CloudHSM Documentation
Erreurs pkcs11js : Consulter pkcs11js GitHub Issues
Tests ProbatioVault : Créer issue dans projet ProbatioVault