-
Notifications
You must be signed in to change notification settings - Fork 162
hsmCompatVerify Combined Examples
This document demonstrates HSM compatibility verification for both traditional (RSA/EC) and post-quantum (ML-DSA/ML-KEM) key archival and recovery using the hsmCompatVerify tools.
|
Important
|
Please read the Important Notes and Disclaimers on the main hsmCompatVerify page regarding HSM compatibility testing limitations and best practices. |
Tested Workflows: The examples in this document demonstrate workflows that have been tested with the listed configurations. Results may vary with different HSM vendors and models.
What’s New in v11.10:
-
Full ML-DSA (NIST FIPS 204) CA signing support
-
ML-KEM (NIST FIPS 203) transport/storage key support
-
Enhanced multi-token support (CA and KRA on different HSMs)
-
Improved ML-DSA user certificate key usage handling
Key Points:
-
Verifies HSM compatibility with Dogtag KRA cryptographic operations
-
hsmCompatVerifyis a standalone KRA simulator - no CA/KRA instances needed -
Supports both traditional (RSA/EC) and post-quantum (ML-DSA/ML-KEM) workflows
-
Tests both client-side and server-side operations
-
Supports HSM/PKCS#11 token testing (single-token and multi-token modes)
This document is organized to help you quickly find what you need:
For Most Users:
-
Quick Start Guide - Complete workflows with combined archive + recovery (recommended)
-
Software Token - Learn the tool without HSM
-
HSM with Traditional Crypto (RSA/EC) - Most common production use
-
HSM with Post-Quantum Crypto (ML-DSA/ML-KEM) - Post-quantum ready
-
For Advanced Testing:
-
Part 1: Traditional Cryptography - Detailed workflows for RSA/EC
-
Multi-token configurations (CA and KRA on different tokens)
-
Separate archive and recovery phases (debugging and testing)
-
-
Part 2: Post-Quantum Cryptography - Detailed workflows for ML-DSA/ML-KEM
-
Multi-token configurations (working around HSM limitations)
-
Separate archive and recovery phases (debugging and testing)
-
Additional Resources:
-
Key Highlights - Algorithm support, operations, token modes
-
Troubleshooting - Common issues and solutions
| Component | Version |
|---|---|
NSS |
3.123+ (for ML-KEM/ML-DSA support) |
JSS |
5.10+ (for ML-KEM/ML-DSA support) |
PKI |
11.10+ (this version) |
hsmCompatVerify |
Included in PKI v11.10 |
dogtag-jss-tools |
Required for PKCS#12 import (provides p12tool) |
This section shows the most common usage - verifying compatibility with a complete archival and recovery workflow in a single command.
|
Tip
|
First-time users: Start with the Software Token workflow to learn the tool without needing an HSM. Then proceed to test your actual HSM. |
Create directory structure and initialize NSS databases:
$ mkdir -p ~/demo/hsm-compat/serv ~/demo/hsm-compat/clnt
$ cd ~/demo/hsm-compat
# Create password files
$ echo "Secret.123" > serv/nss.pwd
$ echo "Secret.123" > clnt/nss.pwd
$ echo "Secret.123" > clnt/recover.pwd
# Initialize NSS databases
$ certutil -N -d serv/ -f serv/nss.pwd
$ certutil -N -d clnt/ -f clnt/nss.pwd|
Note
|
All commands below assume you are in the ~/demo/hsm-compat directory.
|
Purpose: Run this first to see what a successful workflow looks like - no HSM required!
This uses the NSS database’s internal token instead of an HSM, perfect for understanding the tool before testing your actual HSM.
$ hsmCompatVerifyServ --setup-only \
--pkiserv-db-path serv \
--pkiserv-passwd-file serv/nss.pwd \
--hsm-token "" \
--hsm-token-passwd-file serv/nss.pwd \
--verboseExpected Output:
-
RSA-4096 CA certificate created (self-signed)
-
RSA-2048 Transport certificate created
-
RSA-2048 Storage certificate created
-
serv/kra_transport.pemandserv/kra_storage.pemexported
$ hsmCompatVerifyClnt \
--client-db-path clnt \
--client-passwd-file clnt/nss.pwd \
--transport-cert serv/kra_transport.pem \
--verboseExpected Output Files:
clnt/kra-test-wrapped-session.bin (256 bytes - RSA-OAEP wrapped session key)
clnt/kra-test-wrapped-private.bin (1224 bytes - AES-KWP wrapped RSA private key)
clnt/kra-test-public.der (294 bytes - RSA public key)$ hsmCompatVerifyServ \
--pkiserv-db-path serv \
--client-db-path clnt \
--hsm-token "" \
--hsm-token-passwd-file serv/nss.pwd \
--subject-dn "CN=Test User" \
--p12-output clnt/recovered.p12 \
--recovery-passwd-file clnt/recover.pwd \
--verboseWhat Happened:
-
Session key unwrapped using transport private key
-
User private key unwrapped successfully
-
User certificate created and signed by CA
-
New session key generated for storage
-
User private key re-wrapped with storage key
-
LDIF file created:
clnt/kra-archived-key.ldif -
Storage session key unwrapped
-
User private key recovered
-
PKCS#12 file created:
clnt/recovered.p12
# Inspect PKCS#12 contents
$ pk12util -l clnt/recovered.p12 -w clnt/recover.pwd
# Import using p12tool (recommended)
$ mkdir -p test-import
$ echo "Secret.123" > test-import/nss.pwd
$ certutil -N -d test-import -f test-import/nss.pwd
$ p12tool -i clnt/recovered.p12 -d test-import -w clnt/recover.pwd
# Verify import
$ certutil -L -d test-import
$ certutil -K -d test-import|
Note
|
Use p12tool -i to import the PKCS#12 file (from dogtag-jss-tools package). If not installed: sudo dnf install dogtag-jss-tools. If unavailable, you can try pk12util -i, though it may not support all PKCS#12 encryption modes.
|
✅ Success! You now understand the tool. Next, test your actual HSM below.
Purpose: Verify your HSM supports RSA/EC key archival and recovery for KRA.
# Create HSM password file
$ echo "HSMPassword123" > serv/hsm.pwd
# Setup CA, transport, and storage certificates on HSM
$ hsmCompatVerifyServ --setup-only \
--pkiserv-db-path serv \
--pkiserv-passwd-file serv/nss.pwd \
--hsm-token "myHSM" \
--hsm-token-passwd-file serv/hsm.pwd \
--verboseExpected Output:
-
RSA-4096 CA certificate created (self-signed) on HSM
-
RSA-2048 Transport certificate created on HSM
-
RSA-2048 Storage certificate created on HSM
-
serv/kra_transport.pemandserv/kra_storage.pemexported
$ hsmCompatVerifyClnt \
--client-db-path clnt \
--client-passwd-file clnt/nss.pwd \
--transport-cert serv/kra_transport.pem \
--verboseExpected Output Files:
clnt/kra-test-wrapped-session.bin (256 bytes - RSA-OAEP wrapped session key)
clnt/kra-test-wrapped-private.bin (1224 bytes - AES-KWP wrapped RSA private key)
clnt/kra-test-public.der (294 bytes - RSA public key)$ hsmCompatVerifyServ \
--pkiserv-db-path serv \
--client-db-path clnt \
--hsm-token "myHSM" \
--hsm-token-passwd-file serv/hsm.pwd \
--subject-dn "CN=Test User" \
--p12-output clnt/recovered.p12 \
--recovery-passwd-file clnt/recover.pwd \
--verboseWhat Happened (all on HSM):
-
Session key unwrapped using transport private key (RSA-OAEP)
-
User private key unwrapped successfully (AES-KWP)
-
User certificate created and signed by CA (RSA-SHA256)
-
New session key generated for storage
-
User private key re-wrapped with storage key
-
LDIF file created:
clnt/kra-archived-key.ldif -
Storage session key unwrapped
-
User private key recovered
-
PKCS#12 file created:
clnt/recovered.p12
# Inspect PKCS#12 contents
$ pk12util -l clnt/recovered.p12 -w clnt/recover.pwd
# Import using p12tool (recommended)
$ mkdir -p test-import
$ echo "Secret.123" > test-import/nss.pwd
$ certutil -N -d test-import -f test-import/nss.pwd
$ p12tool -i clnt/recovered.p12 -d test-import -w clnt/recover.pwd
# Verify import
$ certutil -L -d test-import
$ certutil -K -d test-import|
Note
|
Use p12tool -i to import the PKCS#12 file (from dogtag-jss-tools package). If not installed: sudo dnf install dogtag-jss-tools. If unavailable, you can try pk12util -i, though it may not support all PKCS#12 encryption modes.
|
✅ HSM Compatibility Verified! Your HSM supports all required KRA cryptographic operations for traditional (RSA/EC) algorithms.
Purpose: Verify your HSM supports post-quantum (ML-DSA/ML-KEM) key archival and recovery for KRA.
Requirements: NSS 3.123+, JSS 5.10+
# Create HSM password file (if not already created)
$ echo "HSMPassword123" > serv/hsm.pwd
# Setup PQC CA, transport, and storage certificates on HSM
$ hsmCompatVerifyServ --setup-only \
--pqc \
--pkiserv-db-path serv \
--pkiserv-passwd-file serv/nss.pwd \
--hsm-token "myHSM" \
--hsm-token-passwd-file serv/hsm.pwd \
--verboseExpected Output:
-
ML-DSA-65 CA certificate created (self-signed) on HSM
-
ML-KEM-768 Transport certificate created on HSM
-
ML-KEM-768 Storage certificate created on HSM
-
serv/kra_transport.pemandserv/kra_storage.pemexported
$ hsmCompatVerifyClnt \
--pqc \
--client-db-path clnt \
--client-passwd-file clnt/nss.pwd \
--transport-cert serv/kra_transport.pem \
--user-key-type ML-KEM \
--pqc-kem-algorithm ml-kem-768 \
--verboseExpected Output Files:
clnt/kra-test-kem-ciphertext.bin (1088 bytes - ML-KEM-768 ciphertext)
clnt/kra-test-wrapped-private.bin (2512 bytes - AES-KWP wrapped ML-KEM private key)
clnt/kra-test-public.der (1184 bytes - ML-KEM-768 public key)$ hsmCompatVerifyServ \
--pqc \
--pkiserv-db-path serv \
--client-db-path clnt \
--hsm-token "myHSM" \
--hsm-token-passwd-file serv/hsm.pwd \
--subject-dn "CN=Test PQC User" \
--p12-output clnt/recovered.p12 \
--recovery-passwd-file clnt/recover.pwd \
--user-key-type ML-KEM \
--verboseWhat Happened (all on HSM):
-
ML-KEM decapsulation with transport private key (recovers shared secret)
-
User ML-KEM private key unwrapped successfully (AES-KWP)
-
User certificate created and signed by ML-DSA CA
-
ML-KEM encapsulation with storage public key (generates new shared secret)
-
User private key re-wrapped with storage shared secret
-
LDIF file created:
clnt/kra-archived-key.ldif -
ML-KEM decapsulation with storage private key
-
User ML-KEM private key recovered
-
PKCS#12 file created:
clnt/recovered.p12
# Inspect PKCS#12 contents
$ pk12util -l clnt/recovered.p12 -w clnt/recover.pwd
# Import using p12tool (recommended)
$ mkdir -p test-import
$ echo "Secret.123" > test-import/nss.pwd
$ certutil -N -d test-import -f test-import/nss.pwd
$ p12tool -i clnt/recovered.p12 -d test-import -w clnt/recover.pwd
# Verify import
$ certutil -L -d test-import
$ certutil -K -d test-import|
Note
|
Use p12tool -i to import the PKCS#12 file (from dogtag-jss-tools package). If not installed: sudo dnf install dogtag-jss-tools. If unavailable, you can try pk12util -i, though it may not support all PKCS#12 encryption modes.
|
✅ HSM PQC Compatibility Verified! Your HSM supports all required KRA cryptographic operations for post-quantum (ML-DSA/ML-KEM) algorithms.
This section provides detailed workflows for advanced testing scenarios.
For most users: Use the Quick Start Guide above with combined archive+recovery.
This example shows CA on HSM and KRA on internal NSS DB - an interim test deployment pattern where your HSM is incapable of doing AES-KWP.
$ hsmCompatVerifyServ --setup-only \
--pkiserv-db-path serv \
--pkiserv-passwd-file serv/nss.pwd \
--ca-token "myHSM" \
--ca-token-passwd-file serv/hsm.pwd \
--kra-token "" \
--kra-token-passwd-file serv/nss.pwd \
--verbose|
Note
|
Use --ca-token "" for internal NSS DB, or "tokenName" for HSM. Same applies to --kra-token.
|
When to use this workflow:
-
Testing or debugging individual archival and recovery operations
-
Simulating KRA’s LDIF-based key archival/recovery process
-
Understanding the internals of KRA key wrapping mechanisms
-
Batch testing multiple recovery scenarios from the same archived LDIF
This workflow assumes you’ve already completed the Quick Start Guide’s Initial Setup and Step 1-2 (setup certificates and generate client keys).
If starting fresh, complete those steps first before continuing here.
Unwrap the user’s private key from transport wrapping, re-wrap with storage key, and create LDIF entry.
$ hsmCompatVerifyServ --archive-only \
--pkiserv-db-path serv \
--client-db-path clnt \
--hsm-token "myHSM" \
--hsm-token-passwd-file serv/hsm.pwd \
--subject-dn "CN=Test User" \
--verboseExpected Output:
-
Session key unwrapped using transport private key (HSM)
-
User private key unwrapped successfully
-
User certificate created and signed by CA
-
New session key generated for storage wrapping
-
User private key re-wrapped with storage session key
-
Session key wrapped with storage public key
-
LDIF file created:
clnt/kra-archived-key.ldif(contains certificate + wrapped key data)
Read archived key from LDIF, unwrap with storage key, and export to PKCS#12 file for user.
$ hsmCompatVerifyServ --recover-only \
--pkiserv-db-path serv \
--client-db-path clnt \
--hsm-token "myHSM" \
--hsm-token-passwd-file serv/hsm.pwd \
--p12-output clnt/recovered.p12 \
--recovery-passwd-file clnt/recover.pwd \
--verboseExpected Output:
-
Loaded certificate + wrapped keys from LDIF
-
Session key unwrapped using storage private key (HSM)
-
User private key unwrapped successfully
-
PKCS#12 file created:
clnt/recovered.p12
Verification: See the Quick Start Guide’s Step 4 for PKCS#12 verification steps.
This section provides detailed workflows for advanced PQC testing scenarios.
For most users: Use the Quick Start Guide’s PQC section above.
This example shows CA on HSM and KRA on internal NSS DB - e.g. an interim test deployment pattern where your HSM is capable of handling ml-dsa but does not handle persistant ml-kem key operations (encapsulation/decapsulation).
$ hsmCompatVerifyServ --setup-only \
--pqc \
--pkiserv-db-path serv \
--pkiserv-passwd-file serv/nss.pwd \
--ca-token "myHSM" \
--ca-token-passwd-file serv/hsm.pwd \
--kra-token "" \
--kra-token-passwd-file serv/nss.pwd \
--verboseFollow Steps 2-4 from the PQC Quick Start Guide, but use the multi-token flags:
-
Replace
--hsm-token "myHSM"with--ca-token "myHSM" --kra-token "" -
Use
--ca-token-passwd-file serv/hsm.pwd --kra-token-passwd-file serv/nss.pwd -
Add
--pqcand--user-key-type ML-KEMflags
When to use this workflow:
-
Testing or debugging individual PQC archival and recovery operations
-
Understanding ML-KEM encapsulation/decapsulation internals
-
Batch testing multiple PQC recovery scenarios from the same archived LDIF
This workflow assumes you’ve already completed the Quick Start Guide’s PQC Initial Setup and Steps 1-2 (setup PQC certificates and generate client ML-KEM keys).
If starting fresh, complete those steps first before continuing here.
Decapsulate shared secret, unwrap user’s ML-KEM key, re-encapsulate with storage key, and create LDIF entry.
$ hsmCompatVerifyServ --archive-only \
--pqc \
--pkiserv-db-path serv \
--client-db-path clnt \
--hsm-token "myHSM" \
--hsm-token-passwd-file serv/hsm.pwd \
--subject-dn "CN=Test PQC User" \
--user-key-type ML-KEM \
--verboseExpected Output:
-
ML-KEM decapsulation with transport private key (HSM)
-
User ML-KEM private key unwrapped successfully
-
User certificate created and signed by ML-DSA CA
-
ML-KEM encapsulation with storage public key (generates new shared secret)
-
User private key re-wrapped with storage shared secret
-
LDIF file created:
clnt/kra-archived-key.ldif
Read archived key from LDIF, decapsulate with storage key, unwrap user key, and export to PKCS#12.
$ hsmCompatVerifyServ --recover-only \
--pqc \
--pkiserv-db-path serv \
--client-db-path clnt \
--hsm-token "myHSM" \
--hsm-token-passwd-file serv/hsm.pwd \
--p12-output clnt/recovered.p12 \
--recovery-passwd-file clnt/recover.pwd \
--user-key-type ML-KEM \
--verboseExpected Output:
-
Loaded certificate + wrapped keys from LDIF
-
ML-KEM decapsulation with storage private key (HSM)
-
User ML-KEM private key unwrapped successfully
-
PKCS#12 file created:
clnt/recovered.p12
Verification: See the Quick Start Guide’s Step 4 for PKCS#12 verification steps.
-
ML-DSA CA Support: Full support for ML-DSA (FIPS 204) signing certificates
-
ML-KEM Transport/Storage: ML-KEM (FIPS 203) for quantum-resistant key wrapping
-
Multi-Token Support: CA and KRA keys can be on different HSM tokens
-
Improved Key Usage: Correct key usage extensions for ML-DSA (signature-only) certificates
| Key Type | Traditional (RSA/EC) | Post-Quantum (PQC) |
|---|---|---|
CA Signing |
RSA-4096 or EC-nistp256 |
ML-DSA-65 |
Transport |
RSA-2048 |
ML-KEM-768 |
Storage |
RSA-2048 |
ML-KEM-768 |
User Keys |
RSA-2048/4096, EC-nistp256 |
ML-KEM-768, ML-DSA-65 |
Traditional (RSA/EC):
-
RSA-OAEP: Session key wrapping with transport/storage public keys
-
AES-256-KWP: Private key wrapping (RFC 5649, FIPS-compliant)
-
AES-256-KWP: PKCS#12 private key encryption (default
--pkcs12-mode kwp)
Post-Quantum (ML-DSA/ML-KEM):
-
ML-KEM encapsulation/decapsulation: Post-quantum key establishment
-
AES-256-KWP: Private key wrapping
-
AES-256-KWP: PKCS#12 private key encryption (default
--pkcs12-mode kwp)
Alternative PKCS#12 modes:
-
--pkcs12-mode cbc: PBKDF2 + AES-256-CBC (for compatibility) -
--pkcs12-mode legacy: PBE_SHA1_DES3_CBC (legacy only, not recommended)
Single-Token Mode:
Use --hsm-token when all certificates (CA, transport, storage) are on the same HSM token.
Multi-Token Mode:
Use --ca-token and --kra-token when CA and KRA certificates are on different tokens. This is useful for:
-
Separating CA and KRA security domains
-
Using HSM for CA and software token for KRA (or vice versa)
-
Testing different HSM configurations
# Check NSS version (should be 3.123+)
$ rpm -q nss
# Check for ML-KEM support
$ nss-build-flags | grep -i ml-kem
# Check JSS version (should be 5.10+)
$ rpm -q jssIssue: ML-KEM key generation fails
Solution: Verify NSS 3.123+ is installed and ML-KEM support is enabled
Issue: PKCS#12 export fails for ML-KEM keys with AES-KWP mode
Solution: Try --pkcs12-mode cbc instead of --pkcs12-mode kwp if the token does not support AES-KWP
Issue: p12tool command not found
Solution: Install dogtag-jss-tools package:
sudo dnf install dogtag-jss-toolsIssue: Cannot import recovered.p12 file
Solution: Use p12tool -i instead of pk12util -i. The p12tool utility supports all PKCS#12 encryption modes. If p12tool is unavailable, try pk12util -i or use --pkcs12-mode cbc or --pkcs12-mode legacy when creating the PKCS#12 file.
p12tool -i clnt/recovered.p12 -d test-import -w clnt/recover.pwdIssue: Multi-token setup fails with "token not found"
Solution: Verify HSM tokens are properly configured in NSS:
$ modutil -list -dbdir serv|
Tip
|
To find a page in the Wiki, enter the keywords in search field, press Enter, then click Wikis. |