Part 7: Stream cipher traits, CFB as a stream cipher, and new CFB8 and CTR modes

.gitignore

@@ -5,3 +5,13 @@ mutants.out*/
 
 .idea/
 .vscode/
+
+# Claude Code: ignore personal/local state, but share team tooling
+# (skills, slash commands, subagents, and project settings.json).
+.claude/*
+!.claude/settings.json
+!.claude/skills/
+!.claude/commands/
+!.claude/agents/
+.claude/settings.local.json
+.claude 2/

CLAUDE.md

@@ -9,12 +9,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Common commands
 
-Build / test / bench / docs run against the cargo workspace from the repo root:
+Build / test / bench / docs run against the cargo workspace from the repo root. `--workspace` is
+not optional: the root manifest is both the workspace and the umbrella `bouncycastle` package, so a
+bare `cargo build` builds only that package (no `cli`, no benches) and a bare `cargo test` runs
+**zero** tests and still exits 0, because the umbrella crate has none of its own.
 
 ```
-cargo build                     # whole workspace incl. `bc-rust` CLI binary
+cargo build --workspace         # whole workspace incl. `bc-rust` CLI binary
 cargo build -p bouncycastle-sha3   # one sub-crate
-cargo test                      # all tests
+cargo test --workspace          # all tests
 cargo test -p bouncycastle-mlkem   # tests for one crate
 cargo test -p bouncycastle-mlkem ml_kem_tests   # one integration test file
 cargo bench --all               # all criterion benches
@@ -30,19 +33,25 @@ Quality / mutation testing:
 cargo mutants                              # config in .cargo/mutants.toml (output: custom_mutants_output/)
 ```
 
-Stack-memory benches are separate binaries under `mem_usage_benches/`:
+Stack-memory benches are separate binaries under `mem_usage_benches/src/`, each declared as a
+`[[bin]]` in that crate's `Cargo.toml`:
 
 ```
 cargo run --release -p mem_usage_benches --bin bench_mlkem_mem_usage
 cargo run --release -p mem_usage_benches --bin bench_mldsa_mem_usage
 ```
 
+`mem_usage_benches/src/lib.rs` makes those sources modules of a lib target as well, so their `//!`
+headers are rustdoc'd and any indented or fenced block in them is compiled as a Rust doctest. The
+valgrind and `ms_print` recipes there are fenced as ```` ```text ```` for that reason — keep it that
+way when adding a harness, or `cargo test --workspace` fails to compile them.
+
 ## Workspace architecture
 
 The workspace has three top-level kinds of member:
 
-1. `crypto/*` — one sub-crate per primitive (`sha2`, `sha3`, `hmac`, `hkdf`, `mlkem`, `mlkem_lowmemory`, `mldsa`, `mldsa_lowmemory`, `rng`, `hex`, `base64`, `utils`) plus the spine crates `core`, `core-test-framework`, and `factory`. Each crate is published as `bouncycastle-<name>` and depended on internally via the `workspace.dependencies` table in the root `Cargo.toml`.
-2. `src/` — the umbrella `bouncycastle` crate, which is just `pub use` re-exports of every sub-crate (e.g. `bouncycastle::sha3`, `bouncycastle::mlkem`). It exists so downstream users can pull the whole library with one dependency; it has no code of its own.
+1. `crypto/*` — one sub-crate per primitive (`sha2`, `sha3`, `sm3`, `hmac`, `hkdf`, `mlkem`, `mlkem_lowmemory`, `mldsa`, `mldsa_lowmemory`, `rng`, `hex`, `base64`, `utils`) plus the spine crates `core`, `core-test-framework`, and `factory`. Each crate is published as `bouncycastle-<name>` and depended on internally via the `workspace.dependencies` table in the root `Cargo.toml`.
+2. `src/` — the umbrella `bouncycastle` crate, which is just `pub use` re-exports of every sub-crate (e.g. `bouncycastle::sha3`, `bouncycastle::sm3`, `bouncycastle::mlkem`). It exists so downstream users can pull the whole library with one dependency; it has no code of its own.
 3. `cli/` — the `bc-rust` binary built on top of `bouncycastle`, exposing every primitive as a streaming stdin→stdout subcommand using `clap`.
 4. `mem_usage_benches/` — stand-alone binary crates that measure peak stack usage of algorithms (cannot be done via criterion).
 
@@ -113,10 +122,11 @@ Rules when working from the downloaded copy:
 ## Notes on testing
 
 - `cargo mutants` is expected to be run on each crate; surviving mutants must be investigated but not all need to die (e.g. XOR/OR equivalences in crypto code are acceptable). Config lives in `.cargo/mutants.toml` (output dir `custom_mutants_output/`).
-- Behaviour-critical private functions can use in-file `#[cfg(test)] mod tests` blocks when they can't be exercised from outside the crate.
+- Integration tests in `tests/` are preferred over in-file `#[cfg(test)] mod tests` blocks — see "Unit tests vs integration tests" in QUALITY_AND_STYLE.md for the reasoning and the exceptions. A unit test is justified for high-risk code that has known-answer values and cannot be reached through the public API; when you write one, all of its helpers go inside that `mod tests`.
+- A property that can be asserted at compile time (`const _: () = assert!(...)`) stays a compile-time assertion even when a test also covers it: `cargo mutants` cannot see a const assertion fail, so pair the two rather than trading the guarantee for the coverage.
 - For traits in `core`, the canonical tests live in `core-test-framework` and are invoked from each implementor's integration tests — don't duplicate them per-implementation.
 - The per-width `impl Condition<W>` blocks in `crypto/utils/src/ct.rs` (and their test modules) are deliberately duplicated rather than macro-generated: `cargo mutants` cannot see into `macro_rules!` bodies, so a macro would hide the mask identities from mutation testing. Do not fold them back into a macro. Any change to one width in a group (i64/i32, u64/u32) must be applied to every width in that group.
 
 ## CI
 
-The only workflow is `.github/workflows/publish_doc_benches_to_ghpages.yaml`: on every PR it builds rustdoc and runs `quality_stats.sh`; on `main` it additionally runs `cargo bench --all` and publishes docs, code stats, and benchmark results to GitHub Pages (`https://bcgit.github.io/bc-rust/`). There is no separate CI test/lint job — local `cargo test` is the gate.
+The only workflow is `.github/workflows/publish_doc_benches_to_ghpages.yaml`: on every PR it builds rustdoc and runs `quality_stats.sh`; on `main` it additionally runs `cargo bench --all` and publishes docs, code stats, and benchmark results to GitHub Pages (`https://bcgit.github.io/bc-rust/`). There is no separate CI test/lint job — local `cargo test --workspace` is the gate, and nothing but a developer running it stands between a broken test and `main`.

Cargo.toml

@@ -9,7 +9,9 @@ version = "0.1.3"
 
 # *** Internal Dependencies ***
 bouncycastle = { path = "./" }
+bouncycastle-aes-lowmemory = { path = "./crypto/aes-lowmemory" }
 bouncycastle-base64 = { path = "./crypto/base64" }
+bouncycastle-modes = { path = "./crypto/modes" }
 bouncycastle-core = { path = "crypto/core" }
 bouncycastle-core-test-framework = { path = "./crypto/core-test-framework" }
 bouncycastle-factory = { path = "./crypto/factory" }
@@ -20,9 +22,11 @@ bouncycastle-mlkem = { path = "./crypto/mlkem" }
 bouncycastle-mlkem-lowmemory = { path = "./crypto/mlkem-lowmemory" }
 bouncycastle-mldsa = { path = "./crypto/mldsa" }
 bouncycastle-mldsa-lowmemory = { path = "./crypto/mldsa-lowmemory" }
+bouncycastle-padding = { path = "./crypto/padding" }
 bouncycastle-rng = { path = "./crypto/rng" }
 bouncycastle-sha2 = { path = "./crypto/sha2" }
 bouncycastle-sha3 = { path = "./crypto/sha3" }
+bouncycastle-sm3 = { path = "./crypto/sm3" }
 bouncycastle-utils = { path = "./crypto/utils" }
 
 
@@ -41,6 +45,7 @@ version.workspace = true
 edition.workspace = true
 
 [dependencies]
+bouncycastle-aes-lowmemory.workspace = true
 bouncycastle-base64.workspace = true
 bouncycastle-core.workspace = true
 bouncycastle-factory.workspace = true
@@ -51,6 +56,9 @@ bouncycastle-mldsa.workspace = true
 bouncycastle-mldsa-lowmemory.workspace = true
 bouncycastle-mlkem.workspace = true
 bouncycastle-mlkem-lowmemory.workspace = true
+bouncycastle-modes.workspace = true
+bouncycastle-padding.workspace = true
 bouncycastle-rng.workspace = true
 bouncycastle-sha2.workspace = true
 bouncycastle-sha3.workspace = true
+bouncycastle-sm3.workspace = true

QUALITY_AND_STYLE.md

@@ -128,6 +128,36 @@ Note that rust macros tend not to play well with a lot of dev tooling for compil
 `cargo mutants`, which is a good reason to avoid macros in core algorithm or data processing code. Macros can be used
 more freely within test code.
 
+## Unit tests vs integration tests
+
+Unit tests are test code (and supporting helper functions) embedded in src/**.rs files. They have access to
+crate-private or module-private functions and constants.
+
+Integration tests are test code (and supporting helper functions) in tests/**.rs files. They test the crate's code from
+the outside -- ie through its public APIs -- since tests/ is a separate crate from src/.
+
+In general, integration tests are preferred over unit tests. This is for a number of reasons:
+
+* To reduce reviewer burden; reviewers will typically focus more effort on the src/ than the tests/, so we want to keep
+  src/ as short as is reasonable.
+* Usually it is easier to determine what is the correct behaviour at the public API level. For example, this is the
+  level at which we typically have KATs and test vectors.
+* Tools like cargo mutants are very helpful at detecting branches that are not exercisable via the public APIs, which
+  often is an indicator that the branch isn't doing what you think it's doing, or is simply not useful and can be
+  deleted. Unit tests that bypass the public APIs to pin these sorts of branches obscure the fact that this code is
+  unreachable.
+
+Unit tests are reasonable to include in the following cases:
+
+* There is high-risk code (usually meaning that it is complex code whose behaviour is not obvious from inspection) where
+  unit tests help to document the behaviour and protect against accidental breakage via a benign-looking change.
+* AND where known answer tests are available.
+* AND where this behaviour cannot be tested from integration tests.
+
+When writing unit tests, they should be contained with an `mod tests` at the bottom of the file, and ALL helper
+functions that support the unit tests must be contained within that module. The intention is to clearly signal to a code
+reviewer what is test code vs functional code.
+
 # Docs
 
 ## Usage Examples