Craton HSM

Architecture Overview

Architecture Overview

Craton HSM is a pure-Rust software Hardware Security Module that implements the PKCS#11 v3.0 Cryptographic Token Interface. The codebase is organised as a single craton_hsm core library with thin consumer-facing surfaces layered on top: a C ABI shared library, a gRPC daemon, and an admin CLI. All three surfaces share the same in-process state.

Layered View

+--------------------------------------------------------------+
| Consumer applications                                        |
| (OpenSSL engine, Java SunPKCS11, NSS, pkcs11-tool, ssh-agent)|
+----------+-------------------+---------------------+---------+
           |                   |                     |
    dlopen / C ABI         gRPC / mTLS          local invocation
           |                   |                     |
           v                   v                     v
+------------------+  +-----------------+  +----------------------+
|  pkcs11_abi/     |  |  cratond        |  |  craton-hsm-admin    |
|  70+ C exports   |  |  (tonic + TLS)  |  |  (clap)              |
|  libcraton_hsm.* |  |                 |  |                      |
+---------+--------+  +--------+--------+  +----------+-----------+
          |                    |                      |
          +--------------------+----------------------+
                               |
                               v
                   +-----------------------+
                   |       HsmCore         |  src/core.rs
                   |                       |
                   |  SlotManager          |
                   |  SessionManager       |
                   |  ObjectStore          |
                   |  AuditLog             |
                   |  CryptoBackend (Arc)  |
                   |  HmacDrbg (Mutex)     |
                   |  AlgorithmConfig      |
                   +-----------+-----------+
                               |
     +------------+------------+-----------+-----------+----------+
     |            |            |           |           |          |
     v            v            v           v           v          v
 +--------+  +--------+  +---------+  +---------+  +--------+ +---------+
 |session/|  | token/ |  | store/  |  | crypto/ |  | audit/ | |self-    |
 |        |  |        |  |         |  |         |  |        | |tests    |
 |states, |  |PIN,    |  |objects, |  |backends,|  |append- | |FIPS POST|
 |DashMap |  |lockout |  |encrypted|  |DRBG,    |  |only,   | |17 KATs  |
 |        |  |        |  |redb,    |  |mech-    |  |chained | |         |
 |        |  |        |  |backup   |  |anisms   |  |SHA-256 | |         |
 +--------+  +--------+  +---------+  +---------+  +--------+ +---------+

The HsmCore Singleton

HsmCore (src/core.rs) is the central state container. Every consumer surface -- the C ABI, the gRPC daemon, and the admin CLI -- dispatches into the same type. A single process contains one live HsmCore at a time.

For the PKCS#11 shared-library path, HsmCore is held in a Mutex<Option<Arc<HsmCore>>> that is populated by C_Initialize and cleared by C_Finalize. The daemon and admin CLI instead construct an HsmCore directly and retain it via Arc for the lifetime of the process.

HsmCore owns, by composition:

  • a SlotManager and SessionManager for PKCS#11 slot/session state,
  • an ObjectStore for PKCS#11 objects and their attributes,
  • an Arc<AuditLog> for tamper-evident event logging,
  • an Arc<dyn CryptoBackend> that dispatches to the chosen crypto implementation (RustCrypto by default; aws-lc-rs when the enterprise FIPS backend is linked in),
  • an HmacDrbg (SP 800-90A HMAC-SHA256) guarded by a mutex,
  • an AlgorithmConfig capturing the approved-mode policy.

Session, Token, and Object Model

Craton HSM follows the PKCS#11 v3.0 data model unchanged:

  • A slot represents a logical reader; a slot contains at most one token. Craton's default deployment exposes a single slot, but the SlotManager supports multiple slots keyed by CK_SLOT_ID.
  • A token holds the label, serial, PIN hashes, and login state. PINs are stored as PBKDF2-HMAC-SHA256 digests (600,000 iterations) with a random per-token salt and compared in constant time.
  • Sessions are the unit of concurrent access. Each session has a read-only or read-write flavour and tracks a login state (Public, User, or SO). Sessions are stored in a DashMap<CK_SESSION_HANDLE, Session> for lock-free concurrent lookup.
  • Objects (keys, certificates, data) live in the ObjectStore and follow the PKCS#11 attribute model. Storage-resident token objects (CKA_TOKEN = true) are persisted through the encrypted store when persistence is enabled; session objects are held in memory only.

See Components for a per-module breakdown and Security Model for the PIN and key-lifecycle rules.

Storage

The default object store is a DashMap of Arc<RwLock<StoredObject>>. When persistence is configured, an EncryptedStore backed by redb serialises token objects and encrypts each record with AES-256-GCM under a key derived from the user PIN via PBKDF2-HMAC-SHA256 (1,000,000 iterations). A per-file exclusive lock prevents two processes from opening the same database.

See Storage for the on-disk layout and encryption details.

Random Number Generation

All cryptographic randomness flows through a single SP 800-90A HMAC_DRBG instance (HMAC-SHA256) seeded from the operating-system CSPRNG. The DRBG enforces prediction resistance by pulling fresh entropy on every generate call and runs continuous health tests per SP 800-90B. Key generation, AES-GCM nonces, and backup nonces are all routed through this DRBG -- no cryptographic operation inside HsmCore reads OsRng directly for key material.

Audit Log

The AuditLog records every security-relevant operation as an append-only entry. Each entry carries a previous_hash field that chains the log with H_n = SHA-256(H_{n-1} || serialize(payload_n)) where payload_n excludes the previous_hash itself. Modifying, deleting, or reordering any entry breaks the chain. Writes are synchronous: the corresponding PKCS#11 function does not return until the audit record is durable.

Self-Tests

On C_Initialize (and on daemon startup), the module runs FIPS 140-3 Power-On Self-Tests: a software-integrity HMAC-SHA256 check over the module binary plus 16 algorithm Known-Answer Tests covering SHA-2/SHA-3, HMAC, AES-GCM/CBC/CTR, RSA, ECDSA, ML-DSA, ML-KEM, RNG health, and the DRBG itself. If any test fails the module latches a global POST_FAILED flag and all subsequent PKCS#11 calls return CKR_GENERAL_ERROR until the module is re-initialised.

The gRPC Daemon

cratond wraps HsmCore in a tonic-based gRPC server that exposes the same operations over the network. The daemon enforces mutual TLS (TLS 1.3 minimum, optional client-certificate CA and CRL), per-connection concurrency limits, per-request timeouts, and an in-memory login-attempt throttle. Running without TLS is refused unless allow_insecure is set and the bind address is a loopback IP.

See gRPC Daemon for the protocol surface and configuration entry points.

Extension Points

The CryptoBackend trait is the primary extension point. The core crate ships the pure-Rust RustCryptoBackend; the separate enterprise distribution adds AwsLcBackend (FIPS-validated aws-lc-rs), OpenSSL, Windows CNG, PKCS#11 passthrough, and hardware backends (NXP HSE, Infineon TPM). Backends are selected at C_Initialize via algorithms.crypto_backend in craton_hsm.toml, or injected directly via HsmCore::new_with_backend().