[dghgit]

Issue Link

No issue filed. These are fixes for mwcw's correctness reviews of release/0.1.3alpha at 94d4e96: sm3, utils, ascon, sha2, hex/base64, core, factory, and now (2026-11-04) aes, sha3, rng, hkdf and cipher. The branch is rebased onto 615065a, the #172 merge. It's taken a while as we keep running out of tokens!

Pick the sentence that isn't AI generated... At the moment we're half way through the review, #172 is now on release/0.1.3alpha as it's turned out it fixed a good proportion of what was raised to date. The intention is this will form the cap of release/0.1.3alpha and the head of it will become the base of release/0.1.4alpha

Summary

Each finding the reviews rated as a bug or hardening item is fixed here, with a test, except the ones listed under Deferred. The branch also adds HKDF-SM3 and SM3 stack figures, renames Ascon's length constants, and updates the HMAC truncation citation. The 2026-11-04 update adds the aes, sha3, rng, hmac/hkdf, cipher, ML-KEM, ML-DSA and CLI reports (8 to 15): the rng one found that Hash_DRBG did not match SP 800-90A and failed every CAVP vector; it now passes all 960. There is one commit per crate; a commit includes the factory or CLI wiring that belongs to it. The 2026-11-04 verification of this PR against the fifteen reviews (every claimed fix confirmed, no regression) raised one hardening item and a set of notes; all are addressed in the commits above 32b09ad, listed in the last Description section.

Description

• sm3:

  • from_suspended refuses a byte count that disagrees with the buffer offset, or that is above 2^61−1.
  • The docs give the correct message-length limit.
  • The padding at l ≡ 447 (mod 512), where the draft's prose and formula disagree, is pinned by a known answer from an independent reference checked against openssl.

• sm3, factory, cli: HKDF-SM3, the HKDF the RFC 8998 TLS 1.3 SM suites use:

  • an alias, a suspended-state length, a KDFFactory arm, an hkdf-sm3 subcommand and a bench;
  • known answers are RFC 5869 A.1–A.3's inputs through OpenSSL 3.0.13 with SM3, since there are no published HKDF-SM3 vectors.

• sm3, mem_usage_benches: bench_sm3_mem_usage and a measured per-entry-point stack table for SM3, HMAC-SM3 and HKDF-SM3.

• utils:

  • Secret's equality now needs the new unsafe trait NoPadding, which closes a soundness gap: a padded user type could have its uninitialised padding read by ==. ZeroizablePrimitive stays safe, so mlkem and mldsa keep forbid(unsafe_code).
  • is_bit_set returns FALSE for an index past the width.
  • The version-header length is a compile-time check.
  • A version component above 255 fails the build in release too.
  • Doc fixes.

• ascon:

  • AsconHash256::do_final_partial_bits now follows the Hash contract.
  • The decryptor's resume refuses held-back bytes outside the data phase.
  • A squeezer suspended before its first output resumes as a squeezer.
  • The Security Considerations section adds SP 800-232 R5–R7's limits and the clone hazard.
  • KEY_LEN/NONCE_LEN/TAG_LEN become ASCON_AEAD128_*_LEN.

• hmac, sha2, sha3, sm3: the 32-bit truncation floor is cited to FIPS 140-3 IG C.L Resolution C.4, which carries SP 800-107r1 §5.3.3 while NIST withdraws that document.

• core:

  • KeyMaterial::from_rng sets its metadata through the setters, and a zero-length draw is Zeroized.
  • Becoming Zeroized or Unknown drops the strength, which removes a reachable panic in truncate.
  • A clone taken inside a hazardous-operations window has the window closed.

• hmac: an end-to-end test of HmacKey::<SHA224>::generate with the default 256-bit RNG.

• base64:

  • Input ending one symbol into a block is TruncatedInput, where the decoder built bytes from leftover state.
  • Anything after the padding other than more padding (and whitespace, when it is skipped) is InvalidPadding, where it was silently dropped. This follows RFC 4648 §3.3 and §4.

• sha2:

  • An invalid SHA512t<T> is a compile error on the resume path too.
  • SHA-224/256 from_suspended refuses a byte count above 2^61−1.

• factory: MACFactory's 256-bit default is HMAC-SHA512, where it was the 128-bit HMAC-SHA256.

• utils, aes (report 8):

  • ct::value_barrier is public.
  • A non-MACKey salt no longer credits entropy to HKDF's output label.
  • The round-key widening in the 2- and 4-block paths folds into a multiply of a secret: a no_std harness built with -Zbuild-std shows a __mulsi3 / __muldi3 call on AVR, muls / __aeabi_lmul on Cortex-M0 and __muldi3 on RISC-V 32I. Off x86-64 and aarch64 the word now passes through the barrier first, and the harness shows no multiply and no branch on any of the five targets. On x86-64 and aarch64, where the multiply is fixed-latency, the fold is left alone: the barrier there cost 60 % of the 2-block and 190 % of the 4-block throughput.
  • expand takes the key array (the length is a compile-time assertion, as_chunks replaces the unwrap); the plane-agreement debug_assert that short-circuited on key bytes goes; GCM_NONCE_LEN is re-exported; two doc nits; the CCM key's drawing in-place one-shot, which no test reached, is tested.

• sha3, cli (report 9):

  • TupleHash*::new and ParallelHash*::new return a Result and refuse an output_len above u64::MAX / 8 (the KMAC cap), and resume holds the stored length to the same bound: past it the bit count wrapped, and at 2^61 bytes the fixed-length function silently became the XOF.
  • SHA3 refuses a resumed state in the squeezing phase, as SHAKE did.
  • The KDF entropy counter and the ParallelHash block counter saturate, and the entropy counter is width-checked on resume.
  • squeeze works in slices of at most usize::MAX / 8 bytes, so the bit count cannot wrap on 32-bit targets.
  • The two tests the review asked for: TupleHash at 264 bits against Section 5.3 written out by hand over cSHAKE (a right_encode value with a non-zero low byte), and SHAKE's partial byte with its unused bits all ones against all zeros.

• rng (report 10): Hash_DRBG matches SP 800-90A Rev. 1 and passes all 960 CAVP Hash_DRBG.rsp vectors (no-reseed and pr-false, SHA-256 and SHA-512, with and without personalization string and additional input), where it failed every one:

  • V and C are seedlen bits (440 / 888), not 512.
  • Hash_df encodes no_of_bits_to_return big-endian.
  • reseed_counter is added as an integer, not its byte-reversed bytes.
  • For SHA-256, H is added at the low end of V, not shifted by 256 bits.
  • The one known-answer test compared against the code's own output; its values are now computed independently from Section 10.3.1. The CAVP files are read from bc-test-data/crypto/cavp/drbg/, which needs them added there (the three NIST sets as shipped, except that the copies have LF line endings where the zip has CRLF; the parser trims).

• hkdf, sha2 (report 11, the HKDF items):

  • On resume, a strength label above the hash's cap (half its output), or any entropy or strength on a state that was never initialized, is refused: a pre-init state with those two bytes edited used to label the PRK of HMAC(0^64, "") as CryptographicRandom at 256-bit.
  • A salt credits entropy only when typed MACKey (SP 800-56Cr2 Section 5.1's secret salt). RFC 5869 Section 2.2's salt is "a non-secret random value", so a random public salt with an empty IKM gave a full-entropy, full-strength label on a PRK anyone who knows the salt can compute; it is now Unknown. Existing callers and the CLI type their salts MACKey, so nothing else changes.
  • The report's bug H1 (HmacKey::generate on sub-32-byte hashes) and K1 (the resumed entropy counter) were already closed on this branch.

• cipher, core-test-framework, ascon (report 12):

  • GCM refuses a resumed CTR counter below 2: GCTR starts at inc32(J0) (SP 800-38D Algorithm 4 step 3), J0 itself is the tag mask, so a state claiming 0 or 1 would emit CIPH_K(J0) as keystream.
  • CCM bounds a resumed counter index by the payload the mode can carry rather than the counter field's width, which for a 7-byte nonce is u64::MAX and overflowed on the next block.
  • One rule for the family, now checked by the AEAD suite: an empty data call is a no-op that leaves the AAD phase open. GCM and Ascon closed it; CCM did not.
  • The CMAC doc no longer claims an all-zero key is accepted.
  • Ci1, Ci3, Ci4, Ci5, Ci7 and Ci9 had landed with Key object rework: the traits lose their constructors, every mode gets a key, and workers borrow the key #172; Ci10 went with the worker constructors.

• mlkem-common, mlkem, mlkem-lowmemory (report 13):

  • The k-term dot product is reduced before the inverse NTT (M1). Each product coefficient is a sum of two Montgomery reductions in (−q, q), so the sum reaches 16q for ML-KEM-1024, and inv_ntt's first butterfly adds two of them in i16 (limit 9.84q). FIPS 203 Section 3.3 allows deferring a reduction only while the result is right for every input; the margin here was empirical (the review's search reached 8.9q on a real key), and an overflow would have made m′ wrong and the honest decapsulation return K̄. bc-java and the reference implementation reduce at this point. No known-answer output changes.
  • barrett_reduce is valid for every i16 (M2): at or below −9q the t·q product does not fit an i16 and the narrowed subtraction overflowed in debug builds. The subtraction is done in i32 and the unit test covers the whole range.
  • m′, K′, r′, K̄ and the shared secret of decapsulation, m and K of encapsulation, and d and σ of key generation are Secret buffers, and the private-key comparison encodes into Secret buffers rather than plain arrays of up to 3168 bytes (M3). The hazmat encaps_with_randomness keeps its by-value contract.
  • The seed error text names KeyType::CryptographicRandom, the variant the check accepts (M5).
  • M4 and M6 to M13 were notes; nothing changed for them.

• core, mldsa-common, mldsa, mldsa-lowmemory (report 14):

  • The low-memory signer's iteration-cap return clears the caller's buffer, which held a rejected candidate's c̃ and z (M1; FIPS 204 Section 6.2: "no other output, destroying the results of the unsuccessful signing attempts"). The cap is reachable only at about 2^−315.
  • ρ″ in both signers and ρ′ in the full key generation are Secret, so the error paths wipe them too; the full crate used a plain fill on the success path only and the low-memory crate never wiped ρ″ (M2). The zeroization docs say which polynomial temporaries stay plain.
  • check_norm OR-accumulates over all 256 coefficients and make_hint is a mask expression, removing the two secret-dependent branches inside the rejection loop (M3). FIPS 204 asks for neither and the reference implementations branch; a new test compares both with the comparisons they replace over every input.
  • SignatureError gains RejectionLimitExceeded and PreHashTooWeak in place of GenericError strings, ConsistencyCheckFailed loses its empty parentheses, the seed error names a KeyType that exists, the unit-error decoders return Option, and the key, worker and crate docs say signing can fail at the cap (M4).
  • Twin alignment (M5): the low-memory public key and the full crate's key-pair check compare in constant time, the low-memory tr() returns a reference as the full crate's does, and both crates re-export MLDSA_SEED_LEN. compute_z_component no longer returns a Result with no error path, and the signer doc's duplicated opening is gone (M6).
  • M7: SHAKE128 and SHAKE256 are now pre-hashes. The sha3 crate gives the SHAKE types HashAlgParams with the fixed digests of RFC 8702 Section 3.1 ("the output length of SHAKE128 or SHAKE256 as the message digest MUST be 32 or 64 bytes, respectively"), which is FIPS 204 Algorithm 4's SHAKE128(M, 256) under id-shake128. SHAKE128's 128-bit strength fits ML-DSA-44 only, SHAKE256 fits all three; a test in each ML-DSA crate checks the signature against Algorithm 4's M′ built by hand with the OID bytes of line 18, through the external-mu path. The module doc no longer says "any approved hash"; the strength check stays the only gate, pending the workspace FIPS-mode design (PR Simple ciphers: stream + symmetric cipher unification off the release branch, plus SHA-512/t for any t #133). M8 is documented behaviour and unchanged.

• cli (report 15), five commits:

  • Bugs: mlkem1024 keygen called the ML-KEM-512 keygen, so it emitted a 1632-byte key no mlkem1024 command accepted (L1); the ML-KEM-768 public-key parser used the 512 length (L2). L3 (base64 after the padding) was already closed by the base64 fix on this branch.
  • The six ML-DSA and three ML-KEM command bodies and their twelve key parsers are one generic body each over a table of the parameter set's key types, lengths and functions, so a length or a function can no longer be right for two sets and wrong for the third (L22); the bit-count and name dispatches with panicking wildcard arms are enums.
  • One input rule for every subcommand (L11, L12, L13): inline values are hex; files, and the stdin a command decodes, are raw bytes, or hex text under the new global --hex-input. Nothing is guessed from a file's contents, so a raw key whose bytes happen to be hex digits is no longer silently decoded into a different key. kmac* -k is the key file as for hmac-*, ascon-aead128 --ad is --aad with an --aad-file, ascon-cxof128 --customization is the string and --customization-hex the bytes, and the SP 800-185 commands gain --customization-hex. The conventions are written up on the helpers module.
  • Keys, seeds, private keys, salts and IKM are read into a zeroized KeyMaterial buffer, never a Vec (L20). A stdin read error, a missing or non-hex key, salt, IKM or verify value, a bad seed, a context over 255 bytes and an unwritable --ctfile report with exit 255 rather than a panic (L5 to L9). XOF output is squeezed to stdout in 1 KiB pieces; the fixed-length KMAC, TupleHash and ParallelHash outputs are capped at 256 MiB with a pointer to the XOF forms (L10). MAC keys take any length up to 16 KiB, so RFC 4231's long-key cases run (L14). Every failure line starts with Error: (L15); hkdf -x ends in a newline (L16); the help-text errors are fixed (L18); #![forbid(unsafe_code)] and a clippy-clean package (L19).
  • Parity with the library (L17, L21): hmac-sha224, hmac-sha384, hmac-sha3-*, cshake*, kmacxof*, tuplehashxof*, parallelhashxof*, aes*-cmac, aes*-gmac, --hash sha256|sha512|shake128|shake256 on hash-mldsa*, --deterministic, compute-mu/sign-mu/verify-mu, and rng --hash and the hazardous rng --seed-file. Not added: the low-memory twins (same outputs) and SHA512t at other t (a const generic).
  • Tests: the reviewer's eight scripts (sha2, sha3, sm3, hmac KATs, encoders, mlkem, mldsa, rng), read and adapted to the input rule, plus their extensions for the new subcommands and a CMAC/GMAC script against the ACVP files; every known answer names its vector file. The three macOS failures of the existing suite (GNU timeout, BSD wc padding) are fixed. 20 files, 281 tests, all passing.

• Doc corrections from reports 9 to 11 (sha3 S-N2/S-N3, hmac H5, hkdf K8, rng R9/R10/R16), one commit per crate: the SHA-3 KDF impl is described as the plain hash it is rather than SP 800-56C's one-step KDF, and the KMAC rows of its memory table match the bench; the HMAC instantiation table lists all eleven aliases and Display prints the HMAC name; HKDF reports credited entropy in bytes, quotes SP 800-56Cr2 Section 5.1's own sentence on RFC 5869, and states the right reason for having no Drop; the DRBG trait docs drop the InsufficientSeedEntropy check that was never made, quote Section 8.6.7 for the nonce, and state the reseed policy, the unsupported prediction resistance and the panicking OS-seeded constructors; the Table 2 limit constants are named for the bytes they hold.

• From the 2026-11-04 verification of this PR (every claimed fix confirmed present and doing what the finding asked, two partials as stated above, no regression; its ids are P190-<crate>-<n>), one commit per crate:

  • ascon P190-ascon-1 (hardening): do_decrypt_inplace now ends the AAD phase on its first non-empty call, as do_decrypt_out does, so the two decrypt entry points run one phase machine; a test drives both with every byte held back.
  • aes P190-aes-1/2/3: the cross-target assembly check is in the tree and in CI: dev_scripts/aes_ct_harness (the two splat bodies with and without the barrier), dev_scripts/check_aes_ct_asm.sh (nightly, -Zbuild-std=core, thumbv6m and riscv32i; the barriered bodies must show no multiply, call or branch, the plain ones must show the multiply) and aes-ct-asm.yml. The splat comment records that the architecture-only gate makes 32-bit Arm, x86 and wasm32 pay the barrier. The dead allow(unused_imports) is gone.
  • cipher P190-cipher-1/2, core P190-cipher-3: the CCM counter-index test adds the q = 8 case; GCM's resumed-counter rule reads the counter through a new CtrKeyStream::counter_from_state; the core do_update_aad docs carry the empty-call rule on both sides.
  • mlkem P190-mlkem-2: a unit test that dot_product returns reduced coefficients, which pins the reduction M1 restored; it showed poly_reduce's doc giving [0, q) for a reduction into [0, q], fixed in mlkem-common.
  • Docs and comments: utils P190-utils-1 (the NoPadding contract is "every byte initialized"), core P190-core-1, sha3 P190-sha3-2, sm3 P190-sm3-2, hkdf P190-hkdf-1, base64 P190-base64-1 (unreachable!), rng P190-rng-1/2 (the nonce sentence cites Section 8.6.7's 3/2-strength alternative), mldsa-common P190-mldsa-2, cli P190-cli-3 and P190-base64-2 (why the CLI repeats the padding check for later chunks).
  • Recorded, no change: P190-core-2 (moves with C10), P190-sha2-1, P190-sha3-1 (C15), P190-hmac-1, P190-hkdf-2, P190-factory-1 (F4), P190-cli-1/2 (probe-script aging; an allowed ParallelHash block size), P190-mldsa-1 and P190-mlkem-1 (the breaking list below), P190-mldsa-3 (deferred below).

Deferred, with reasons

• utils U2, barriers in the Condition constructors: this needs a decision on losing const fn and a cross-target asm check.
• ascon A6, a shared nonce helper: the default-DRBG do_*_init sites it would share went with Key object rework: the traits lose their constructors, every mode gets a key, and workers borrow the key #172.
• ascon A2's per-instance byte counter: it would change the frozen suspended-state format, so only the docs change here.
• The remaining notes: ascon A4, A10; sm3/sha2 HKDF and name-coverage gaps; factory F3–F14; the review's workspace-wide findings.
• aes A4 (three naming grammars for the AES family) is a decision to take before the factory grows AES; A10 is Create and apply a pattern for #[must_use] #74.
• sha3 S-N1 to S-N5 (output length 0, which the spec allows; docs; API observations).
• mldsa M7's "approved hash" half: the pre-hash gate is strength only, so SM3 is still accepted for HashML-DSA-44; FIPS mode is Simple ciphers: stream + symmetric cipher unification off the release branch, plus SHA-512/t for any t #133's design, and hash_mldsa.rs says the choice is the caller's.
• rng R5 to R8 (prediction resistance is todo!(), the empty-nonce check, the pre-check allocation in generate, V copies as plain arrays) and the notes R9 to R17.
• hmac H3 (keygen_from_rng re-typing outside a hazardous window) and the hmac/hkdf notes K4 to K10, H4 to H7. hmac H2 (resume skipping the key policy) is not deferred: Key object rework: the traits lose their constructors, every mode gets a key, and workers borrow the key #172 closed it, since SuspendableKeyed::Key = HmacKey and the bare key constructor is private.
• cipher notes Ci12 to Ci17 (doc claims, decrypt-side constructor grammar, CFB/CFB8 keystream scratch zeroization, unchecked + TAG_LEN in _out_len, the two MACs' key retagging, the F.5 CTR vectors).

Scope and Risk

• Packages: utils, core, core-test-framework, ascon, sm3, sha2, sha3, hmac, hkdf, base64, aes, cipher, rng, factory, cli, mem_usage_benches.
• Breaking changes, which the alpha status allows:
  • NoPadding is required for Secret<T>: PartialEq.
  • Ascon's length constants are renamed.
  • Base64Error has two new variants.
  • MACFactory's 256-bit default is a different MAC.
  • base64 now refuses input it used to accept.
  • TupleHash*::new and ParallelHash*::new return a Result.
  • Every Hash_DRBG output for a given seed changes (it is now the standard's).
  • ct::value_barrier is public.
  • A non-MACKey salt no longer credits entropy to HKDF's output label.
  • SignatureError::ConsistencyCheckFailed is a unit variant (a match on ConsistencyCheckFailed() stops compiling), and SignatureError gains RejectionLimitExceeded and PreHashTooWeak.
  • bouncycastle_mldsa_lowmemory::MLDSAPrivateKeyTrait::tr returns &[u8; 64] rather than [u8; 64].
  • bouncycastle_mlkem_common::polynomial::Polynomial::from_msg takes &[u8; 32] (a #[doc(hidden)] item, reachable all the same).
  • HKDF_SM3_NAME moved from sm3::hmac to sm3::hkdf.
• Regression likelihood: low. No known-answer suite changed, and each fix has a test that fails without it.
• Verified:
  • Every commit builds.
  • The tip passes all 182 workspace test suites and the CLI shell tests, and fmt is clean.
  • cargo-mutants ran on each changed crate before the rebase onto Key object rework: the traits lose their constructors, every mode gets a key, and workers borrow the key #172. The numbers are in each commit message, and every miss is either an equivalent mutant or a gap the reviews already list.
  • The CLI shell suite (cli/tests/test_all.sh): 20 files, all passing. cargo-mutants is not meaningful for the cli package, which has no Rust tests.
  • 2026-11-04: the tip passes the whole workspace; cargo-mutants on apollo, scoped to the changed files: aes 278 mutants (182 caught, 81 unviable, 15 missed: the twelve |/^ equivalents the review lists plus the three SymmetricCipherKey fast-path arms, whose removal changes no output); sha3 827 (654 caught, 152 unviable, 8 timeouts in the squeeze and ParallelHash loops, 13 missed: the review's seven inherent TupleHash one-shot wrappers, five bit-mixing equivalents, and the squeeze slice size, larger than any buffer either way); rng 190 (re-run after the two test additions for the reseed counter's increment and add_seed_keymaterial: 142 caught, 27 unviable, 1 timeout from the default/new_from_os recursion, 20 missed: the byte-valued Table 2 limits that no test can reach at 4 GiB and the / 8 on those constants); hkdf 160 (116 caught, 44 unviable, none missed). ascon 172 (145 caught, 21 unviable, 5 missed: pos % 8 to pos + 8 in the three state-byte helpers, where a release build masks the shift count to six bits, and | to ^ after the byte is masked out); cipher 773 (486 caught, 185 unviable, 1 timeout, 101 missed: nearly all in the streaming CCM worker, tag_block, impl_mul64 and GcmKeyState::eq, whose known-answer tests live in the aes crate and are out of a crate-scoped run's reach, so a re-run with the aes tests included is queued on apollo, as are the three ML-KEM runs for report 13 and the three ML-DSA runs for report 14; numbers to follow).

Assisted-by: Claude:claude-opus-5-5

🤖 Generated with Claude Code

[dghgit]

Squash-merged onto release/0.1.3alpha as 029a17b (tree identical to this branch's head c3c5e9d, plus the release-notes commit 9068290 that was already on the branch). Verified on the squashed tree before committing: fmt clean, every target builds, 1282 workspace tests pass, rustdoc 0 warnings.

[dghgit]

Merged by hand as squash commit.