Craton HSM

Certified Build Tooling

Certified Build Tooling

The craton-hsm-certified crate provides the tooling a module vendor needs when preparing a FIPS 140-3 Level 1 submission: an approved-mode finite state machine, ACVP test-vector runner, CMVP artifact packaging, reproducible-build verification, and HMAC-SHA256 binary signing with a tamper-evident metadata envelope.

  • Crate: craton-hsm-certified
  • License: BSL 1.1
  • MSRV: Rust 1.75
  • Safety: #![deny(unsafe_code)] at the crate root.
  • Status: production-ready tooling

This crate provides the tooling. The Craton HSM module itself is not yet FIPS 140-3 certified — validation is a process involving a CMVP-accredited lab, not a property of this code alone. See the FIPS certification plan for status.

Modules

  • fsm — Models the FIPS 140-3 module states and validates the transition graph.
  • acvp — ACVP / CAVP test-vector runner.
  • cmvp — Packages CMVP submission artifacts.
  • security_policy — Structured FIPS security-policy document generation.
  • integrity — HMAC-SHA256 power-on integrity check helpers.
  • reproducibility — SHA-256-based reproducible-build verification.
  • approved_mode — Runtime enforcement of approved-mode configuration.
  • test_harness — Certification test harness with known-answer tests, instantiated against the FIPS-validated aws-lc-rs backend.
  • binary_sign — Binary signing with canonical-JSON metadata envelope.

Approved-Mode State Machine

The fsm module models the FIPS 140-3 module states (PowerOff, PowerOn, SelfTest, CryptoOfficerMode, UserMode, ErrorState, Zeroization) and validates the transition graph:

  • SelfTest is the only path out of PowerOn.
  • ErrorState can only transition to Zeroization or PowerOff.
  • Operational states must pass through Zeroization before PowerOff (FIPS 140-3 §7.9 zeroization-on-shutdown).
  • No unreachable or dead states are allowed, other than PowerOff as the terminal state.
use craton_hsm_certified::fsm::{ModuleFsm, ModuleState};

let fsm = ModuleFsm::fips_140_3_default();
fsm.validate()?;
assert_eq!(fsm.initial_state(), ModuleState::PowerOff);
# Ok::<(), craton_hsm_certified::fsm::FsmError>(())

ACVP / CAVP Harness

The acvp module parses NIST ACVP JSON, runs Known-Answer, Monte-Carlo, and Algorithm-Functional tests against a CryptoBackend, and emits ACVP response JSON for submission.

Coverage:

  • AES-GCM
  • AES-CBC
  • SHA-2 (256 / 384 / 512)
  • HMAC
  • RSA
  • ECDSA

The harness is instantiated against the FIPS-validated aws-lc-rs backend. Additional algorithm coverage (KAS, KDFs beyond HKDF, DRBG-specific validations) is on the roadmap. NIST ACVP test-vector JSON files are not bundled — obtain them from NIST and point the runner at them.

Reproducible Builds

The reproducibility module checks SHA-256 equality between two built binaries. Producing byte-reproducible binaries is a build-system concern, not a code concern — the crate verifies equality; you are responsible for deterministic inputs.

To reproduce a certified build from source:

  1. Freeze the toolchain. Use the exact rustc version recorded in the release manifest. Do not let rust-toolchain.toml silently update.
  2. Lock dependency versions. Use the released Cargo.lock without modification.
  3. Pin RUSTFLAGS to the values in the release manifest.
  4. Set SOURCE_DATE_EPOCH to the release timestamp so timestamp- dependent build metadata is deterministic.
  5. Build from the exact Git SHA of the release tag.
  6. Compare the output binary with the published reference using the reproducibility module's SHA-256 equality check.
# Example: reproduce release v0.1.1
export SOURCE_DATE_EPOCH=$(git log -1 --format=%ct v0.1.1)
export RUSTFLAGS="-C link-arg=-s"  # match the release manifest

git checkout v0.1.1
cargo build --release --locked --features fips \
    -p craton-hsm-awslc

sha256sum target/release/libcraton_hsm_awslc.*
# Compare against the reference SHA in the release manifest.

If the SHAs match, you have reproduced the certified binary. If they differ, consult the release manifest for the exact toolchain and flags in use.

CMVP Artifact Generation

The cmvp and security_policy modules package the artifacts a CMVP lab needs: test results, security-policy document, known-answer-test logs. Drive them from your release pipeline after the ACVP harness has produced the response JSON.

Binary Signing

The binary_sign module appends a tamper-evident footer to a built binary. Envelope layout:

[original binary bytes]
[FOOTER_MAGIC = "RHSMSIGN"]   (8 bytes)
[FOOTER_VERSION]              (u8)
[original_len]                (u64 LE)
[metadata_json]               (canonical JSON of BinaryMetadata)
[metadata_len]                (u32 LE)
[integrity_tag]               (HMAC-SHA256 over everything above)

The HMAC tag covers every preceding byte, so inserting or removing bytes between the original binary and the footer, or nesting an old footer inside a new one, is detected on verify.

use craton_hsm_certified::binary_sign::{sign_binary, verify_binary, BinaryMetadata};

let key: [u8; 32] = [0u8; 32];            // in practice, a zeroizing secret
let meta          = BinaryMetadata::default();

sign_binary  ("target/release/craton-hsmd", &key, meta)?;
verify_binary("target/release/craton-hsmd", &key)?;
# Ok::<(), Box<dyn std::error::Error>>(())

The HMAC key is a symmetric secret; distribution is out of scope for this crate. Typical deployment keeps the HMAC key in a signing HSM and verifies the binary at module load inside the integrity check.

Integrity Check on Load

The integrity module wraps the verify path for a power-on integrity test. Typical use: compute HMAC-SHA256 over the loaded module's bytes, compare against the footer tag, and refuse to enter CryptoOfficerMode if the tag does not match.

Feature Flags

This crate exposes no Cargo features. The craton-hsm dependency is pulled in with features = ["awslc-backend"] so the test harness can run ACVP vectors against FIPS-validated primitives.

Error Reporting

Each module has a dedicated error type (FsmError, AcvpError, IntegrityError, SignError, etc.) — see the module docs.

Limitations

  • The module is not yet FIPS-certified. This crate produces artifacts useful to a CMVP lab; it does not confer validation by itself.
  • Binary signing is HMAC-SHA256, a symmetric primitive. Key distribution is out of scope for this crate.
  • Reproducible-build verification checks SHA-256 equality; producing reproducible binaries is a build-system concern.
  • ACVP coverage is partial. Algorithms covered are listed above; additional KAS / KDF / DRBG validations are on the roadmap.

Related Documents