Crate kipuka_hsm 

PKCS#11 HSM abstraction with ML-DSA and ML-KEM support.

This crate provides a high-level interface to PKCS#11 Hardware Security Modules (HSMs) with full support for:

• Classical algorithms: RSA (2048/3072/4096), ECDSA (P-256/P-384/P-521)
• Post-quantum algorithms: ML-DSA (FIPS 204), ML-KEM (FIPS 203)
• Key wrapping: AES Key Wrap (RFC 3394), RSAES-OAEP
• NIAP CA PP compliance: FCS_CKM.1 key generation requirements

Supported Providers

• Entrust nShield
• Utimaco CryptoServer
• Kryoptic (software token)
• Thales Luna Cloud HSM (CSP)
• Thales Luna Tactical (TCT)

Post-Quantum Cryptography

PQC mechanisms (ML-DSA, ML-KEM) are vendor-specific until PKCS#11 v3.2 standardization. Each provider configuration includes vendor-specific mechanism IDs via PqcMechanismIds.

When HSM does not support PQC, the library can fall back to software implementations using synta-certificate.

Architecture

┌─────────────────────────────────────────────────────────┐
│                     Application Layer                    │
│                  (kipuka EST server)                     │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    kipuka-hsm crate                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  HsmKeyPair  │  │  HsmSigner   │  │   HsmSlot    │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│            │              │                  │           │
│            └──────────────┴──────────────────┘           │
│                           │                              │
│                  ┌────────▼────────┐                     │
│                  │ Pkcs11Context   │                     │
│                  └────────┬────────┘                     │
└───────────────────────────┼──────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                     cryptoki crate                       │
│              (Rust PKCS#11 bindings)                     │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│            Vendor PKCS#11 Library (.so/.dll)             │
│   (Entrust, Utimaco, Kryoptic, Thales CSP/TCT)          │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│              Hardware Security Module                    │
│           (Physical HSM or software token)               │
└─────────────────────────────────────────────────────────┘

Example Usage

use kipuka_hsm::{
    HsmSlot, HsmKeyPair, KeyAlgorithm, EcdsaCurve,
    Pkcs11Context, sign_ecdsa,
    providers::HsmProvider,
    key::PqcMechanismIds,
};

// Initialize PKCS#11 library
let provider = HsmProvider::Kryoptic;
let config = provider.config();
let context = Pkcs11Context::new(&config.library_path)?;

// Find HSM slot
let slot = HsmSlot::find_first_slot(&context)?;

// Generate ECDSA P-256 key pair
let pqc_mechanisms = PqcMechanismIds::default();
let key = HsmKeyPair::generate(
    &slot,
    KeyAlgorithm::Ecdsa(EcdsaCurve::P256),
    "my-signing-key",
    &[0x01, 0x02, 0x03], // CKA_ID
    &config,
    &pqc_mechanisms,
)?;

// Sign a message digest
let digest = [0u8; 32]; // SHA-256 digest
let signature = sign_ecdsa(&key, &digest)?;

ML-DSA Example

use kipuka_hsm::{
    HsmSlot, HsmKeyPair, KeyAlgorithm, MlDsaLevel,
    Pkcs11Context, sign_ml_dsa,
    providers::HsmProvider,
    key::PqcMechanismIds,
};

let provider = HsmProvider::Kryoptic;
let config = provider.config();
let context = Pkcs11Context::new(&config.library_path)?;
let slot = HsmSlot::find_first_slot(&context)?;

// Configure vendor-specific PQC mechanism IDs
let pqc_mechanisms = PqcMechanismIds {
    ml_dsa_keygen: Some(0x8000_0001),
    ml_dsa_65: Some(0x8000_0003),
    ..Default::default()
};

// Generate ML-DSA-65 key pair
let key = HsmKeyPair::generate(
    &slot,
    KeyAlgorithm::MlDsa(MlDsaLevel::L3),
    "ml-dsa-signing-key",
    &[0x04, 0x05, 0x06],
    &config,
    &pqc_mechanisms,
)?;

// Sign a message (ML-DSA hashes internally)
let message = b"Hello, post-quantum world!";
let signature = sign_ml_dsa(&key, message, MlDsaLevel::L3, &pqc_mechanisms)?;

Re-exports

pub use error::HsmError;

pub use error::HsmResult;

pub use key::EcdsaCurve;

pub use key::HsmKeyPair;

pub use key::KeyAlgorithm;

pub use key::MlDsaLevel;

pub use key::MlKemLevel;

pub use key::PqcMechanismIds;

pub use pkcs11::Pkcs11Context;

pub use providers::HsmProvider;

pub use sign::DefaultHsmSigner;

pub use sign::HsmSigner;

pub use sign::RsaHashAlgorithm;

pub use sign::SoftwarePqcFallback;

pub use sign::sign_ecdsa;

pub use sign::sign_ml_dsa;

pub use sign::sign_rsa_pkcs1;

pub use sign::sign_rsa_pss;

pub use slot::HsmSlot;

Modules

error

Error types for HSM operations.

key

HSM key pair generation and management with PQC support.

pkcs11

PKCS#11 library context management.

providers

HSM provider registry and vendor-specific configurations.

sign

HSM signing operations with PQC support.

slot

HSM slot and session management.

Structs

HsmContext

High-level HSM context wrapping PKCS#11 initialization and provider config.