[dghgit]

Summary

Adds bouncycastle-tdes: a constant-time, table-free Triple DES (TDEA) engine per SP 800-67r2, on the key objects of #172: TDES3Key<M> (three-key) and the decryption-only two-key TDES2Key<M>, over the engines TDESInternal and TDES2Internal.

Rebased onto feature/key-rework-memory (#172) on 2026-10-24 and ported to its key-object design; the base is now that branch. The review round of PR #140 is applied here in the last two commits: the keys' redundant key-type check is gone, the CLI matches the AES commands and gains a test suite, the Memory Usage table is measured, and the style and nit items are fixed. Wycheproof carries no TDEA vectors, so there is no suite to add.

Description

• S-box layer is a compile-time-derived ANF Boolean circuit (no lookup tables, no secret-indexed memory access).
• TDESKey<P, M> mirrors AESKey: the key holds the mode's state, its workers borrow it, and which role pair a key carries is decided by its mode (CBC<Blocks>, CBC<PKCS7>, ECB<..>, CFB, CFB8, CTR<6, 8>). The aliases TDES_CBC<'k, Dir, Pad>, TDES_CFB, TDES_CFB8, TDES_CTR, TDES_ECB and the TDES2_* decryptors name what the keys hand out. 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.
• TDESInternal::new (its ElectronicCodeBook impl) rejects non-distinct component keys and any of the 64 weak/semi-weak/possibly-weak DES keys (structural check, not a table), as KeyMaterialError::WeakKey (added in this PR).
• TDES2Internal sets ElectronicCodeBook::ENCRYPTION_APPROVED = false (added in this PR); the encrypting modes assert it in an inline const, so TDES2Key::create_encryptor fails to compile under every mode, per SP 800-131A Rev 2's "disallowed for encryption, legacy use for decryption". Two compile_fail doctests pin it.
• CLI subcommands tdes-* / tdes2-* for every mode, through the key objects, with the aes*-* contract: tdes-cbc and tdes2-cbc are CBC<PKCS7> at any length, every command with an IV or nonce takes --iv/--iv-file (in band otherwise), and every command takes -d/--direction; the tdes2-* commands accept only decrypt there, so encrypt is refused by the parser. ECB stays unpadded with no IV, as aes*-ecb is.

Scope and Risk

New crate only; the core / cipher / cli changes it depends on (ENCRYPTION_APPROVED, the mode-side const assert on it, KeyMaterialError::WeakKey, generic block length in the CLI plumbing, DecryptOnlyAction) are additive and covered by existing suites. No behavioural change to AES or other existing ciphers.

Validation

• NIST CAVP T{E,C}{CB,BC,FB64,FB8}MMT{2,3} vectors (bc-test-data), both key sizes, both directions: CBC and CFB through the keys, ECB through the engines.
• Shared frameworks over every mode key: TestFrameworkFromKeyMaterial, TestFrameworkBlockCipher, TestFrameworkSymmetricCipher, TestFrameworkStreamCipher, TestFrameworkElectronicCodeBook.
• cargo test --workspace: all passing; cargo test --workspace --all-targets --no-run builds the benches; cargo +nightly fmt --check clean.
• cli/tests/tdes_cli_tests.rs pins COUNT = 0 of TCBCMMT3, TCFB64MMT3, TCFB8MMT3 and TECBMMT3 through the binary in both directions (encryption under --iv), and the two-key [DECRYPT] vectors through the tdes2-* commands, read from bc-test-data at test time.
• cargo mutants -p bouncycastle-tdes after the review fixes: 500 mutants, 422 caught, 41 unviable, 33 missed (31 bit-permutation XOR/OR equivalences in spread, permute_p, lookup, rotl28, pc1, expand and is_weak, and two loop-bound </<= mutants in the compile-time anf_constants), 4 timeouts (the compile-time ANF constant derivation).

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.

[npajkovsky]

Why on earth would anybody want 3DES?

NIST deprecated 3DES for new use via SP 800-131A Rev. 2 (disallowed after December 31, 2023) and withdrew SP 800-67 Rev. 2 effective January 1, 2024.

[dghgit]

Fair question, even though, as much as I hate to say it, I could point you at people still using DES, some of who should definitely know better... We still support it in BC-FIPS as well, as far as I can tell it's mainly used for dealing with legacy encrypted data these days. In this case this one is simply here as it's on the OpenSSL provider list, so it's one of the algorithms they'll want to invoke (at least for a while).

[dghgit]

The review round of PR #140 applied here, in 5f367891 and e7b7e68e (branch head e7b7e68e):

1. Key roles. The keys never had the MAC-key path, but ran a check_key_type ahead of the engine's own validation, which is the same check for every mode that has a role; it is gone. A scoped cargo mutants on key.rs is 0 missed. Wycheproof carries no TDEA vectors, so there is no suite to add.
2. CLI. tdes-cbc and tdes2-cbc are CBC<PKCS7> at any length; every command with an IV or nonce takes --iv/--iv-file; every command takes -d/--direction, the tdes2-* ones with decrypt as the only value the parser accepts; ECB stays unpadded with no IV, as aes*-ecb is. The commands had no CLI tests: cli/tests/tdes_cli_tests.rs pins COUNT = 0 of TCBCMMT3 (plus the PKCS7 block, computed from the engine), TCFB64MMT3, TCFB8MMT3 and TECBMMT3 through the binary in both directions, encryption under --iv, and the two-key [DECRYPT] vectors through the tdes2-* commands, read from bc-test-data at test time; plus the round trips, padding against alignment, a supplied CTR nonce held to the library, the parser's refusal of tdes2-* -d encrypt, and the bundle rejections.
3. Heading is # 🚨 Security Considerations 🚨, anchor updated.
4. Memory Usage tabulates measured per-entry-point stack for both engines (new 800 B / 544 B, one-block 48 B, two-block 80 B, four-block 112 B; the two-key engine's decrypting entry points only), by the same method and toolchain as the SM4 and Camellia tables.
5. The public-behaviour unit tests in both engines (sizes, names and strengths, the ENCRYPTION_APPROVED gate) moved to alg_name_tests.rs; the split/join, parity and schedule pins stay.
   6–13. Manifest comment, the reference-style link in key.rs, and every doc line within 100 columns.
6. cargo mutants -p bouncycastle-tdes after the changes: 500 mutants, 422 caught, 41 unviable, 33 missed (the bit-permutation XOR/OR equivalences and two loop bounds in the compile-time ANF derivation), 4 timeouts (that derivation). PR description updated.

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