API Reference

Craton HSM exposes two primary interfaces: a PKCS#11 C ABI (the standard way to consume it) and a Rust library API (for embedding directly in Rust programs).

PKCS#11 C ABI

The shared library (libcraton_hsm.so / craton_hsm.dll / libcraton_hsm.dylib) exports 70+ #[no_mangle] extern "C" functions conforming to PKCS#11 v3.0 (OASIS Standard).

Any PKCS#11-aware consumer (OpenSSL engines, Java SunPKCS11, Firefox NSS, pkcs11-tool, etc.) can load the library directly.

Loading the Library

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

# OpenSSL (via engine or provider)
export PKCS11_MODULE_PATH=/path/to/libcraton_hsm.so

# Python (PyKCS11)
import PyKCS11
lib = PyKCS11.PyKCS11Lib()
lib.load("/path/to/libcraton_hsm.so")

Exported Functions

Initialization

Slot and Token Management

Session Management

PIN Management

Object Management

Key Generation

Signing and Verification

Encryption and Decryption

Digesting

Key Wrapping

Key Derivation

Random Number Generation

Operation State

Supported Mechanisms

41 PKCS#11 mechanisms registered via C_GetMechanismList:

Rust Library API

When used as an rlib (Rust library), the public API is organized into these modules:

craton_hsm::core — Central State

use craton_hsm::core::HsmCore;
use craton_hsm::config::HsmConfig;

// Default configuration
let hsm = HsmCore::new_default();

// Custom configuration
let config = HsmConfig::load("craton_hsm.toml")?;
let hsm = HsmCore::new(config);

// Custom crypto backend
let hsm = HsmCore::new_with_backend(config, my_backend);

craton_hsm::config — Configuration

use craton_hsm::config::{HsmConfig, TokenConfig, SecurityConfig, AlgorithmConfig, AuditConfig};

let config = HsmConfig::default();
// Or load from file:
let config = HsmConfig::load("craton_hsm.toml")?;
// Or load with validation:
let config = HsmConfig::load_validated("craton_hsm.toml")?;

See Configuration Reference for all fields.

craton_hsm::error — Error Types

use craton_hsm::error::{HsmError, HsmResult};

HsmError maps 1:1 to PKCS#11 CK_RV return codes. See Troubleshooting for common errors.

craton_hsm::crypto — Cryptographic Operations

The CryptoBackend trait defines all cryptographic operations:

use craton_hsm::crypto::backend::CryptoBackend;

// Backend is selected at HsmCore creation time:
// - Default: RustCrypto (pure Rust)
// - Optional: aws-lc-rs (FIPS-validated, via craton_hsm-enterprise)

Sub-modules:

• crypto::keygen — key generation (RSA, EC, Ed25519, AES)
• crypto::sign — signing (RSA PKCS#1/PSS, ECDSA, EdDSA)
• crypto::encrypt — encryption (AES-GCM/CBC/CTR, RSA-OAEP)
• crypto::digest — hashing (SHA-1/2/3)
• crypto::derive — key derivation (ECDH shared secret, PKCS#11 EC KDFs, legacy HKDF-SHA256, derived-key template policy)
• crypto::wrap — key wrapping (AES-KW, RFC 3394)
• crypto::pqc — post-quantum (ML-KEM, ML-DSA, SLH-DSA)
• crypto::drbg — SP 800-90A HMAC_DRBG
• crypto::self_test — power-on self-tests
• crypto::pairwise_test — pairwise consistency tests

craton_hsm::store — Object Storage

use craton_hsm::store::object::StoredObject;
use craton_hsm::store::attributes::ObjectStore;
use craton_hsm::store::key_material::RawKeyMaterial;
use craton_hsm::store::encrypted_store::EncryptedStore;

craton_hsm::session — Session Management

use craton_hsm::session::manager::SessionManager;
use craton_hsm::session::session::{Session, SessionState};

craton_hsm::token — Token Management

use craton_hsm::token::token::Token;
use craton_hsm::token::slot::SlotManager;

craton_hsm::audit — Audit Logging

use craton_hsm::audit::log::{AuditLog, AuditOperation, AuditResult};

Generated Rustdoc

Full Rust API documentation with type signatures is available via:

cargo doc --open --no-deps

Or online at docs.rs/craton_hsm (after crates.io publication).