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

@@ -41,8 +41,8 @@ cargo run --release -p mem_usage_benches --bin bench_mldsa_mem_usage
 
 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).
 

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

cli/src/aes_cbc_cmd.rs

@@ -0,0 +1,68 @@
+//! AES-CBC encryption and decryption, streaming stdin to stdout.
+//!
+//! Only the mode wiring lives here: the IV convention, key loading, stdin framing and
+//! block-alignment enforcement are all in [`crate::block_mode_cmd`], shared with the `aes*-cfb` and
+//! `aes*-ecb` commands. See that module for the command-line contract.
+//!
+//! CBC (NIST SP 800-38A Sec 6.2) provides confidentiality only. It does not detect tampering, and
+//! neither the ciphertext nor the IV is authenticated -- a flipped ciphertext bit flips the same bit
+//! of the *next* block's plaintext (Appendix D). Do not decrypt data you have not authenticated
+//! separately.
+
+use crate::block_mode_cmd::{BLOCK_LEN, BlockModeAction, decrypt_stream, encrypt_stream, load_key};
+use bouncycastle::aes_lowmemory::{Aes128, Aes192, Aes256};
+use bouncycastle::core::key_material::KeyMaterial;
+use bouncycastle::core::traits::ElectronicCodeBook;
+use bouncycastle::modes::{Cbc, Decrypting, Encrypting};
+
+/// Names the mode in error messages.
+const MODE: &str = "CBC";
+
+pub(crate) fn aes128_cbc_cmd(
+    action: &BlockModeAction,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<Aes128, 16>(action, &load_key::<16>(key, key_file, "AES-128"), output_hex);
+}
+
+pub(crate) fn aes192_cbc_cmd(
+    action: &BlockModeAction,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<Aes192, 24>(action, &load_key::<24>(key, key_file, "AES-192"), output_hex);
+}
+
+pub(crate) fn aes256_cbc_cmd(
+    action: &BlockModeAction,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<Aes256, 32>(action, &load_key::<32>(key, key_file, "AES-256"), output_hex);
+}
+
+/// Dispatches to the shared streaming loops with `Cbc` filled in as the mode.
+fn run<P, const KEY_LEN: usize>(
+    action: &BlockModeAction,
+    key: &KeyMaterial<KEY_LEN>,
+    output_hex: bool,
+) where
+    P: ElectronicCodeBook<KEY_LEN, BLOCK_LEN>,
+{
+    match action {
+        BlockModeAction::Encrypt => {
+            encrypt_stream::<Cbc<P, Encrypting, KEY_LEN, BLOCK_LEN>, KEY_LEN, BLOCK_LEN>(
+                key, output_hex, MODE,
+            )
+        }
+        BlockModeAction::Decrypt => {
+            decrypt_stream::<Cbc<P, Decrypting, KEY_LEN, BLOCK_LEN>, KEY_LEN, BLOCK_LEN>(
+                key, output_hex, MODE,
+            )
+        }
+    }
+}

cli/src/aes_cfb8_cmd.rs

@@ -0,0 +1,76 @@
+//! AES-CFB8 encryption and decryption, streaming stdin to stdout.
+//!
+//! Only the mode wiring lives here: the IV convention, key loading and stdin framing are in
+//! [`crate::stream_mode_cmd`] (and [`crate::block_mode_cmd`] for the key loader), shared with the
+//! `aes*-cfb` commands. See those modules for the command-line contract.
+//!
+//! # Which CFB
+//!
+//! These commands are **CFB8**: the segment size is one byte (`s = 8` in NIST SP 800-38A Sec 6.3).
+//! That is a different, non-interoperable mode from the CFB128 of `aes*-cfb`, not a variant of it:
+//! the two ciphertexts agree on their first byte and differ everywhere after it. It also costs a
+//! full AES call per byte of data, sixteen times the work of `aes*-cfb`, so prefer `aes*-cfb`
+//! unless a byte-granular self-synchronising stream is required or the format demands CFB8.
+//!
+//! # Any length
+//!
+//! CFB8's segment is a single byte, so these commands accept input of any length, pad nothing, and
+//! emit a ciphertext exactly as long as the plaintext.
+//!
+//! # Warning
+//!
+//! CFB8 provides confidentiality only. It does not detect tampering, and neither the ciphertext nor
+//! the IV is authenticated. Appendix D, Table D.2 gives "SBE in the decryption of Cj" plus random
+//! errors in the next `b/s` segments: flipping a ciphertext bit flips the *same* bit of the *same*
+//! plaintext byte, corrupts the following 16 bytes, and then decryption resynchronises. Do not
+//! decrypt data you have not authenticated separately.
+
+use crate::block_mode_cmd::{BLOCK_LEN, BlockModeAction, load_key};
+use crate::stream_mode_cmd::run_stream_mode;
+use bouncycastle::aes_lowmemory::{Aes128, Aes192, Aes256};
+use bouncycastle::core::key_material::KeyMaterial;
+use bouncycastle::core::traits::ElectronicCodeBook;
+use bouncycastle::modes::{Cfb8, Decrypting, Encrypting};
+
+pub(crate) fn aes128_cfb8_cmd(
+    action: &BlockModeAction,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<Aes128, 16>(action, &load_key::<16>(key, key_file, "AES-128"), output_hex);
+}
+
+pub(crate) fn aes192_cfb8_cmd(
+    action: &BlockModeAction,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<Aes192, 24>(action, &load_key::<24>(key, key_file, "AES-192"), output_hex);
+}
+
+pub(crate) fn aes256_cfb8_cmd(
+    action: &BlockModeAction,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<Aes256, 32>(action, &load_key::<32>(key, key_file, "AES-256"), output_hex);
+}
+
+/// Dispatches to the shared streaming loops with `Cfb8` filled in as the mode.
+fn run<P, const KEY_LEN: usize>(
+    action: &BlockModeAction,
+    key: &KeyMaterial<KEY_LEN>,
+    output_hex: bool,
+) where
+    P: ElectronicCodeBook<KEY_LEN, BLOCK_LEN>,
+{
+    run_stream_mode::<
+        Cfb8<P, Encrypting, KEY_LEN, BLOCK_LEN>,
+        Cfb8<P, Decrypting, KEY_LEN, BLOCK_LEN>,
+        KEY_LEN,
+        BLOCK_LEN,
+    >(action, key, output_hex)
+}

cli/src/aes_cfb_cmd.rs

@@ -0,0 +1,77 @@
+//! AES-CFB128 encryption and decryption, streaming stdin to stdout.
+//!
+//! Only the mode wiring lives here: the IV convention, key loading and stdin framing are in
+//! [`crate::stream_mode_cmd`] (and [`crate::block_mode_cmd`] for the key loader), shared with the
+//! `aes*-cfb8` commands. See those modules for the command-line contract.
+//!
+//! # Which CFB
+//!
+//! These commands are **CFB128**: the segment size is the full 16-byte block (`s = b` in NIST
+//! SP 800-38A Sec 6.3). SP 800-38A also defines `s = 8`, which is a different, non-interoperable
+//! mode -- if you need CFB8, the `aes*-cfb8` commands are it -- and `s = 1`, which this library does
+//! not provide.
+//!
+//! # Any length
+//!
+//! CFB is a stream cipher, so unlike `aes*-cbc` and `aes*-ecb` these commands accept input of any
+//! length and pad nothing; the ciphertext is exactly as long as the plaintext. For a message that
+//! is not a whole number of blocks the last partial block is a short final segment, which is what
+//! every streaming CFB128 implementation does; see the `bouncycastle_modes::Cfb` docs.
+//!
+//! # Warning
+//!
+//! CFB provides confidentiality only. It does not detect tampering, and neither the ciphertext nor
+//! the IV is authenticated. CFB's malleability is more directly exploitable than CBC's: Appendix D,
+//! Table D.2 gives "SBE in the decryption of Cj" -- flipping a ciphertext bit flips the *same* bit
+//! of the plaintext in the *same* block, so an attacker edits the block they aimed at, at the cost
+//! of randomising the next one. Do not decrypt data you have not authenticated separately.
+
+use crate::block_mode_cmd::{BLOCK_LEN, BlockModeAction, load_key};
+use crate::stream_mode_cmd::run_stream_mode;
+use bouncycastle::aes_lowmemory::{Aes128, Aes192, Aes256};
+use bouncycastle::core::key_material::KeyMaterial;
+use bouncycastle::core::traits::ElectronicCodeBook;
+use bouncycastle::modes::{Cfb, Decrypting, Encrypting};
+
+pub(crate) fn aes128_cfb_cmd(
+    action: &BlockModeAction,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<Aes128, 16>(action, &load_key::<16>(key, key_file, "AES-128"), output_hex);
+}
+
+pub(crate) fn aes192_cfb_cmd(
+    action: &BlockModeAction,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<Aes192, 24>(action, &load_key::<24>(key, key_file, "AES-192"), output_hex);
+}
+
+pub(crate) fn aes256_cfb_cmd(
+    action: &BlockModeAction,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<Aes256, 32>(action, &load_key::<32>(key, key_file, "AES-256"), output_hex);
+}
+
+/// Dispatches to the shared streaming loops with `Cfb` filled in as the mode.
+fn run<P, const KEY_LEN: usize>(
+    action: &BlockModeAction,
+    key: &KeyMaterial<KEY_LEN>,
+    output_hex: bool,
+) where
+    P: ElectronicCodeBook<KEY_LEN, BLOCK_LEN>,
+{
+    run_stream_mode::<
+        Cfb<P, Encrypting, KEY_LEN, BLOCK_LEN>,
+        Cfb<P, Decrypting, KEY_LEN, BLOCK_LEN>,
+        KEY_LEN,
+        BLOCK_LEN,
+    >(action, key, output_hex)
+}

cli/src/aes_ctr_cmd.rs

@@ -0,0 +1,84 @@
+//! AES-CTR encryption and decryption, streaming stdin to stdout.
+//!
+//! Only the mode wiring lives here: the nonce convention, key loading and stdin framing are in
+//! [`crate::stream_mode_cmd`] (and [`crate::block_mode_cmd`] for the key loader), shared with the
+//! `aes*-cfb` and `aes*-cfb8` commands. See those modules for the command-line contract.
+//!
+//! # The nonce is 12 bytes and the counter is 4
+//!
+//! NIST SP 800-38A Sec 6.5 builds CTR on a sequence of counter blocks, and Appendix B.2's second
+//! approach makes each one a message nonce followed by a counter. These commands use the
+//! `AES_CTR_*` aliases, so the nonce is **12 bytes** and the counter is the remaining 4, giving
+//! 2^32 blocks -- 64 GiB -- in a single message.
+//!
+//! `encrypt` writes that 12-byte nonce as the first bytes of its output and `decrypt` reads it back,
+//! exactly as the other modes do with their IVs; note that it is 12 bytes here, not 16.
+//!
+//! # Any length
+//!
+//! CTR is a stream cipher: input of any length is accepted, nothing is padded, and the output is
+//! exactly as long as the input.
+//!
+//! # Warning
+//!
+//! CTR provides confidentiality only. It does not detect tampering, and neither the ciphertext nor
+//! the nonce is authenticated. It is the most malleable of the modes here: flipping any ciphertext
+//! bit flips exactly the corresponding plaintext bit and affects nothing else (SP 800-38A
+//! Appendix D, Table D.2, "SBE in the decryption of Cj"), so an attacker can edit the plaintext at
+//! will, wherever they like, without any garbling to give it away. Do not decrypt data you have not
+//! authenticated separately.
+//!
+//! A repeated nonce is fatal here rather than merely unwise: the same nonce under the same key
+//! gives the same keystream, and two messages XORed with the same keystream leak their XOR. The
+//! nonce is drawn from the OS-backed DRBG for exactly that reason, and there is no way to supply
+//! one.
+
+use crate::block_mode_cmd::{BLOCK_LEN, BlockModeAction, load_key};
+use crate::stream_mode_cmd::run_stream_mode;
+use bouncycastle::aes_lowmemory::{Aes128, Aes192, Aes256, CTR_NONCE_LEN};
+use bouncycastle::core::key_material::KeyMaterial;
+use bouncycastle::core::traits::ElectronicCodeBook;
+use bouncycastle::modes::{Ctr, Decrypting, Encrypting};
+
+pub(crate) fn aes128_ctr_cmd(
+    action: &BlockModeAction,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<Aes128, 16>(action, &load_key::<16>(key, key_file, "AES-128"), output_hex);
+}
+
+pub(crate) fn aes192_ctr_cmd(
+    action: &BlockModeAction,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<Aes192, 24>(action, &load_key::<24>(key, key_file, "AES-192"), output_hex);
+}
+
+pub(crate) fn aes256_ctr_cmd(
+    action: &BlockModeAction,
+    key: &Option<String>,
+    key_file: &Option<String>,
+    output_hex: bool,
+) {
+    run::<Aes256, 32>(action, &load_key::<32>(key, key_file, "AES-256"), output_hex);
+}
+
+/// Dispatches to the shared streaming loops with `Ctr` filled in as the mode.
+fn run<P, const KEY_LEN: usize>(
+    action: &BlockModeAction,
+    key: &KeyMaterial<KEY_LEN>,
+    output_hex: bool,
+) where
+    P: ElectronicCodeBook<KEY_LEN, BLOCK_LEN>,
+{
+    run_stream_mode::<
+        Ctr<P, Encrypting, KEY_LEN, BLOCK_LEN, CTR_NONCE_LEN>,
+        Ctr<P, Decrypting, KEY_LEN, BLOCK_LEN, CTR_NONCE_LEN>,
+        KEY_LEN,
+        CTR_NONCE_LEN,
+    >(action, key, output_hex)
+}