Skip to content
HeliosDB Nano

FIPS 140-3 Compliance Tutorial

FIPS 140-3 Compliance Tutorial

Available since: v3.6.0 Build: cargo build --release --no-default-features --features "fips,encryption,vector-search,ha-tier1" Crypto provider: AWS-LC FIPS — NIST CMVP Certificate #4816

UVP

Most embedded databases either ship a single crypto stack you can’t swap, or punt FIPS compliance to a wrapper layer. HeliosDB Nano builds the same source tree in two modes via Cargo features: the default ring-crypto (BLAKE3 + Argon2id) for performance, or fips (AWS-LC FIPS Certificate #4816 + SHA-256 + PBKDF2-HMAC-SHA256) for regulated environments. No code change. Same SQL. Same wire protocol. Same data files. Toggle the feature flag and you have a binary that satisfies FedRAMP / DoD / FIPS 140-3 requirements out of the box — no third-party HSM required.

When You Need This

You areUse
Building for US Federal civilian / DoD / ICFIPS mode (mandatory under FIPS 140-3 / FedRAMP)
State / municipal government with NIST mandateFIPS mode
HIPAA + Defense contractor (e.g., DHA)FIPS mode
PCI / SOC 2 / GDPR commercialDefault ring-crypto is sufficient
Pure performance benchmarkDefault ring-crypto (BLAKE3 is ~3× faster than SHA-256)

Prerequisites

  • Rust 1.85+ toolchain
  • A C/C++ toolchain (AWS-LC builds native FIPS-validated assembly)
  • ~5 minutes
Terminal window
rustc --version          # 1.85+
cc --version             # any modern gcc/clang

1. Build the FIPS Binary

The fips feature is mutually exclusive with the default ring-crypto. You must opt out of defaults:

Terminal window
git clone https://github.com/Dimensigon/HDB-HeliosDB-Nano.git
cd HDB-HeliosDB-Nano


cargo build --release \
    --no-default-features \
    --features "fips,encryption,vector-search,ha-tier1"

The build pulls aws-lc-rs = { version = "1.12", features = ["fips"] }, which compiles the FIPS-validated AWS-LC C library with the same source as Certificate #4816.

Verify:

Terminal window
./target/release/heliosdb-nano --version
# heliosdb-nano 3.19.1

2. What Changes in FIPS Mode

The crypto provider is a trait (src/crypto/provider.rs); the fips feature swaps which implementation gets compiled in. Three primitives differ:

OperationDefault (ring-crypto)FIPS (fips)
Content hashing (CAS, dump checksums)BLAKE3SHA-256 (NIST FIPS 180-4)
KDF for password / TDE keysArgon2id (memory-hard)PBKDF2-HMAC-SHA256 (NIST SP 800-132)
Random bytes (TDE keys, IVs)ring::rand::SystemRandomAWS-LC FIPS DRBG (SP 800-90A CTR_DRBG)
Symmetric encryptionAES-256-GCM (ring)AES-256-GCM (AWS-LC FIPS)
TLS providerrustls + ringrustls + AWS-LC FIPS

Argon2id is not on the FIPS-approved list, which is why HeliosDB swaps in PBKDF2 in this mode. PBKDF2 is computationally cheaper than Argon2id — log in attempts will be marginally faster, but the security guarantee shifts from memory-hardness to iteration count.

3. Confirm You’re Running FIPS

Start the server and check the startup banner:

Terminal window
./target/release/heliosdb-nano start \
    --memory \
    --auth scram-sha-256 \
    --password s3cret

The banner names the active crypto provider:

[2/4] Initializing in-memory database...
      Crypto provider: aws-lc-rs (SHA-256 + PBKDF2-HMAC-SHA256, FIPS Cert #4816)

You can also check from SQL:

Terminal window
psql "postgresql://postgres:s3cret@127.0.0.1:5432/postgres" -c \
    "SELECT current_setting('helios.crypto_provider');"
#  current_setting
# ----------------------------------------------------------------
#  aws-lc-rs (SHA-256 + PBKDF2-HMAC-SHA256, FIPS Cert #4816)

4. Programmatic Self-Test

The CryptoProvider trait exposes run_self_test() which exercises the FIPS power-on self-tests (KAT vectors for AES-GCM, SHA-256, HMAC, DRBG):

use heliosdb_nano::crypto::provider::default_provider;


fn main() -> heliosdb_nano::Result<()> {
    let crypto = default_provider();
    println!("Provider: {}", crypto.name());
    println!("FIPS:     {}", crypto.is_fips());
    crypto.run_self_test()?;
    println!("Self-test: PASS");
    Ok(())
}

When built with --features fips, is_fips() returns true and run_self_test() runs the KATs that AWS-LC requires before any cryptographic operation.

5. Encryption At Rest — Same SQL, FIPS Cipher Suite

TDE (Transparent Data Encryption) reads its key material through the active provider. The DDL is unchanged from the default build:

-- Wrap an entire tablespace in TDE
CREATE ENCRYPTED TABLESPACE classified
WITH (algorithm = 'AES-256-GCM', key_source = 'master_key');


CREATE TABLE classified.documents (
  id    SERIAL PRIMARY KEY,
  title TEXT,
  body  BYTEA      -- on-disk pages encrypted under FIPS-derived key
);

In FIPS mode the master key is derived via PBKDF2-HMAC-SHA256 (600 000 iterations by default — meets NIST SP 800-132 § 5.1) and the page-level cipher is AES-256-GCM from AWS-LC.

6. TLS / wire encryption

Terminal window
./target/release/heliosdb-nano start \
    --data-dir ./data \
    --tls-cert /etc/heliosdb/server.pem \
    --tls-key  /etc/heliosdb/server.key \
    --auth scram-sha-256 --password s3cret

The TLS handshake is performed by rustls backed by the AWS-LC FIPS provider — no separate OpenSSL FIPS module required.

7. Audit Trail

The audit log (see AUDIT_LOGGING_TUTORIAL) chains every event with SHA-256 checksums in FIPS mode (BLAKE3 in the default build). The chain hash is verifiable post-incident:

SELECT pg_audit_verify_chain();
-- t   (chain intact)

Troubleshooting

SymptomCauseFix
error: feature 'fips' and 'ring-crypto' are mutually exclusiveForgot --no-default-featuresRe-run with --no-default-features --features "fips,encryption,vector-search,ha-tier1"
Build fails with aws-lc-sys link errorMissing C toolchainInstall gcc/clang and cmake
is_fips() returns false at runtimeDefault build, not FIPS buildRebuild with the fips feature; verify via the startup banner
Self-test panic on first crypto opA KAT failed (corrupted binary, mismatched AWS-LC version)Reproduce on a clean checkout; report with cargo --version
Slower password hashing than expectedPBKDF2 with 600k iterations is the FIPS minimumThis is intentional — FIPS prefers iteration count over memory hardness

Where Next