FIPS Mode

FIPS mode is an operational configuration that restricts Craton HSM to FIPS-approved mechanisms and routes all classical cryptography through the FIPS-validated AWS-LC library. This page describes how to enable it, what changes at runtime, and how to verify the module is operating in the intended mode.

Enabling FIPS mode does not turn Craton HSM into a CMVP-validated module. See overview for the distinction.

Prerequisites

FIPS mode requires a build with the awslc-backend feature. The default build uses pure-Rust primitives that are not FIPS-validated.

cargo build --release --features awslc-backend

Building aws-lc-rs needs CMake 3.x, Clang/LLVM, and Go 1.18 or newer. On Windows:

$env:LIBCLANG_PATH = "C:\path\to\llvm\bin"
$env:AWS_LC_SYS_NO_ASM = "1"

See ../operations/installation for full build requirements.

Configuration

Edit craton_hsm.toml (or set CRATON_HSM_CONFIG to point at the file):

[algorithms]
# Required: select the FIPS-validated backend
crypto_backend = "awslc"

# Required: reject non-approved mechanisms
fips_approved_only = true

# Recommended: keep post-quantum mechanisms disabled
enable_pqc = false

# Defaults — already correct for FIPS, listed for clarity
allow_weak_rsa = false
allow_sha1_signing = false

fips_approved_only = true is the switch that changes runtime behaviour. Without it, the module still runs against AWS-LC but leaves non-approved mechanisms visible, which defeats the purpose in a regulated deployment.

What Changes in FIPS Mode

Rejected Mechanisms

The following return CKR_MECHANISM_INVALID from C_EncryptInit, C_DecryptInit, C_SignInit, C_VerifyInit, C_GenerateKey, C_GenerateKeyPair, C_WrapKey, C_UnwrapKey, and C_DeriveKey:

C_GetMechanismList returns only the approved subset when fips_approved_only = true, so applications that query mechanism capabilities see a consistent view.

Key Size Enforcement

RSA key size validation strips leading zero bytes before counting, so legitimate keys whose modulus starts with a leading zero are accepted and keys that would otherwise under-count are rejected.

PBKDF2 Parameters

Lowering the iteration count below 600,000 is rejected at config load. The comparison path uses subtle::ConstantTimeEq.

IV and Nonce Handling

• AES-CBC and AES-CTR reject an all-zero IV at C_EncryptInit.
• AES-GCM nonces are tracked with a per-key counter (SHA-256 of key material → AtomicU64) and a 2^31 limit; approaching the limit emits warnings at 50%, 75%, 90%, 95%, and 99%. Nonce reuse aborts the operation.

Software Integrity Sidecar

The integrity check at C_Initialize compares an HMAC-SHA256 of the module binary against a .hmac sidecar file next to the library.

After every build, regenerate the sidecar:

# Linux / macOS
./tools/compute-integrity-hmac.sh target/release/libcraton_hsm.so

# Windows
.\tools\compute-integrity-hmac.ps1 -LibPath target\release\craton_hsm.dll

This writes libcraton_hsm.hmac / craton_hsm.hmac next to the binary. Under the FIPS build feature the sidecar is mandatory; a missing or mismatched sidecar fails POST and leaves the module in error state with all operations returning CKR_GENERAL_ERROR.

Verifying FIPS Mode at Runtime

1. POST Success

C_Initialize returns CKR_OK only after all 17 self-tests pass (1 integrity check + 16 KATs). Any failure returns CKR_GENERAL_ERROR and sets POST_FAILED. See self-tests.

2. Mechanism List

pkcs11-tool --module ./libcraton_hsm.so --list-mechanisms

The list must not contain EDDSA, any ML-*, SLH-*, or HYBRID entries. Prehashed RSA and ECDSA combined-hash mechanisms must also be absent.

3. Algorithm Indicator in the Audit Log

Every crypto operation audit entry carries fips_approved: true in FIPS mode:

{
  "timestamp": 1743379200000000000,
  "session_handle": 1,
  "operation": {
    "Sign": {
      "mechanism": 7,
      "fips_approved": true
    }
  },
  "result": "Success",
  "previous_hash": "..."
}

Any fips_approved: false entry in a FIPS-mode deployment indicates either a misconfiguration or a caller reaching a mechanism the enforcement path missed — treat it as an incident and review the audit log chain.

4. Session State

Each session records last_operation_fips_approved. Applications that need a post-operation check can retrieve this through the session info extensions, or query the vendor-defined attribute CKA_VENDOR_FIPS_APPROVED (0x80000001).

5. Backend Identity

The module logs the resolved backend at C_Initialize:

craton_hsm: crypto backend = awslc, fips_approved_only = true

If the resolved backend is rustcrypto, FIPS mode is not active regardless of the fips_approved_only setting.

Deployment Checklist

• Build with --features awslc-backend.
• Set crypto_backend = "awslc" and fips_approved_only = true in craton_hsm.toml.
• Regenerate the .hmac sidecar and deploy it alongside the library.
• Verify C_Initialize returns CKR_OK.
• Verify only approved mechanisms appear in C_GetMechanismList.
• Initialise the token with a strong SO PIN; set a strong user PIN.
• Confirm the startup log shows crypto backend = awslc.
• Forward the audit log to the SIEM and alert on any fips_approved: false entry.
• Schedule a quarterly review of the FIPS configuration and the tested operational environment list.

Further Reading

• self-tests — POST and conditional self-test details
• gap-analysis — what FIPS mode does not cover
• ../security/hardening — deployment hardening
• ../security/audit-scope — audit log coverage