ML-KEM: KEM layer, input checks and zeroization #10

Activity

1. Zikithezikit

   added this to the 2.0.0 milestone on Oct 29, 2026
2. Zikithezikit

   added

   enhancementNew feature or requestNew feature or request

   ml-kemML-KEM (FIPS 203) workML-KEM (FIPS 203) work

   securitySecurity review, hardening, findingsSecurity review, hardening, findings

   on Oct 29, 2026
3. Zikithezikit

   added a parent issue on Oct 29, 2026

   • [2.0] Add ML-KEM (FIPS 203) support while keeping legacy Kyber API with deprecation #3
4. Zikithezikit

   marked this as blocked on Oct 29, 2026

   • ML-KEM: K-PKE key generation, encryption and decryption #9
5. Zikithezikit

   marked this as blocking 5 issues on Oct 29, 2026

   • Test ML-KEM against the NIST ACVP vectors #11
   • Test ML-KEM against C2SP CCTV and Wycheproof, plus a differential test #12
   • Python classes ML_KEM_512, ML_KEM_768, ML_KEM_1024 #13
   • Timing checks: assembly scan and a dynamic timing test #16
   • Fuzzing and dependency checks #17
6. Zikithezikit commented on Oct 29, 2026

   

   Zikithezikit

   on Oct 29, 2026

   OwnerAuthor

   More actions

   Open question: do we expose ML-KEM in the public Rust crate API for 2.0, or keep the crate Python-only for now? I'm leaning towards Python-only, but I'm open to arguments.

   In the meantime we'll keep it python only.
7. Zikithezikit commented on Oct 30, 2026

   

   Zikithezikit

   on Oct 30, 2026

   OwnerAuthor

   More actions

   Notes for whoever picks this up, from WP-3 part one (#9, merged in #29). Read the module docs at the top of src/mlkem/mod.rs first.

   What exists now in src/mlkem/ (still crate-private, still under the dead_code allow in src/lib.rs, keep it until WP-5 wires something in):

   • kpke.rs: keygen::(d: &[u8; 32]) -> (ek_PKE Vec, dk_PKE Zeroizing), encrypt::(ek, m, r) -> Result<Vec, KyberError>, decrypt::(dk_PKE, c) -> Result<Zeroizing<[u8; 32]>, KyberError>. They only check lengths (KyberError::InvalidInput). The section 7.2 modulus check, the 7.3 hash check and the full dk length check are yours.
   • compress.rs: poly_compress(r, a, d), poly_decompress(r, a, d) and poly_from_msg. d is a runtime argument because stable Rust cannot take ParamSet constants as const generics. Call generic code with the pattern kpke.rs uses in its tests, kpke::keygen::<{ MlKem768::K }>(..).
   • fetch mechanism: scripts/fetch_vectors.py and tests/vectors/manifest.json (pinned ACVP-Server commit, SHA-256 per file), run by scripts/check.sh and the CI test job. Test ML-KEM against the NIST ACVP vectors #11 and Test ML-KEM against C2SP CCTV and Wycheproof, plus a differential test #12 extend it.
   • acvp_tests.rs: decaps_case is a test-only copy of Algorithm 18 built from kpke::decrypt and encrypt. Replace it with the real decaps_internal once it exists and keep the cases.

   Things you will have to write yourself:

   • The constant-time compare of c and c' and the K' / K-bar select. Do not use kyber/verify.rs (no barrier, caller-supplied length). poly_from_msg shows the idiom used so far (mask through core::hint::black_box). That is best effort, so check the release assembly for the compare and the select and put the grep output in the PR.
   • H is sha3_256, G is sha3_512, J(z || c) is shake256 with 32 bytes of output, all from kyber::fips202. Test code in acvp_tests.rs has small wrappers you can copy.
   • Randomness: rand 0.8 is already a dependency and has OsRng, so no new crate is needed. try_fill_bytes and return KyberError::RandomBytesGeneration on failure; do not use thread_rng for key material.
   • The reject flag must not be returned or stored, and dk, z, m, r, K and K-bar all need zeroizing on the error paths too.

   Things that will bite:

   • PolyVec::from_bytes reduces mod q, which is what the modulus check compares against. For dk_PKE it also decodes a secret; the reduction is branch-free arithmetic, but keep it that way.
   • Known limit from the WP-2 audit still holds: the Keccak permutation spills temporaries that zeroizing the state cannot clear. It belongs to Timing checks: assembly scan and a dynamic timing test #16 and Security pass over the legacy Kyber code #18.
   • Clippy: run cargo +stable clippy --all-targets -- -D warnings as well. 1.99 flags chunks_exact with a constant size (chunks_exact_to_as_chunks).
   • Size: feat: ML-KEM K-PKE KeyGen, Encrypt and Decrypt (WP-3, first half) #29 came to 773 lines, mostly tests. This one is bigger in risk than in code, so splitting it is fine, for example input checks and the compare/select first, then the KEM functions.

   The open question about a public Rust API stays as decided: Python-only for now.
8. Zikithezikit commented on Oct 30, 2026

   

   Zikithezikit

   on Oct 30, 2026

   OwnerAuthor

   More actions

   Done in #30 (merged). Every box above is covered: keygen, keygen_from_seed, encaps and decaps in src/mlkem/kem.rs, the section 7.2 and 7.3 checks in check.rs, the branch-free select in ct.rs, OsRng with RandomBytesGeneration on failure, zeroization on the error paths, and the *_internal functions behind kem::acvp under cfg(any(test, feature = "acvp")). Round trips pass for all three sets and each input check has a negative test. The assembly evidence is in the PR.

   What is left from this issue is only what the PR description lists as believed: the barrier is best effort, armv7/i686 and a dynamic timing test belong to #16, and compiler-made stack copies of secrets belong with the Keccak-spill item in #18.
9. Zikithezikit

   closed this as completedon Oct 30, 2026