Craton HSM Security Policy

DISCLAIMER: Craton HSM is NOT FIPS 140-3 certified. This document describes the security design targeting FIPS 140-3 Level 1 requirements. The module has not been validated by a CMVP-accredited laboratory.

Document Information

---

1. Module Description

Craton HSM is a PKCS#11 v3.0-compliant software Hardware Security Module (HSM) implemented in Rust. It provides cryptographic key management, generation, storage, and operations through the standard PKCS#11 C API interface.

The module runs as a shared library (libcraton_hsm.so / craton_hsm.dll) loaded into an application's address space, or as a standalone gRPC daemon for remote access.

1.1 Module Architecture

+---------------------------------------------------------------+
|                    Cryptographic Module Boundary                |
|                                                                 |
|  +-------------------+  +------------------+  +--------------+ |
|  | PKCS#11 C ABI     |  | gRPC Interface   |  | Admin CLI    | |
|  | (libcraton_hsm.so)   |  | (craton-hsm-daemon) |  | (craton_hsm-   | |
|  |                    |  |                  |  |  admin)      | |
|  +--------+-----------+  +--------+---------+  +------+-------+ |
|           |                       |                    |         |
|  +--------v-----------------------v--------------------v-------+ |
|  |                      HsmCore                                | |
|  |  +------------------+  +------------------+                 | |
|  |  | SessionManager   |  | SlotManager      |                 | |
|  |  | (DashMap)        |  | (Token, PIN)     |                 | |
|  |  +------------------+  +------------------+                 | |
|  |  +------------------+  +------------------+                 | |
|  |  | ObjectStore      |  | CryptoBackend    |                 | |
|  |  | (in-memory +     |  | (RustCrypto or   |                 | |
|  |  |  EncryptedStore) |  |  aws-lc-rs)      |                 | |
|  |  +------------------+  +------------------+                 | |
|  |  +------------------+  +------------------+                 | |
|  |  | AuditLog         |  | Self-Test (POST) |                 | |
|  |  +------------------+  +------------------+                 | |
|  +-------------------------------------------------------------+ |
+---------------------------------------------------------------+

1.2 Physical Boundary

As a software-only module (FIPS 140-3 Level 1), the physical boundary is defined by the process address space of the host application loading the module. There are no physical security mechanisms.

---

2. Ports and Interfaces

2.1 Logical Interfaces

2.2 API Entry Points

The module exports 70+ PKCS#11 v3.0 C functions via #[no_mangle] pub extern "C" declarations. All entry points use catch_unwind at the FFI boundary to prevent Rust panics from unwinding through C callers.

---

3. Roles, Services, and Authentication

3.1 Roles

3.2 Services

3.3 Authentication Mechanism

PINs are verified using PBKDF2-HMAC-SHA256 with 600,000 iterations and a random 32-byte salt. The PIN hash is stored; the plaintext PIN is never persisted. PIN comparison uses constant-time comparison (subtle::ConstantTimeEq) to prevent timing attacks.

Default PINs:

• SO PIN: "12345678" (must be changed on first use via C_InitToken)
• User PIN: Set by SO via C_InitPIN

---

4. Finite State Model

4.1 Module States

                    +---------------+
                    |   Power Off   |
                    +-------+-------+
                            |
                            v
                    +-------+-------+
             +----->|  POST Running |
             |      +-------+-------+
             |              |
             |        Pass  |  Fail
             |     +--------+--------+
             |     v                 v
      +------+-----+        +-------+-------+
      | Initialized |        |  POST Failed  |
      | (Ready)     |        | (Error State)  |
      +------+------+        +---------------+
             |                  All operations
             |                  return CKR_
             |                  GENERAL_ERROR
     C_Login |
             v
      +------+------+
      | Authenticated|
      | (Operational)|
      +------+------+
             |
     C_Logout|
             v
      (back to Initialized)

4.2 Session States

Per PKCS#11 specification, each session has an independent state:

4.3 Error States

• POST_FAILED: If any Power-On Self-Test fails, POST_FAILED AtomicBool is set. All subsequent cryptographic operations return CKR_GENERAL_ERROR.
• Fork Detected (Unix): If a child process calls any PKCS#11 function after fork(), it receives CKR_CRYPTOKI_NOT_INITIALIZED and must re-initialize.

---

5. Cryptographic Algorithms

5.1 Approved Algorithms

5.2 Non-Approved Algorithms

5.3 Crypto Backend Selection

Two backends are available at compile time:

For FIPS deployments, build with --features awslc-backend. The backend is selected by the crypto_backend configuration parameter. Both backends implement the identical CryptoBackend trait (26 methods).

5.4 Random Number Generation

The module uses an SP 800-90A-compliant HMAC_DRBG (HMAC-SHA256) for all cryptographic random number generation. The DRBG is seeded from the operating system's CSPRNG (OsRng):

• Linux: getrandom(2) system call
• Windows: BCryptGenRandom
• macOS: SecRandomCopyBytes

The DRBG provides:

• Prediction resistance: fresh entropy from OsRng on every generate call
• Continuous health test: compares consecutive DRBG outputs per SP 800-90B
• Reseed interval: 2^48 requests before mandatory reseed
• POST KAT: NIST CAVP known-answer test validates DRBG correctness at initialization

A continuous RNG health test on the entropy source (per SP 800-90B) compares each 32-byte output block against the previous output. Identical consecutive outputs cause the operation to fail.

---

6. Key Management

6.1 Key Generation

Keys are generated using approved algorithms and the SP 800-90A HMAC_DRBG (seeded from OS CSPRNG). Key material is allocated in process memory and immediately locked via mlock() (Unix) or VirtualLock() (Windows) to prevent paging to disk.

6.1.1 Key Lifecycle States (SP 800-57)

Keys support lifecycle state tracking per SP 800-57 Part 1:

State transitions based on CKA_START_DATE and CKA_END_DATE are evaluated automatically at each cryptographic operation.

6.2 Key Storage

Persistent storage uses a master encryption key derived from the SO PIN via PBKDF2 (600K iterations). Each object is serialized, encrypted with a unique random nonce, and stored as an opaque blob.

6.3 Key Protection

6.4 Key Destruction

When a key object is destroyed (via C_DestroyObject or session close for session objects):

1. RawKeyMaterial::drop() is called
2. Memory is overwritten with zeros via zeroize()
3. munlock_buffer() / VirtualUnlock() releases the memory lock
4. If persistent, the encrypted blob is deleted from the database

6.5 Key Import/Export

• Import: Via C_CreateObject with CKA_VALUE. Subject to CKA_TOKEN and CKA_PRIVATE attribute enforcement.
• Export: Only if CKA_EXTRACTABLE = true (defaults to false). Exported via C_GetAttributeValue for CKA_VALUE.
• Wrapping: AES Key Wrap (SP 800-38F) via C_WrapKey / C_UnwrapKey.

---

7. Self-Tests

7.1 Power-On Self-Tests (POST)

17 self-tests run at module initialization (C_Initialize):

The RNG health test verifies the OS random number generator produces non-zero, non-repeating output, and the DRBG continuous health test validates non-repeating DRBG output.

Note on KAT design (v0.9.1): AES-CBC and AES-CTR KATs use genuine known-answer tests with hardcoded expected ciphertexts (not circular encrypt/decrypt roundtrips). This catches symmetric implementation bugs that a roundtrip-only test would miss.

7.2 POST Failure Behavior

If any POST fails:

• POST_FAILED atomic flag is set to true
• All subsequent cryptographic operations return CKR_GENERAL_ERROR
• On re-initialization (after C_Finalize), POST_FAILED is reset and POST re-runs
• If POST fails again, the module remains in error state

7.3 Conditional Self-Tests (§9.6)

Pairwise test failure sets POST_FAILED and the module enters error state.

---

8. Operational Environment

8.1 Requirements

• Operating System: Any OS supporting Rust compilation (Linux, Windows, macOS)
• Rust Compiler: Edition 2021 or later
• Memory: Process must have sufficient mlock quota for key material

8.2 Multi-Process Considerations

• The module is NOT fork-safe on Unix. Child processes must call C_Initialize after fork.
• If persistent storage is enabled, only one process may access a given database path (enforced by exclusive file lock via fs2).
• Multi-process access is supported via the gRPC daemon (craton-hsm-daemon).

---

9. Design Assurance

9.1 Source Code Management

• All source code managed in Git
• Rust's ownership model provides compile-time memory safety guarantees
• No unsafe code outside the PKCS#11 C ABI boundary (where catch_unwind protects callers)

9.2 Testing

9.3 Build Configuration

For FIPS deployments:

# Build with FIPS-certified crypto backend
cargo build --release --features awslc-backend

# Verify all tests pass
cargo test --features awslc-backend -- --test-threads=1

---

10. Mitigation of Other Attacks

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

---

11. Critical Security Parameters (CSPs)

The following table documents all Critical Security Parameters managed by the module, their storage location, protection mechanism, and zeroization method.

11.1 CSP Lifecycle

Generation/Import --> mlock() --> Active Use --> zeroize() --> munlock() --> Destroyed
                      |                           |
                      |  (if persistent)           |
                      +-> AES-256-GCM encrypt ->   |
                          store in redb             |
                                                   |
                      (if persistent)              |
                      delete from redb <-----------+

11.2 CSP Access Control