# FIPS Readiness Tasks

Internal working plan. This is not a FIPS validation claim.

Last external source check: 2026-05-16.

## Hard Rules

- Do not say `rscrypto` is FIPS validated unless CMVP has issued a certificate for the exact module, version, build, and operational environment.
- Do not treat "algorithm appears in a NIST standard" as "this crate is validated."
- Do not mix non-approved algorithms into a claimed FIPS boundary.
- Do not add a FIPS mode that silently changes behavior without clear status reporting.
- Verify all standards and ACVP coverage again before implementation work starts.

## Scope

Near-term target: FIPS-ready structure.

That means `rscrypto` can define a credible module boundary, run self-tests,
organize official vectors, document sensitive material handling, and produce
traceable release artifacts. It does not mean the crate is validated.

Formal validation is separate work:

- CMVP validation requires a third-party accredited lab.
- CAVP/ACVP algorithm validation normally comes before module validation.
- A certificate is tied to specific code, build configuration, and operational environments.

## Candidate Boundary

Implemented primitives that may belong in a future FIPS-ready boundary, subject
to fresh standards and ACVP review:

- AES-GCM: `Aes128Gcm`, `Aes256Gcm`.
- SHA-2: SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/256.
- SHA-3 and XOFs: SHA3 family, SHAKE128, SHAKE256, cSHAKE256.
- MAC/KDF: HMAC-SHA256/SHA384/SHA512, HKDF-SHA256/SHA384, KMAC256.
- Signatures/key agreement: Ed25519 and X25519 are candidates only after confirming the validation path.

Keep these outside any FIPS boundary:

- AES-GCM-SIV.
- AEGIS.
- ChaCha20-Poly1305 and XChaCha20-Poly1305.
- BLAKE2 and BLAKE3.
- XXH3, RapidHash, and CRCs.
- Password hashing unless a specific validated use is defined.

## Path A: FIPS-Ready Structure

### 1. Boundary Policy

- [ ] Decide whether the boundary is a feature-gated facade, a separate crate, or a documented subset of the core crate.
- [ ] List every API inside the boundary.
- [ ] List every API outside the boundary.
- [ ] Define status reporting for self-test failure and non-FIPS use.
- [ ] Decide how `portable-only` interacts with the boundary.

Verify:

- [ ] A reader can tell which APIs are inside the boundary without reading source.
- [ ] Non-approved algorithms cannot be accidentally presented as inside the boundary.

### 2. Power-Up Known-Answer Tests

- [ ] Add self-test orchestration under `src/fips/` or an equivalent boundary module.
- [ ] Add KATs from official vectors for each boundary algorithm.
- [ ] Ensure approved algorithms cannot run before required self-tests pass.
- [ ] Halt or enter a permanent error state on self-test failure.

Minimum KAT set:

- [ ] AES-128-GCM encrypt/decrypt/tag verify.
- [ ] AES-256-GCM encrypt/decrypt/tag verify.
- [ ] SHA-256, SHA-384, SHA-512.
- [ ] SHA3-256, SHA3-512, SHAKE256.
- [ ] HMAC-SHA256, HMAC-SHA384, HMAC-SHA512.
- [ ] HKDF-SHA256 and HKDF-SHA384.
- [ ] KMAC256.
- [ ] Ed25519 only if kept inside the candidate boundary.
- [ ] X25519 only if kept inside the candidate boundary.

Verify:

- [ ] Self-tests run exactly once per process or according to the documented `no_std` policy.
- [ ] Failure tests prove the module refuses service after a failed KAT.

### 3. Conditional Self-Tests

- [ ] Pairwise consistency tests for generated signing keys that remain inside the boundary.
- [ ] Pairwise or public-key validation tests for key agreement if included.
- [ ] Continuous RNG test after a DRBG exists.

Verify:

- [ ] Conditional tests are triggered by the documented events.
- [ ] Failure behavior matches the module state model.

### 4. DRBG Decision

`rscrypto` currently accepts caller-provided entropy for key generation helpers;
it is not an RNG crate.

Options:

- HMAC-DRBG with HMAC-SHA256.
- CTR-DRBG if AES-CTR becomes internal infrastructure.
- No DRBG in core, with FIPS users required to provide entropy from a validated module.

Recommendation: prefer the smallest design that avoids pretending OS randomness is automatically a FIPS DRBG.

Verify:

- [ ] Entropy source responsibilities are documented.
- [ ] Test vectors cover instantiate, generate, reseed, and failure cases if a DRBG is implemented.

### 5. Zeroization Audit

- [ ] Expanded AES schedules.
- [ ] GHASH/Polyval state and intermediates.
- [ ] HMAC pads.
- [ ] HKDF PRK material.
- [ ] Ed25519 scalar intermediates.
- [ ] X25519 scalar and shared secret.
- [ ] DRBG state if implemented.

Verify:

- [ ] Sensitive types implement `Drop` or an equivalent zeroization path.
- [ ] `Debug` never prints secrets.
- [ ] Optimized builds retain the intended wipe mechanism.

### 6. CAVP/ACVP Vector Organization

- [ ] Put official vectors under a stable `testdata/` layout with provenance comments.
- [ ] Separate correctness vectors from validation-submission fixtures.
- [ ] Cover success and fail cases.
- [ ] Track gaps per algorithm.

Verify:

- [ ] The vector source is named for every file.
- [ ] CI can run the boundary vector suite independently.

### 7. Boundary Documentation

- [ ] Module boundary.
- [ ] Approved and non-approved services.
- [ ] Sensitive security parameters.
- [ ] Finite state model.
- [ ] Interfaces and status indicators.
- [ ] Operational environment assumptions.
- [ ] Build flags and toolchain.
- [ ] User guidance.

Verify:

- [ ] The document avoids validation claims.
- [ ] The documented build can be reproduced.

### 8. Release Provenance

- [ ] SBOM for tagged releases.
- [ ] Signed release artifacts.
- [ ] Checksums.
- [ ] Provenance attestations.
- [ ] Pinned release workflow actions.
- [ ] Verification recipe for users.

Verify:

- [ ] The crates.io package, git tag, and source archive refer to the same source tree.

## Path B: Formal Validation

Start this only after Path A is stable and a budget exists.

- [ ] Select target module boundary.
- [ ] Select operational environments.
- [ ] Select a CMVP-accredited lab.
- [ ] Confirm CAVP/ACVP scope for each algorithm.
- [ ] Produce the security policy package.
- [ ] Run lab testing.
- [ ] Respond to CMVP comments.
- [ ] Maintain a validation branch and change-control policy.

## Open Questions

- Should Ed25519 be inside the first candidate boundary or kept outside until the validation path is unambiguous?
- Should X25519 be inside the first candidate boundary or limited to TLS/non-FIPS use first?
- Should the first FIPS-ready surface use only `portable-only` code to simplify review?
- Should DRBG live in core, a FIPS facade, or caller infrastructure?

## Sources

- FIPS 140-3: https://csrc.nist.gov/pubs/fips/140-3/final
- CMVP: https://csrc.nist.gov/Projects/Cryptographic-Module-Validation-Program
- CAVP ACVTS access: https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/how-to-access-acvts
- ACVP project: https://pages.nist.gov/ACVP/
- SP 800-90A Rev. 1: https://csrc.nist.gov/pubs/sp/800/90/a/r1/final
- FIPS 186-5: https://csrc.nist.gov/pubs/fips/186-5/final
- SP 800-186: https://csrc.nist.gov/pubs/sp/800/186/final
- SP 800-140 series overview: https://csrc.nist.gov/Projects/fips-140-3-transition-effort/fips-140-3-docs
