deps(rust): bump ml-kem 0.2 → 0.3.0 (with reader.rs API migration)#28
Merged
Conversation
API migration to ml-kem 0.3:
- `KemCore` removed → use `kem::Kem` (we no longer reference it
directly; the per-parameter type aliases below capture it).
- `EncodedSizeUser::from_bytes` removed → `ExpandedKeyEncoding::
from_expanded_bytes` is the replacement, now fallible
(returns Result<Self, InvalidKey> with FIPS 203 hash validation
on the expanded key, per RustCrypto/KEMs #207).
- `Encoded<T>` replaced by `Array<u8, T::EncodedSize>` from the
re-exported `hybrid_array` (`ml_kem::array`).
- Per-parameter aliases moved into `ml_kem::ml_kem_768` — use
`MlKem768Ct` / `MlKem768Dk` (renamed locally for brevity since
the param is fixed at the import site).
Interop note: the 2400-byte FIPS 203 expanded decapsulation key
layout produced by BouncyCastle's `MLKemPrivateKeyParameters.
GetEncoded()` is preserved bit-for-bit in 0.3, so all existing
test vectors continue to decrypt. The 1088-byte ciphertext wire
format is unchanged.
Notable: `ExpandedKeyEncoding` is marked deprecated in 0.3.0; the
crate authors recommend `DecapsulationKey::from_seed` (64-byte
d||z) instead. We can't switch because BC does not expose the
seed via `GetEncoded()`, so we accept the deprecation warning.
The pqf-reader bump in this branch made cargo unify the transitive
`kem` crate across both ml-kem versions, which broke ml-kem 0.2's
compile (its source was written against the older `kem` trait shape).
Both crates must move together.
Writer-side changes:
- `Encapsulate` trait moved to crate root and renamed its required
method to `encapsulate_with_rng(rng)` (the old `encapsulate(rng)`
was a single method; now the trait splits into a required RNG
method and a no-arg convenience). Return is now an infallible
tuple instead of Result.
- `EncodedSizeUser::from_bytes` is gone; construct `EncapsulationKey`
via `TryKeyInit::new_from_slice(bytes) -> Result<_, InvalidKey>`.
- Per-parameter aliases live under `ml_kem::ml_kem_768`.
- The "deterministic" feature flag was renamed to "hazmat" and the
`EncapsulateDeterministic` trait promoted to an inherent method
on `EncapsulationKey` (same name, same shape).
- `MlKem768Params` is gone; `EncapsulationKey<MlKem768>` (the crate
root struct parameterized by Kem) is the new form.
The X-Wing draft KAT in tests/xwing_draft_kat.rs replays the published
IETF vectors via deterministic encap; that's the load-bearing test
for FIPS 203 bit-compatibility across this version bump.
In ml-kem 0.2 `DecapsulationKey::decapsulate` returned `Result<SharedSecret, ()>` even though the `()` error never fired in practice — FIPS 203 implicit rejection always returns a pseudorandom secret, not an error. 0.3 made the inherent method honest and returns `Array<u8, U32>` directly. Drop the Result match. The constant-time recipient-trial loop still iterates every recipient regardless of match, and the AEAD tag below remains the sole signal of a real match.
ml-kem 0.3's `encapsulate_with_rng` requires a `CryptoRng` from the newer rand_core it re-exports; the writer uses rand 0.8 everywhere else (x25519-dalek's `random_from_rng`, AEAD nonce filling). Mixing versions inside one fn would force a deep import chain. Switch the encap call to `encapsulate_deterministic` (gated by the "hazmat" feature, already enabled): generate 32 CSPRNG bytes via rand 0.8 OsRng and pass them in. Cryptographically equivalent to the RNG-based variant since the bytes come from the same OS CSPRNG.
Same shape as decapsulate — the 0.2 Result return was a vestigial () error type that never fired. 0.3 honestly returns the `(Ciphertext, SharedKey)` tuple directly.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
`pqf-writer` stays on ml-kem 0.2 — the two versions coexist in the workspace because the writer/reader exchange wire bytes, not ml-kem types. A future PR can bump the writer.
Interop safety
What CI must confirm (in order of importance)