Frequently Asked Questions

General

Is Craton HSM FIPS 140-3 certified?

No. Craton HSM implements the Level 1 technical requirements — power-on self-tests (POST), an approved-only mode, an SP 800-90A HMAC_DRBG, pairwise consistency tests, module integrity checks, and zeroization — but has not been submitted to a CMVP-accredited laboratory. There is no certificate number and the module does not appear on the CMVP public register.

Submission of the Enterprise aws-lc-rs backend is the Phase E2 roadmap item; see ../project/roadmap and ../fips/overview.

What is the difference between Core and Enterprise?

Core is the open-source PKCS#11 v3.0 module licensed under Apache-2.0. It includes the full cryptographic surface, the gRPC daemon, the admin CLI, and the FIPS design envelope. Enterprise is a separate workspace of source-available crates licensed under Business Source License 1.1 that adds integrations an HSM product typically needs once it leaves a single host: authentication providers (LDAP, OIDC, X.509, TOTP), HSM clustering with Raft, KMIP, cloud CSI shims, Windows CNG, and hardware backends (NXP HSE, Infineon TPM). See ../project/license for the legal detail and compatibility-matrix for which crate covers which integration.

Can I run Craton HSM in production?

Yes, with the usual caveats for a software HSM:

• It is a software module (FIPS 140 Level 1 design target). It does not provide physical tamper resistance; that is Level 2 and up.
• The post-quantum dependencies are at release-candidate versions (see the PQC question below).
• No third-party security audit has been published yet.

If your requirements exceed what Level 1 covers, use craton-hsm-pkcs11 to front a validated hardware HSM and let Craton handle the higher-level API, clustering, audit, and KMIP surface.

How does Craton HSM compare to SoftHSMv2?

Comparative benchmarks against SoftHSMv2 ship with the Core repository (SOFTHSM2_LIB env var drives the Criterion suite).

How does it compare to YubiHSM, Thales Luna, and other hardware HSMs?

Craton HSM is a software module, so the comparison is not apples-to-apples. The common deployment pattern is to use craton-hsm-pkcs11 to front a hardware HSM: the hardware device holds keys and performs operations, while Craton provides the higher-level API surface, clustering, audit log, and KMIP server. Supported vendor libraries are listed in compatibility-matrix and include YubiHSM2, Thales Luna, Utimaco CryptoServer, nCipher nShield, and AWS CloudHSM.

Does it support cloud KMS?

The craton-hsm-cloud Enterprise crate provides KMS-compatible shims for AWS KMS, Azure Key Vault, and HashiCorp Vault (KV v2 and Transit). These are reference implementations; production validation is on the roadmap. A Kubernetes CSI driver is included and is the most mature integration in the crate. Mock implementations are gated behind mock-insecure-do-not-ship and CRATON_HSM_ALLOW_MOCK=1 — they are not for production.

What PKCS#11 version does Craton HSM implement?

PKCS#11 v3.0 (OASIS Standard). The library exports 70+ functions covering initialization, session management, object management, key generation, sign/verify, encrypt/decrypt, digest, key wrapping, key derivation, and random number generation. PKCS#11 v3.1 tracking is a long-term roadmap item.

Cryptography

What algorithms are supported?

Classical:

• RSA 2048 / 3072 / 4096 (PKCS#1 v1.5, PSS, OAEP)
• ECDSA on P-256 and P-384
• EdDSA on Ed25519
• AES 128 / 192 / 256 (GCM, CBC, CTR, Key Wrap per RFC 3394)
• SHA-1, SHA-256 / 384 / 512, SHA3-256 / 384 / 512
• HMAC-SHA-256 / 384 / 512
• ECDH key derivation on P-256, P-384 with HKDF-SHA256 per SP 800-56C

Post-quantum (NIST FIPS standards, RustCrypto RC crate versions):

• ML-KEM 512 / 768 / 1024 (FIPS 203)
• ML-DSA 44 / 65 / 87 (FIPS 204)
• SLH-DSA SHA2-128s / SHA2-256s (FIPS 205)

A hybrid X25519 + ML-KEM-768 key exchange is also provided for transitional deployments.

Is the PQC support stable?

Not yet. The backing crates (ml-kem 0.3.0-rc.0, ml-dsa 0.1.0-rc.7, slh-dsa 0.2.0-rc.4 as of 0.9.1) are release candidates. Their APIs and key serialization formats may change before 1.0. Keys generated with RC versions should be treated as non-portable across major version bumps. Upgrade to stable crates is a near-term roadmap item — see ../project/roadmap.

Why is SHA-1 available but restricted?

SHA-1 is available for C_Digest and for verifying existing signatures via C_Verify. It is blocked for new signatures by default and is fully blocked in FIPS approved mode. The allow_sha1_signing flag in the [algorithms] config section controls the non-FIPS behaviour; in FIPS mode the flag is ignored because FIPS defaults are hardcoded.

How is randomness generated?

All randomness goes through an SP 800-90A HMAC-SHA256 DRBG with prediction resistance (reseed from OS entropy on every generate), a continuous health test per SP 800-90B (rejects identical consecutive outputs), and a monotonic reseed counter capped at 2^48. Key generation never calls OsRng directly — a prior 0.9.1 critical fix closed exactly that gap.

How is key material protected?

• In memory: wrapped in RawKeyMaterial (Vec<u8> + mlock / VirtualLock), zeroed on drop via ZeroizeOnDrop.
• At rest: AES-256-GCM with PBKDF2-derived keys (600 000 iterations by default, configurable above a compile-time floor).
• In logs: never printed — Debug impls return [REDACTED].
• In backups: encrypted with a PIN-derived key (PBKDF2 + AES-256-GCM).

What happens after too many failed PINs?

Exponential backoff starts at 100 ms and doubles per failure, capped at 5 s. After max_failed_logins failures (default 10) the account is locked and the SO must re-initialize the token with C_InitToken.

Does Craton HSM defend against side-channel attacks?

At the software layer:

• Constant-time PIN comparison via subtle::ConstantTimeEq.
• Constant-time template matching using bitwise accumulators (no early returns).
• No secret-dependent branching in the HSM logic layer.

The underlying libraries (RustCrypto, aws-lc-rs) have their own side-channel properties; aws-lc-rs is the relevant backend for FIPS claims. See ../security for the full threat model.

Operations

Can multiple processes use Craton HSM simultaneously?

Not directly — the persistent store uses exclusive file locking. For multi-process access, use the gRPC daemon (craton-hsm-daemon) which serializes access through a single HsmCore instance and authenticates callers with mutual TLS. On Unix, the library detects fork() via PID comparison and forces child processes to re-initialize.

How is storage encrypted?

The persistent object store uses redb with AES-256-GCM envelope encryption. The wrap key is derived from the token password via PBKDF2 (600 000 iterations default). Each write is authenticated. The audit log is a separate append-only file chained with SHA-256. See ../architecture for the full data model.

How do I back up token data?

craton-hsm-admin backup --pin <SO_PIN> --output backup.enc
craton-hsm-admin restore --pin <SO_PIN> --input backup.enc

Backups are encrypted with a PIN-derived key (PBKDF2 + AES-256-GCM). They are portable across hosts running the same Core version.

Does it support OCSP or HTTP CRL distribution points?

No, not in 0.1.x. The Enterprise craton-hsm-auth crate supports only static (pre-loaded) DER-encoded CRLs. Operators must refresh CRL data out-of-band (cron, config-management, sidecar) and reload the auth service. Expired CRLs and CRLs with unverifiable signatures are rejected — the fail-closed behaviour is deliberate.

Can I use it with OpenSSL 1.1?

The craton-hsm-openssl crate will build against system OpenSSL 1.1.1, but that configuration is Best-effort only because the OpenSSL project has ended support for 1.1.1. Production deployments should target OpenSSL 3.0 or 3.2. The PKCS#11 module itself is library-agnostic at the libpkcs11.so boundary and works with any PKCS#11 v3.0 consumer, so OpenSSL 1.1 consumers via the pkcs11 engine continue to work.

Does it work with Java JDK 21?

Yes. The Core CI runs the tests/interop/java_sunpkcs11.sh script against JDK 17 and JDK 21. keytool, PKCS11KeyStore, and the SunPKCS11 provider all operate against the Craton module without special configuration beyond a SunPKCS11 config file pointing at libcraton_hsm.so.

Can I run it in a container?

Yes. A multi-stage Dockerfile is at deploy/Dockerfile (rust:1.83-slim for build, gcr.io/distroless/cc-debian12 for runtime — no shell, no package manager). A Helm chart is at deploy/helm/craton_hsm/. The Enterprise DEPLOYMENT.md adds systemd unit files and a Kubernetes StatefulSet pattern.

Why must tests run single-threaded?

PKCS#11 defines a single global state per process (C_Initialize / C_Finalize). Running tests in parallel causes races on the global OnceLock<Arc<HsmCore>>. Always use cargo test -- --test-threads=1. An evaluation of cargo-nextest for per-process test isolation — which would remove this requirement — is a near-term roadmap item.

Development

How do I add a new crypto mechanism?

1. Add the mechanism constant in src/pkcs11_abi/constants.rs.
2. Register it in src/crypto/mechanisms.rs (validation plus FIPS policy).
3. Implement the operation in the relevant src/crypto/ module.
4. Add the CryptoBackend trait method in src/crypto/backend.rs.
5. Implement both backends (rustcrypto_backend.rs, awslc_backend.rs).
6. Wire the C ABI in src/pkcs11_abi/functions.rs.
7. Add integration tests and update C_GetMechanismList and C_GetMechanismInfo.

How do I run the fuzz targets?

cargo install cargo-fuzz
cargo +nightly fuzz run fuzz_buffer_overflow
cargo +nightly fuzz run fuzz_c_abi -- -max_total_time=300

Current targets cover the ABI boundary, session-state-machine transitions, and buffer-overflow paths. Priorities for new targets are recorded in docs/security-review-checklist.md.

How do I contribute?

See ../project/contributing. The project uses a Contributor License Agreement (CLA), signed automatically via the CLA Assistant bot on your first pull request.