---
title: "FIPS 140-3 Compliance Guide"
---

# FIPS 140-3 Compliance Guide

## Overview

HeliosDB-Lite supports FIPS 140-3 compliant cryptographic operations through the `fips` feature flag. When enabled, all cryptographic operations use the AWS-LC FIPS module (Certificate #4816).


| Component | Standard Mode | FIPS Mode | Certification |
|-----------|---------------|-----------|---------------|
| **Crypto Library** | ring 0.17 | AWS-LC 1.12 | FIPS 140-3 #4816 |
| **Content Hashing** | BLAKE3 | SHA-256 | NIST FIPS 180-4 |
| **Key Derivation** | Argon2id | PBKDF2-HMAC-SHA256 | NIST SP 800-132 |
| **Encryption** | AES-256-GCM | AES-256-GCM | NIST FIPS 197/SP 800-38D |
| **TLS** | rustls + ring | rustls + AWS-LC | NIST SP 800-52 |
| **Random** | ring SystemRandom | AWS-LC DRBG | NIST SP 800-90A |

## Building with FIPS Support

### Prerequisites

1. **Linux x86_64 or aarch64**: AWS-LC FIPS is currently certified for Linux only
2. **CMake 3.12+**: Required for building AWS-LC
3. **Go 1.18+**: Required for AWS-LC's build system (optional, for BoringSSL compatibility)
4. **Clang or GCC**: C/C++ compiler

### Build Commands

```bash
# Build with FIPS support
cargo build --release --no-default-features --features fips,encryption,vector-search

# Verify FIPS mode: the FIPS provider runs its power-on self-tests
# (SHA-256 and PBKDF2 known-answer tests, RNG check) when it is initialised
# and logs at info level:
#   "FIPS 140-3 self-tests passed (AWS-LC Certificate #4816)"
HELIOSDB_JWT_SECRET=change-me RUST_LOG=info \
  ./target/release/heliosdb-lite start --data-dir ./data --verbose
```

There is no `--version` or `--check-fips` CLI flag; check the startup log for the
self-test line above. A self-test failure aborts with a `FIPS self-test failed` error.

### Docker Build

```dockerfile
FROM rust:1.75-bookworm AS builder

# Install AWS-LC build dependencies
RUN apt-get update && apt-get install -y \
    cmake \
    clang \
    golang-go \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY . .

# Build with FIPS
RUN cargo build --release --no-default-features \
    --features fips,encryption,vector-search

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/heliosdb-lite /usr/local/bin/
CMD ["heliosdb-lite"]
```

## Algorithm Replacements in FIPS Mode

### Content-Addressed Storage

| Operation | Standard | FIPS |
|-----------|----------|------|
| Content hash | BLAKE3 | SHA-256 |
| Hash length | 256 bits | 256 bits |
| Performance | ~10 GB/s | ~1 GB/s |

**Note**: SHA-256 is slower than BLAKE3 but is required for FIPS compliance. Content-addressed storage performance may be reduced by approximately 10x.

### Key Derivation

| Parameter | Standard (Argon2id) | FIPS (PBKDF2) |
|-----------|---------------------|---------------|
| Algorithm | Argon2id | PBKDF2-HMAC-SHA256 |
| Memory | 64 MB | N/A |
| Iterations | 3 | 600,000 |
| Parallelism | 4 | 1 |

**Note**: PBKDF2 requires more iterations to achieve comparable security to Argon2id. Key derivation from password will be slower in FIPS mode.

### Encryption

AES-256-GCM is used in both modes. The only difference is the underlying implementation:

| Aspect | Standard | FIPS |
|--------|----------|------|
| Library | aes-gcm crate | AWS-LC |
| Algorithm | AES-256-GCM | AES-256-GCM |
| AEAD | Yes | Yes |

## FIPS Self-Tests

AWS-LC automatically runs Power-On Self-Tests (POST) at module initialization. HeliosDB-Lite adds application-level verification:

### Automatic Self-Tests

1. **SHA-256 KAT**: Known Answer Test for hash function
2. **PBKDF2 KAT**: Key derivation verification
3. **AES-GCM KAT**: Encryption/decryption verification
4. **DRBG Health**: Random number generator verification

### Manual Verification

The self-tests run when the FIPS provider is initialised at startup; there is no separate
check command. Start the server with info-level logging and look for the self-test line:

```bash
HELIOSDB_JWT_SECRET=change-me RUST_LOG=info \
  ./target/release/heliosdb-lite start --data-dir ./data 2>&1 | grep -i "FIPS 140-3"
# FIPS 140-3 self-tests passed (AWS-LC Certificate #4816)
```

A self-test failure aborts startup with a `FIPS self-test failed` error.

## Configuration

FIPS mode is selected at build time with the `fips` feature (see Build Commands). There are no
runtime FIPS settings: a FIPS build always runs the self-tests at startup.

## Compliance Documentation

### Startup Log

HeliosDB-Lite logs its FIPS self-tests and algorithm selection at startup:

```
INFO  FIPS 140-3 self-tests passed (AWS-LC Certificate #4816)
INFO  Using FIPS-approved algorithms: SHA-256, PBKDF2, AES-256-GCM
DEBUG Key derived using PBKDF2-HMAC-SHA256 (600000 iterations)
```

### Security Considerations

1. **Key Material**: All keys are stored using `zeroize` for secure memory erasure
2. **Salt Requirements**: Minimum 128-bit salt for key derivation
3. **IV/Nonce**: Unique 96-bit nonce per encryption operation
4. **Algorithm Negotiation**: No fallback to non-FIPS algorithms in FIPS mode

## Migration Guide

### From Standard to FIPS Mode

1. **Backup existing data**
2. **Export keys** (if using password-derived keys)
3. **Rebuild with FIPS feature**
4. **Re-encrypt data** (content hashes will differ)

```sql
-- Re-index content-addressed data after FIPS migration
REINDEX CONTENT_ADDRESSED;
```

### Data Compatibility

**Warning**: Content-addressed storage hashes are **NOT compatible** between BLAKE3 (standard) and SHA-256 (FIPS) modes. Migration requires:

1. Export all data
2. Rebuild with new mode
3. Re-import data (re-computes hashes)

## Limitations

### Platform Support

| Platform | FIPS Support |
|----------|--------------|
| Linux x86_64 | Certified |
| Linux aarch64 | Certified |
| macOS | Not certified* |
| Windows | Not certified* |

*AWS-LC builds on these platforms but lacks FIPS certification.

### Performance Impact

| Operation | Standard | FIPS | Impact |
|-----------|----------|------|--------|
| Content hash (1 MB) | 0.1 ms | 1.0 ms | -10x |
| Key derivation | 100 ms | 800 ms | -8x |
| AES-GCM encrypt | 0.01 ms/KB | 0.01 ms/KB | ~Same |
| TLS handshake | 2 ms | 3 ms | -1.5x |

### Feature Restrictions

In FIPS mode, the following are disabled:

- BLAKE3 hashing (non-approved algorithm)
- Argon2id KDF (non-approved algorithm)
- ChaCha20-Poly1305 (if used anywhere)

## Verification Checklist

### Deployment Verification

- [ ] Built with `--features fips`
- [ ] FIPS self-tests pass at startup
- [ ] Version output shows "AWS-LC FIPS"
- [ ] No BLAKE3/Argon2 warnings in logs
- [ ] TLS negotiates FIPS-approved cipher suites

### Compliance Audit

- [ ] AWS-LC Certificate #4816 current and valid
- [ ] Operating in approved mode
- [ ] Keys stored/derived using approved methods
- [ ] Server logs retained (built-in audit logging is planned)
- [ ] Incident response procedures documented

## References

- [AWS-LC FIPS Module](https://github.com/aws/aws-lc)
- [NIST CMVP Certificate #4816](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4816)
- [NIST SP 800-132: Password-Based Key Derivation](https://csrc.nist.gov/publications/detail/sp/800-132/final)
- [NIST SP 800-38D: AES-GCM](https://csrc.nist.gov/publications/detail/sp/800-38d/final)
- [NIST FIPS 180-4: SHA-256](https://csrc.nist.gov/publications/detail/fips/180/4/final)

## Support

For FIPS compliance questions:
- Email: security@heliosdb.com
- GitHub: Open an issue with the "fips" label