Craton HSM FIPS 140-3 Security Policy and Certification Document

DISCLAIMER: Craton HSM is NOT FIPS 140-3 certified. This document describes the technical implementation of FIPS 140-3 Level 1 requirements. It has not been reviewed or validated by a CMVP-accredited laboratory. Do not rely on this software for FIPS compliance without independent certification.

---

Document Information

Revision History

---

Acronyms and Abbreviations

---

Normative References

---

1. Cryptographic Module Specification

1.1 Module Identification

1.2 Security Level Claim

1.3 Module Description

Craton HSM is a PKCS#11 v3.0-compliant software cryptographic module implemented entirely in the Rust programming language. The module provides cryptographic key management, digital signature, encryption, hashing, key derivation, and key wrapping services through the industry-standard PKCS#11 C API.

The module is compiled as a dynamically loadable shared library (cdylib) that applications load at runtime via dlopen (Unix) or LoadLibrary (Windows). All cryptographic operations, key storage, authentication, and self-tests are contained within the single shared library binary.

The module supports 41 cryptographic mechanisms including post-quantum algorithms (ML-DSA, ML-KEM, SLH-DSA) and offers dual cryptographic backends: RustCrypto (default, pure Rust) and aws-lc-rs (optional, FIPS 140-3 validated).

1.4 Module Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    CRYPTOGRAPHIC MODULE BOUNDARY                 │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              PKCS#11 C ABI Layer (68+ functions)          │   │
│  │              src/pkcs11_abi/functions.rs                   │   │
│  │       Input validation, catch_unwind, CK_RV mapping       │   │
│  └────────┬──────────┬──────────┬──────────┬────────────────┘   │
│           │          │          │          │                     │
│  ┌────────▼──┐ ┌─────▼─────┐ ┌─▼────────┐ ┌▼──────────────┐   │
│  │ SessionMgr│ │ ObjectStore│ │ AuditLog │ │  CryptoBackend│   │
│  │ DashMap   │ │ DashMap +  │ │ chained  │ │  trait (26    │   │
│  │ sessions  │ │ redb+AES  │ │ SHA-256   │ │  methods)     │   │
│  └───────────┘ └───────────┘ └──────────┘ └──────┬────────┘   │
│                      │                            │             │
│              ┌───────▼───────┐          ┌─────────▼─────────┐  │
│              │ RawKeyMaterial│          │  RustCryptoBackend │  │
│              │ mlock+zeroize │          │  --- OR ---        │  │
│              └───────────────┘          │  AwsLcBackend      │  │
│                                         │  (FIPS validated)  │  │
│  ┌──────────────────┐                  └────────────────────┘  │
│  │  HMAC_DRBG       │  ┌──────────────────┐                    │
│  │  SP 800-90A      │  │  POST/KAT Engine │                    │
│  │  (prediction     │  │  15 KATs +       │                    │
│  │   resistance)    │  │  integrity test   │                    │
│  └──────────────────┘  └──────────────────┘                    │
│                                                                  │
│                         HsmCore (src/core.rs)                   │
│                    OnceLock<Arc<HsmCore>> singleton              │
└─────────────────────────────────────────────────────────────────┘

1.5 Module Boundary

Components inside the cryptographic boundary:

Components outside the cryptographic boundary:

1.6 Modes of Operation

The module operates in one of two modes:

FIPS Approved Mode (configuration: fips_approved_only = true, crypto_backend = "awslc"):

• Only FIPS-approved algorithms are available
• Non-approved mechanisms return CKR_MECHANISM_INVALID
• PQC mechanisms are blocked
• Ed25519 is blocked
• SHA-1 for signing is blocked
• All operations are performed through the FIPS-validated aws-lc-rs backend
• Source: src/crypto/mechanisms.rs:165 (is_fips_approved())

Non-Approved Mode (default configuration):

• All 41 mechanisms are available including PQC and Ed25519
• Algorithm indicator (IG 2.4.C) marks each operation as approved or non-approved
• Uses the RustCrypto backend (not FIPS-validated)

---

2. Cryptographic Module Interfaces

2.1 Logical Interface Mapping

Per FIPS 140-3 §7.2, all module interfaces are mapped to the four logical interface types:

2.2 Exported API Functions

The module exports the following 68 C functions through C_GetFunctionList. All functions are #[no_mangle] pub extern "C" with catch_unwind to prevent panic propagation across the FFI boundary.

Source: src/pkcs11_abi/functions.rs

General-Purpose Functions:

Slot and Token Management:

Session Management:

Object Management:

Encryption/Decryption:

Signing/Verification:

Message Digest:

Key Management:

Random Number Generation:

Not Implemented (return CKR_FUNCTION_NOT_SUPPORTED):

C_GetOperationState, C_SetOperationState, C_SignRecoverInit, C_SignRecover, C_VerifyRecoverInit, C_VerifyRecover, C_DigestEncryptUpdate, C_DecryptDigestUpdate, C_SignEncryptUpdate, C_DecryptVerifyUpdate, C_GetFunctionStatus, C_CancelFunction, C_WaitForSlotEvent

2.3 Interface Separation

The module maintains strict separation between interface types:

• Control inputs (PINs, mechanism selections) are never emitted as data outputs
• Status outputs (CK_RV codes) do not leak internal state — error codes are generic per PKCS#11 specification
• Data outputs (ciphertext, signatures, digests) flow only through designated output parameters
• The error mapping at src/error.rs:104-157 converts internal HsmError variants to standardized CK_RV codes, preventing information leakage through error specificity

---

3. Roles, Services, and Authentication

3.1 Roles

The module implements three roles per the PKCS#11 specification:

Source: src/session/session.rs:7-13 (SessionState enum), src/token/token.rs (login handling)

3.2 Services-to-Roles Mapping

The following table maps all module services to the roles authorized to access them, the CSPs accessed, and the FIPS approval status.

Token Management Services:

Symmetric Key Generation (Approved):

Asymmetric Key Pair Generation:

Digital Signature Services:

All signing services require User authentication. Corresponding verify services use public key components and also require User authentication.

Encryption/Decryption Services:

All encryption/decryption services require User authentication.

Key Wrapping/Unwrapping Services:

Key Derivation Services:

Digest Services (No CSP access):

Digest services are available to all roles including unauthenticated.

Random Number Generation:

Available to User and unauthenticated roles.

Object Management Services:

3.3 Authentication Mechanism

Algorithm: PBKDF2-HMAC-SHA256 (SP 800-132)

Comparison: Constant-time via subtle::ConstantTimeEq to prevent timing side-channel attacks.

Brute-Force Protection:

Source: src/token/token.rs (login state, failed attempt counters)

3.4 Authentication Strength

With a minimum 4-character PIN (assuming alphanumeric, 62 possible characters):

• PIN space: 62^4 = 14,776,336 possible PINs
• PBKDF2 cost: 600,000 iterations per guess
• Online brute-force cost: 14,776,336 × 600,000 = ~8.9 × 10^12 HMAC-SHA256 operations
• Online defense: 10-attempt lockout makes online brute-force infeasible

With the recommended 8-character PIN:

• PIN space: 62^8 = 2.18 × 10^14 possible PINs

---

4. Software/Firmware Security

4.1 Approved Integrity Technique

The module implements a software integrity test per FIPS 140-3 §9.4 using HMAC-SHA256.

Implementation: src/crypto/integrity.rs

Module Path Discovery:

• Unix: dladdr() on function pointer address (integrity.rs:141-156)
• Windows: GetModuleHandleExW() + GetModuleFileNameW() (integrity.rs:159-197)

Behavior Matrix:

Integrity Tool: tools/compute-integrity-hmac.sh and .ps1 compute the .hmac sidecar file from the compiled binary for production deployment.

4.2 Executable Code Integrity

• The module contains no dynamically loaded code at runtime
• No self-modifying code is present
• All cryptographic functions are statically compiled into the shared library
• The crate-type = ["cdylib", "rlib"] configuration (Cargo.toml:12) produces a single artifact

---

5. Operational Environment

5.1 Operating Environment Type

The module operates in a modifiable operational environment (general-purpose operating system). Per FIPS 140-3, a single operator is assumed per instantiation of the module.

5.2 Tested Platforms

5.3 Platform-Specific Security Features

5.4 Build Requirements for FIPS Mode

---

6. Physical Security

Not applicable. Craton HSM is a software cryptographic module. The cryptographic boundary is the process address space of the running application. FIPS 140-3 Level 1 does not impose physical security requirements on software modules.

---

7. Non-Invasive Security

Not applicable. FIPS 140-3 Level 1 does not require non-invasive security mechanisms.

---

8. Sensitive Security Parameter Management

8.1 CSP Inventory

The following table enumerates all Critical Security Parameters (CSPs) managed by the module:

Source: CSPs #1-11 stored in src/store/key_material.rs:10 (RawKeyMaterial); #12-13 in src/token/token.rs; #15-17 in src/crypto/drbg.rs:33-44; #19-20 in src/session/session.rs:39-71

8.2 CSP Generation

All cryptographic keys are generated using the module's HMAC_DRBG (SP 800-90A Rev.1):

PIN hashes are generated using PBKDF2-HMAC-SHA256 with 600,000 iterations and a 32-byte random salt.

8.3 CSP Entry and Establishment

PIN values are transmitted as plaintext over the PKCS#11 API and immediately hashed via PBKDF2. The plaintext PIN is not stored.

8.4 CSP Output

The following CSPs are never output through any API:

• PIN hashes (#12-13)
• Storage encryption key (#14)
• DRBG internal state (#15-17)
• Integrity HMAC key (#18)
• Intermediate plaintext (#19-20)

8.5 CSP Storage

In-Memory Storage:

All key material is stored in RawKeyMaterial (src/store/key_material.rs:10), which provides:

1. Memory locking on allocation: mlock() (Unix) or VirtualLock() (Windows) prevents the OS from paging key material to swap/disk. Source: key_material.rs:14-18
2. Zeroization on deallocation: self.0.zeroize() overwrites all bytes with 0x00 before munlock(). Source: key_material.rs:42-50
3. Debug redaction: Custom Debug impl displays [REDACTED] instead of key bytes. Source: key_material.rs:54-61
4. Clone re-locking: Cloned key material is independently mlock'd. Source: key_material.rs:35-39

Persistent Storage (Optional):

When configured with storage_path, objects are persisted using:

• Database: redb (embedded key-value store)
• Encryption: Per-object AES-256-GCM encryption
• Key derivation: Storage key derived from SO PIN via PBKDF2
• File locking: fs2::FileExt::try_lock_exclusive() prevents concurrent access
• Source: src/store/encrypted_store.rs

8.6 CSP Zeroization

All CSPs are zeroized when no longer needed. The zeroization lifecycle for key material:

RawKeyMaterial::new(data)
    │
    ├── mlock_buffer(ptr, len)          ← Lock pages in physical memory
    │
    ▼
[Active use: sign, encrypt, wrap, etc.]
    │
    ▼
RawKeyMaterial::drop()
    │
    ├── self.0.zeroize()                ← Overwrite all bytes with 0x00
    │
    ├── munlock_buffer(ptr, len)        ← Unlock (now-zeroed) pages
    │
    └── Vec<u8> deallocated             ← Rust allocator frees memory

Source: src/store/key_material.rs:42-50

Zeroization for other CSP types:

Zeroization Verification: 7 tests in tests/zeroization.rs verify that key material is cleared after drop (run in debug mode, require --ignored flag).

8.7 Key Lifecycle (SP 800-57)

The module implements SP 800-57 key lifecycle states with date-based transitions:

Source: src/store/object.rs (KeyLifecycleState enum, effective_lifecycle_state())

State Transition Diagram:

                    ┌───────────────┐
     Key Created →  │ Pre-Activation│
                    └──────┬────────┘
                           │ CKA_START_DATE reached
                    ┌──────▼────────┐
                    │    Active     │
                    └──┬─────┬──┬──┘
     CKA_END_DATE     │     │  │ Manual compromise
        passed         │     │  │
                ┌──────▼──┐  │  ┌▼───────────┐
                │Deactivated│  │  │ Compromised│
                └──────┬──┘  │  └─────┬──────┘
                       │     │        │
           C_DestroyObject   │  C_DestroyObject
                       │     │        │
                    ┌──▼─────▼────────▼──┐
                    │     Destroyed       │
                    └────────────────────┘

---

9. Self-Tests

9.1 Power-On Self-Tests (POST)

POST runs automatically during C_Initialize before any cryptographic service is available. All tests must pass; failure of any test sets POST_FAILED: AtomicBool (src/pkcs11_abi/functions.rs:62) and all subsequent operations return CKR_GENERAL_ERROR.

Source: src/crypto/self_test.rs:19-57 (run_post())

9.1.1 Software Integrity Test (§9.4)

See Section 4.1 for full details.

9.1.2 Known Answer Tests

9.1.3 RNG Health Tests

9.2 Conditional Self-Tests (§9.6)

9.2.1 Pairwise Consistency Tests

Executed immediately after every asymmetric key pair generation. Source: src/crypto/pairwise_test.rs

Test data: b"FIPS 140-3 pairwise consistency test" (pairwise_test.rs:13)

9.2.2 Continuous Random Number Tests

9.3 POST Failure Behavior

When any POST or conditional test fails:

1. POST_FAILED (AtomicBool) is set to true (functions.rs:62)
2. The get_hsm() function checks this flag on every subsequent PKCS#11 call (functions.rs:83)
3. All operations return CKR_GENERAL_ERROR (0x00000005)
4. The module cannot recover without process restart
5. No cryptographic services are available in the error state

---

10. Life-Cycle Assurance

10.1 Configuration Management

10.2 Module Design

Central Coordinator: HsmCore (src/core.rs:18-29)

pub struct HsmCore {
    pub slot_manager: SlotManager,
    pub session_manager: SessionManager,
    pub object_store: ObjectStore,
    pub audit_log: AuditLog,
    pub crypto_backend: Arc<dyn CryptoBackend>,
    pub drbg: parking_lot::Mutex<HmacDrbg>,
    pub algorithm_config: AlgorithmConfig,
}

Backend Abstraction: CryptoBackend trait (src/crypto/backend.rs) defines 26 methods covering all cryptographic operations. Two implementations:

1. RustCryptoBackend (src/crypto/rustcrypto_backend.rs) — default, pure Rust
2. AwsLcBackend (src/crypto/awslc_backend.rs) — optional, FIPS 140-3 validated

Backend selection is configuration-driven (algorithms.crypto_backend in craton_hsm.toml) and resolved at C_Initialize time.

10.3 Finite State Model

Module-Level States

┌──────────┐    C_Initialize     ┌──────────────┐
│ Power Off├────────────────────►│ POST Running │
└──────────┘                     └──────┬───────┘
                                        │
                        ┌───────────────┼───────────────┐
                        │ All tests pass│               │ Any test fails
                        ▼               │               ▼
                ┌───────────────┐       │       ┌──────────────┐
                │  Initialized  │       │       │  Error State │
                │  (Ready)      │       │       │  POST_FAILED │
                └───────┬───────┘       │       └──────────────┘
                        │               │       All ops return
                   C_Login              │       CKR_GENERAL_ERROR
                        ▼               │
                ┌───────────────┐       │
                │ Authenticated │       │
                │ (CO or User)  │       │
                └───────┬───────┘       │
                        │               │
                   C_Logout             │
                        │               │
                        ▼               │
                  Initialized ◄─────────┘
                        │
                   C_Finalize
                        ▼
                   Power Off

Session-Level States (PKCS#11)

    C_OpenSession(RO)               C_OpenSession(RW)
          │                               │
          ▼                               ▼
    ┌───────────┐                   ┌───────────┐
    │ RO Public │                   │ RW Public │
    │ (CKS=0)   │                   │ (CKS=2)   │
    └─────┬─────┘                   └──┬─────┬──┘
          │                            │     │
   C_Login│(User)            C_Login   │     │ C_Login
          │                 (User)     │     │ (SO)
          ▼                            ▼     ▼
    ┌───────────┐                ┌──────────┐ ┌────────┐
    │ RO User   │                │ RW User  │ │ RW SO  │
    │ (CKS=1)   │                │ (CKS=3)  │ │ (CKS=4)│
    └─────┬─────┘                └────┬─────┘ └───┬────┘
          │                           │            │
   C_Logout                    C_Logout     C_Logout
          │                           │            │
          ▼                           ▼            ▼
    RO Public                   RW Public    RW Public

Source: src/session/session.rs:7-13 (enum), lines 140-173 (transitions)

10.4 Development Environment

10.5 Delivery and Operation

Distribution:

• Source code via Git repository
• Compiled binaries via CI pipeline artifacts
• Release signing: GPG, Sigstore/cosign, or Windows Authenticode
• Source: docs/release-signing.md

Integrity Verification:

• HMAC-SHA256 sidecar file (.hmac) for runtime integrity test
• SHA-256 checksums for distribution verification
• Source: tools/compute-integrity-hmac.sh, tools/compute-integrity-hmac.ps1

Configuration:

• File: craton_hsm.toml (TOML format)
• Location: CRATON_HSM_CONFIG environment variable or working directory
• Source: src/config/config.rs

10.6 FIPS Build Procedures

# Build with FIPS-validated backend
cargo build --release --features awslc-backend

# Run full test suite
cargo test --release --features awslc-backend -- --test-threads=1

# Compute integrity HMAC
./tools/compute-integrity-hmac.sh target/release/libcraton_hsm.so

FIPS configuration (craton_hsm.toml):

[algorithms]
crypto_backend = "awslc"
fips_approved_only = true
enable_pqc = false
allow_sha1_signing = false

10.7 Guidance Documentation

---

11. Mitigation of Other Attacks

FIPS 140-3 Level 1 does not require mitigation of attacks beyond the module boundary. However, the module voluntarily implements the following mitigations:

---

Appendix A: Complete Mechanism Table

All 41 cryptographic mechanisms supported by the module:

RSA Mechanisms (FIPS 186-5):

ECDSA Mechanisms (FIPS 186-5):

ECDH Mechanisms (SP 800-56A):

EdDSA Mechanism:

AES Mechanisms (FIPS 197, SP 800-38A/D/F):

Digest Mechanisms (FIPS 180-4, FIPS 202):

Post-Quantum Mechanisms (PKCS#11 v3.2, not FIPS-approved):

The parameter set comes from the key's CKA_PARAMETER_SET. Keys use the v3.2 key types CKK_ML_KEM (0x49), CKK_ML_DSA (0x4A) and CKK_SLH_DSA (0x4B); the vendor-defined key types 0x80000001–0x80000003 used before v0.10.3 are mapped to these on load and in templates.

Post-Quantum Mechanisms (vendor-defined, not FIPS-approved):

Source: src/pkcs11_abi/constants.rs:92-138

---

Appendix B: Error Code Mapping

Complete mapping from internal HsmError variants to PKCS#11 CK_RV return codes:

Source: src/error.rs:104-157

---

Appendix C: Dependency Inventory

Critical cryptographic dependencies inside the module boundary:

Note: When built with --features awslc-backend and configured with crypto_backend = "awslc", all cryptographic operations are performed through the FIPS 140-3 validated aws-lc-rs library instead of the individual RustCrypto crates.

---

Appendix D: Test Suite Summary

Total: 547 tests across 29 test suites, plus 5 fuzz targets.

Fuzz Targets (cargo-fuzz):

---

Appendix E: Configuration Reference

Complete craton_hsm.toml schema with FIPS implications:

[token]
label = "Craton HSM Token"          # Token label (32 bytes max, ASCII)
storage_path = ""                 # Path for persistent storage (empty = in-memory only)
max_sessions = 100                # Maximum concurrent sessions
max_rw_sessions = 50              # Maximum read-write sessions

[security]
pin_min_length = 4                # Minimum PIN length (bytes)
pin_max_length = 64               # Maximum PIN length (bytes)
max_failed_logins = 10            # Failed login attempts before lockout
pbkdf2_iterations = 600000        # PBKDF2 iteration count

[algorithms]
crypto_backend = "rustcrypto"     # "rustcrypto" (default) or "awslc" (FIPS)
fips_approved_only = false         # true = block non-FIPS mechanisms
enable_pqc = true                  # true = enable PQC mechanisms
allow_weak_rsa = false             # true = allow RSA < 2048 bits
allow_sha1_signing = false         # true = allow SHA-1 in signing contexts

[audit]
enabled = true                     # Enable audit logging
log_path = ""                      # Audit log file path (empty = in-memory only)
log_level = "all"                  # "all", "security", or "errors"

[daemon]
bind = "127.0.0.1:5696"           # gRPC bind address (daemon only)
tls_cert = ""                      # TLS certificate path
tls_key = ""                       # TLS private key path

FIPS Mode Configuration Requirements:

---

End of FIPS 140-3 Security Policy and Certification Document Craton HSM v0.9.1 — 2026-03-17