Craton HSM

Not FIPS 140-3 certified. This software has not undergone CMVP validation. See FIPS Gap Analysis for details.

A PKCS#11 v3.0-compliant Software Hardware Security Module (HSM) written in pure Rust.

Overview

Craton HSM provides a software-based implementation of the PKCS#11 Cryptographic Token Interface standard (v3.0). It exposes the standard C ABI so that any PKCS#11-aware application (OpenSSL engines, Java PKCS11 providers, Firefox NSS, etc.) can use it as a drop-in cryptographic backend.

Key Features

• Full PKCS#11 C ABI with 70+ exported functions
• Classical cryptography: RSA (2048/3072/4096) (private-key operations need the awslc-backend feature — see note below), ECDSA (P-256/P-384), EdDSA (Ed25519), AES-256 (GCM/CBC/CTR)
• Post-quantum cryptography: ML-KEM-768, ML-DSA-44/65/87, SLH-DSA-SHA2-128s, hybrid X25519+ML-KEM-768 (PQC crates are at RC versions — API may change before 1.0; see Known Issues)
• Multi-part operations: streaming sign/verify (SHA-256/384/512), streaming encrypt/decrypt (AES-CBC/CTR)
• SP 800-90A HMAC_DRBG with prediction resistance and continuous health tests — all key generation routes through DRBG
• FIPS 140-3 Power-On Self-Tests (POST): 17 self-tests (integrity check + 16 KATs) covering all approved algorithms
• SP 800-57 key lifecycle management: date-based activation/deactivation
• Memory hardening: mlock/VirtualLock for key material, ZeroizeOnDrop, constant-time PIN comparison
• Tamper-evident audit log with chained SHA-256 hashes
• Pluggable crypto backends: RustCrypto (default); FIPS-validated aws-lc-rs available via craton-hsm-enterprise
• Encrypted persistent storage: AES-256-GCM with PBKDF2-derived keys
• gRPC daemon with mutual TLS for remote HSM access
• Admin CLI for token management, PIN operations, and diagnostics

RSA private-key operations require the awslc-backend feature. Release builds of the default RustCrypto backend refuse RSA signing, decryption, and key-pair generation with CKR_MECHANISM_INVALID, because the rsa crate is subject to the Marvin timing attack (RUSTSEC-2023-0071) — a threat model that applies directly to an HSM performing private-key operations for remote callers. RSA signature verification and every other algorithm are unaffected. Build with --no-default-features --features awslc-backend to use RSA. See docs/troubleshooting.md.

Quick Start

Build

# Default build (RustCrypto backend)
cargo build --release

Test

# Run all tests (must use single thread due to global PKCS#11 state)
cargo test -- --test-threads=1

Use as a PKCS#11 Library

Build the cdylib and point your application to it:

cargo build --release
# Output: target/release/craton_hsm.dll (Windows) / libcraton_hsm.so (Linux) / libcraton_hsm.dylib (macOS)

Configure your PKCS#11 consumer to load the library:

# OpenSSL example
export PKCS11_MODULE_PATH=/path/to/libcraton_hsm.so

# pkcs11-tool
pkcs11-tool --module /path/to/libcraton_hsm.so --list-slots

Architecture

craton_hsm/
  src/
    core.rs           - HsmCore: central state shared by all interfaces
    pkcs11_abi/        - C ABI layer (types, constants, 70+ function exports)
    session/           - Session management (DashMap-based concurrent sessions)
    token/             - Token/slot management, PIN lifecycle
    store/             - Object storage, encrypted persistence, key material
    crypto/            - Cryptographic operations, backends, DRBG, self-tests
    audit/             - Tamper-evident append-only audit log
    error.rs           - HsmError -> CK_RV mapping
  craton-hsm-daemon/      - gRPC server with mutual TLS
  tools/
    craton-hsm-admin/     - Admin CLI (clap)
    pkcs11-spy/        - PKCS#11 spy/logging wrapper
  deploy/              - Dockerfile + Helm chart
  docs/                - Architecture, security model, operator runbook
  tests/               - Integration test suites
  benches/             - Criterion benchmarks

Crypto Backend Selection

Craton HSM supports pluggable crypto backends via the CryptoBackend trait:

Use HsmCore::new_with_backend() to inject an external backend.

Security Model

• Memory protection: Key material is mlock'd to prevent swapping; zeroed on drop
• PIN security: PBKDF2-SHA256 (600k iterations) with constant-time comparison
• Self-tests: 17 POST self-tests (integrity + 16 KATs including RSA) run before any cryptographic service is available
• Audit trail: Every operation is logged with chained SHA-256 integrity hashes
• Session isolation: Per-session state with DashMap for safe concurrent access
• Key lifecycle: SP 800-57 states (pre-activation, active, deactivated, compromised)

FIPS 140-3 Status

The FIPS-validated aws-lc-rs backend is available in craton-hsm-enterprise (craton-hsm-awslc crate). See docs/fips-gap-analysis.md for a detailed assessment of remaining gaps for a full FIPS 140-3 Level 1 certification.

Documentation

• Documentation Index — full documentation table of contents
• Installation Guide — build, test, deploy, configure
• API Reference — PKCS#11 C ABI functions and Rust library API
• Examples — usage with pkcs11-tool, OpenSSL, Python, Java
• Configuration Reference — all craton_hsm.toml fields, defaults, and examples
• Persistent Storage — enabling encrypted persistence, backup/restore, file locking, security properties
• Architecture Overview — module diagram, source layout, data flow
• Security Model — threat model, key protection, access control
• Troubleshooting — common errors, build issues, runtime problems
• FAQ — frequently asked questions
• Migration Guide — version upgrade instructions
• FIPS Gap Analysis — certification readiness assessment
• Operator Runbook — day-to-day operations
• Tested Platforms — platform support matrix, CI pipeline
• Changelog — version history
• Roadmap — completed phases and future directions
• Governance — decision-making, roles, contribution process

Disclaimer

Craton HSM is NOT FIPS 140-3 certified. While the codebase implements FIPS 140-3 Level 1 technical requirements (POST KATs, pairwise consistency tests, approved mode, etc.), it has not undergone CMVP validation. Use at your own risk. See docs/fips-gap-analysis.md for details.

License

Copyright 2026 Craton Software Company Licensed under the Apache License, Version 2.0.

Related Repositories