[dghgit]

Summary

Adds bouncycastle-sm4: a constant-time, table-free, low-memory SM4 block cipher (GB/T 32907-2016, as described in draft-ribose-cfrg-sm4-10), ported from Bouncy Castle Java's SM4Engine, on the key objects of #172: SM4Key<M> over the engine SM4Internal.

Rebased onto feature/key-rework-memory (#172) on 2026-10-25 and ported to its key-object design; the base is now that branch. The review items of 2026-10-27 are addressed in the last three commits: the key's leftover MAC-key path is gone, the CLI matches the AES commands, the Memory Usage table is measured, the style and nit items are fixed, and the SM4 Wycheproof GCM and CCM suites run through the mode traits. The four-mode scope (no AEAD roles) is unchanged.

Description

• The S-box is a 127-gate Boolean circuit (found by exhaustive search, reusing the Boyar-Peralta AES non-linear section via a field isomorphism), not a lookup table.
• Bit-sliced over 16-bit planes, four blocks at a time.
• SM4Key<M> mirrors AESKey at SM4's one key length: the key holds the mode's state, its workers borrow it, and which role pair a key carries is decided by its mode. The crate aliases CBC, CFB, CFB8 and CTR (SM4_CBC<'k, Dir, Pad>, SM4_CFB<'k, Dir>, ...); the key carries the symmetric and block role pairs only, which cover those four modes; the engine implements ModeNames for all nine, so the mode types over it are named, but a key under GCM, CCM, CMAC or ECB<Blocks> has no role. Keys and engines implement PartialEq / Eq in constant time over the expanded schedule, as on Key object rework: the traits lose their constructors, every mode gets a key, and workers borrow the key #172.
• CLI subcommands sm4-{cbc,cfb,cfb8,ctr}, through the key object, with the aes128-* contract: sm4-cbc is CBC<PKCS7> at any length, every command takes --iv/--iv-file (the IV or nonce is in band otherwise) and -d/--direction.

Scope and Risk

New crate only; the shared changes it carries (the bouncycastle-sm4 workspace entry, the umbrella re-export, the memory bench) are additive. No behavioural change to AES or other existing ciphers.

Validation

• draft-ribose-cfrg-sm4-10 Appendix A.1 vectors (all 6 examples, every round key and round output, the two 1,000,000-fold iterations under --release), A.2.1 ECB and BC Java's own SM4Test vectors, through the engine; A.2.2 CBC through SM4Key<CBC<Blocks>>, A.2.4 CFB through SM4Key<CFB>, A.2.5 CTR through a reference built from the Sec 8.7.1 equations which SM4Key<CTR> is held to, and the Sec 8.5.2 equations at s = 8 for SM4Key<CFB8>.
• RFC 8998 Appendix A: the SM4-GCM and SM4-CCM vectors through the GCM and CCM<12, 16> hazmat mode traits over the permutation's key state (new with the port); Wycheproof sm4_gcm_test.json (65 of 104 cases dispatchable, the 96-bit-IV ones) and sm4_ccm_test.json (162 of 184, those within SP 800-38C A.1's nonce and tag sets) the same way.
• Shared frameworks over the key: TestFrameworkFromKeyMaterial for every mode, and the block, symmetric and stream suites.
• cargo test --workspace: all passing; cargo test --workspace --all-targets --no-run builds the benches; cargo +nightly fmt --check clean. The CLI integration tests pin the draft's A.2.2 CBC and A.2.4 CFB vectors through the binary in both directions, encryption under --iv.
• cargo mutants -p bouncycastle-sm4 after the review fixes: 395 mutants, 368 caught, 23 unviable, 4 missed (the XOR/OR equivalences in ortho::swap, sbox and tau); the key.rs misses of the review are gone.

AI Usage Statement

• Yes, non-trivial code changes were generated by AI

Assisted-by: Claude:claude-sonnet-5
Assisted-by: Claude:claude-mythos-5-1

🤖 Generated with Claude Code

[ounsworth]

We had agreed not to add more ciphers until we get through reviewing and locking in the overall architecture via the AES work. Closing this PR for now.

[roy-basmacier]

Reviewed the PR with Mythos. Everything looks fine expect for the keys with no roles and the cli doesn't match the AES CLI. There's also some editorial findings as well as small nitpicks. Here is the findings below

1. Key roles (intended scope; cleanup incomplete). SM4Key carries only the symmetric and block
   pairs by design: commit 8df9e35 removed the AEAD, ECB and MAC pairs because they "were there for
   parity with AESKey only", and the PR description says so. So an inert key under GCM, CCM, CMAC
   or ECB<Blocks> is expected. Two things remain:
   • Leftover code (should fix). as_cipher_key and the _ => arm in from_key_material exist
     only for MAC-mode keys, which no longer have a role; all four missed key.rs mutants are there.
     Delete them (or test them if they are meant to stay).
   • Scope vs the Wycheproof rule. QUALITY_AND_STYLE requires Wycheproof tests;
     the only SM4 Wycheproof vectors in bc-test-data are sm4_gcm_test.json (104) and
     sm4_ccm_test.json (184), and those are the RFC 8998 TLS 1.3 suites the PR already proves through
     the hazmat traits. Accepting the four-mode scope means accepting that gap; restoring the AEAD
     roles (plus aliases, Wycheproof suites, CLI) closes it.
2. CLI contract. sm4-cbc is CBC<NoPadding> (whole blocks only) with no --iv/--iv-file;
   on this base aes128-cbc is PKCS7, any length, with --iv/--iv-file, and the stream commands have
   --iv too. The sm4-cbc help says "See aes128-cbc for the IV convention, block-alignment requirement"
   — neither is true of aes128-cbc any more. The helpers already take Option<[u8; N]> (the SM4 commands
   pass None). Recommend matching AES; the CLI tests could then pin encryption against A.2.2/A.2.4.

Should fix (style guide)

3. lib.rs:208 heading must be # 🚨 Security Considerations 🚨; fix the anchor at lib.rs:15.
4. Memory Usage (lib.rs:191–206) has no measured per-entry-point stack table; AES tabulates new,
   encrypt_block, encrypt_2blocks, encrypt_4blocks. Measure and tabulate the same way.
5. Unit tests in src that only test public behaviour (test_alg_name_and_strength, test_lanes_constant,
   test_engine_size_is_exactly_the_round_keys) duplicate alg_name_tests.rs; keep the per-round pins and
   the exhaustive S-box test, move/drop the rest.

Nits

6. crypto/sm4/Cargo.toml:9 comment is stale (cipher is used by key.rs, ModeNames, all four aliases) and
   lines 11–12 are a dangling comment.
7. schedule.rs:7 links crate::SM4::decrypt_block (no such item; private module, so rustdoc is silent).
8. bitslice.rs:31–32 cites bouncycastle-camellia, which is not in the workspace.
9. gbt32907_tests.rs:11 says src/sm4.rs; it is src/hazmat/sm4.rs.
10. cli/tests/sm4_*: cite aes_cbc_cli_tests.rs, cli/src/cbc_cmd.rs, cli/src/stream_mode_cmd.rs;
    none exist (AES CLI tests are test_aes_*.sh, helpers are under cli/src/helpers/).
11. key.rs:6–7 lists the symmetric pair as CFB/CFB8/CTR/CBC; ECB<PKCS7> also works and is tested.
12. hazmat/sm4.rs:88–90, 121, 131, 139 say ElectronicCodeBook::encrypt_block etc.; those methods are on
    BlockPermutation on this base.
13. Over-width doc lines: lib.rs:118 (183 cols), :119 (149), and ~25 others >100; rustfmt does not wrap
    comments, and commit c0b19d0 claims a reflow.
14. PR description: mutants count is 406 after the port, not 374; the new misses are the key.rs path in (1).

Context, not findings

• Single-block calls fill all four lanes with copies, so CBC and CFB encryption (serial) run at a quarter
  of the 4-block throughput. Inherent to the u16-plane "lowmemory" choice and documented.
• The two unused dependency warnings in the test log are from base64 and cipher on the base branch.

[dghgit]

Review items addressed in d4df9254, a964b864 and 2868bba9 (branch head 2868bba9):

1. Key roles. as_cipher_key and the _ => arm are gone, and check_key_type with them: the permutation's own validation is the same check for every mode that has a role, and keeping it left a surviving mutant. A scoped cargo mutants on key.rs is 0 missed (was 4). The four-mode scope is unchanged. The Wycheproof gap is closed on that scope: sm4_gcm_test.json (65 of 104 cases, the 96-bit-IV ones) and sm4_ccm_test.json (162 of 184, those within SP 800-38C A.1's nonce and tag sets) run through the GCM / CCM mode traits over the engine, as rfc8998_tests already did, and the rest are counted as unsupported as the AES suites do.
2. CLI. sm4-cbc is CBC<PKCS7> at any length; all four commands take --iv/--iv-file and -d/--direction like every other cipher command. The CLI tests pin encryption now: sm4-cbc encrypt --iv reproduces A.2.2 (plus the PKCS7 block, computed from the permutation) and sm4-cfb encrypt --iv reproduces A.2.4 exactly.
3. Heading is # 🚨 Security Considerations 🚨, anchor updated.
4. Memory Usage tabulates measured per-entry-point stack (new 272 B, one- and four-block 96 B, two-block 112 B). The bench takes the AES bench's measure-closure shape and the figures are the closure frames from the release build's frame-layout remarks plus the return address, rustc 1.97 nightly on x86-64. Note: the AES table's figures do not reproduce by that method on this toolchain (its encrypt_block closure measures 40 B, not 208 B), so the SM4 table states its method rather than matching the AES numbers.
5. The three public-behaviour unit tests moved to alg_name_tests.rs or went; the per-round pins stay.
   6–13. All fixed: manifest comment, schedule.rs link, camellia citation, src/hazmat/sm4.rs path, CLI test citations (cli/src/helpers/, test_aes_*.sh), ECB<PKCS7> in the key docs, BlockPermutation attributions, every doc line within 100 columns.
6. cargo mutants -p bouncycastle-sm4 after the changes: 395 mutants, 368 caught, 23 unviable, 4 missed (the XOR/OR equivalences in ortho::swap, sbox and tau). PR description updated.

cargo test --workspace, --all-targets --no-run, rustdoc with warnings denied and rustfmt are clean.

[roy-basmacier]

Looks good, there are 2 new issues found after the fix:

New issues:

1. The stack table undercounts by about 4x. It reports only the top frame of each call. But encrypt_4blocks, tau and ortho each get their own frame underneath it, which I confirmed in the disassembly. The AES table, which this one claims to follow, sums the whole chain. Same build, with return addresses:

   Entry point	PR table	Deepest chain
   new	272 B	~704 B
   one- and four-block calls	96 B	~416 B
   two-block calls	112 B	~432 B

2. A key under a MAC mode now contradicts its own KEY_TYPE (minor). For SM4Key<CMAC<16>>, KEY_TYPE is still MACKey. The constructor now rejects MAC keys and accepts cipher keys, and generate() always fails. This breaks the constructor trait's contract, but such a key can't do anything. A one-line key-type check against the mode, plus a test, would make it reject consistently.