hsmCompatVerify - dogtagpki/pki GitHub Wiki

HSM Compatibility Verification Tools

Overview

The hsmCompatVerify tools (hsmCompatVerifyClnt and hsmCompatVerifyServ) are standalone command-line utilities designed to verify whether an HSM (Hardware Security Module) or software-based PKCS#11 cryptographic token is compatible with Dogtag KRA (Key Recovery Authority) operations.

These tools test the essential PKCS#11 mechanisms required for KRA key archival and recovery workflows without requiring a full PKI installation.

Availability: Since PKI 11.10.

Purpose

Before deploying a KRA with an HSM, administrators can use these tools to verify that the HSM supports the required cryptographic operations:

  • Key Generation: RSA, EC, and post-quantum (ML-KEM) key pair generation

  • Key Wrapping/Unwrapping: RSA-OAEP, RSA PKCS#1 v1.5, AES-KWP, AES-CBC

  • Certificate Signing: Self-signed and CA-signed certificate creation

  • Session Key Operations: AES symmetric key generation and operations

The tools simulate the complete KRA workflow:

  1. Client-side: Generate user keys and wrap them for archival (using KRA transport certificate)

  2. Server-side archival: Unwrap keys with transport key, re-wrap with storage key

  3. Server-side recovery: Unwrap keys from storage and export to PKCS#12

Components

Tool Description

hsmCompatVerifyServ

Server-side operations (setup, archival, recovery)

hsmCompatVerifyClnt

Client-side operations (key generation and wrapping)

Supported Algorithms

Traditional Cryptography (Merged in Master)

  • User Keys: RSA (2048-4096 bits), EC (nistp256, nistp384, nistp521)

  • CA Keys: RSA (2048-4096 bits), EC (nistp256, nistp384, nistp521)

  • Transport/Storage Keys: RSA-2048 (required for key wrapping)

Post-Quantum Cryptography (In Development)

  • User Keys: ML-KEM-768

  • CA Keys: ML-DSA-65

  • Transport/Storage Keys: ML-KEM-768

See RSA/EC Key Archival Examples for usage instructions.

Important Notes and Disclaimers

Important

  • These tools are intended for pre-deployment testing and validation of HSM/PKCS#11 token compatibility.

  • While the tools exercise the essential PKCS#11 mechanisms used by Dogtag KRA, successful verification does not guarantee that all KRA features will work flawlessly with your specific HSM configuration.

  • These tools provide a best-effort verification of basic compatibility. Your HSM may have specific requirements, limitations, or configuration needs that are not covered by these tests.

  • Always perform comprehensive testing with your actual KRA deployment before production use.

  • Red Hat and the Dogtag PKI project do not provide warranties or guarantees about HSM compatibility based solely on these tool results.

  • For production deployments, consult your HSM vendor’s documentation and Dogtag PKI’s official HSM compatibility guidance.

Key Features

  • Standalone operation: No CA/KRA server installation required

  • Multiple test modes: Setup-only, archive-only, recover-only, or full workflow

  • LDIF export/import: Archive keys to LDIF format for testing storage workflows

  • Flexible key wrapping: Support for multiple algorithms (AES-KWP, AES-CBC, RSA-OAEP)

  • PKCS#12 export: Verify complete recovery workflow with PKCS#12 file creation

  • HSM token support: Direct testing with PKCS#11 HSM tokens

Use Cases

Pre-Deployment Validation

Verify HSM compatibility before purchasing or deploying hardware:

# Test with your HSM token
$ hsmCompatVerifyServ --setup-only \
    --hsm-token "YourHSM" \
    --hsm-token-passwd-file hsm.pwd \
    --verbose

Algorithm Compatibility Testing

Test specific key wrapping algorithms required by your deployment:

# Test AES-KWP (FIPS-compliant)
$ hsmCompatVerifyClnt --keywrap-alg "AES KeyWrap/Wrapped" --verbose

# Test RSA-OAEP (recommended)
$ hsmCompatVerifyClnt --rsa-keywrap RSA-OAEP --verbose

Development and Testing

Developers can use these tools to test KRA-related code changes without a full PKI setup.

Documentation

Getting Started

  1. Install the pki-tools or pki-hsm-compat-verify package:

    $ sudo dnf install pki-tools

  2. Follow the RSA/EC Key Archival Examples guide

  3. For HSM testing, ensure your HSM’s PKCS#11 library is properly configured with NSS

See Also

References

Tip
 To find a page in the Wiki, enter the keywords in search field, press Enter, then click Wikis.
⚠️ **GitHub.com Fallback** ⚠️