tdes: add bouncycastle-tdes, a constant-time table-free TDEA engine

Cargo.toml

@@ -37,6 +37,7 @@ bouncycastle-sha2 = { path = "./crypto/sha2" }
 bouncycastle-sha3 = { path = "./crypto/sha3" }
 bouncycastle-sm2 = { path = "./crypto/sm2" }
 bouncycastle-sm3 = { path = "./crypto/sm3" }
+bouncycastle-tdes = { path = "./crypto/tdes" }
 bouncycastle-utils = { path = "./crypto/utils" }
 
 
@@ -86,3 +87,4 @@ bouncycastle-sha2.workspace = true
 bouncycastle-sha3.workspace = true
 bouncycastle-sm2.workspace = true
 bouncycastle-sm3.workspace = true
+bouncycastle-tdes.workspace = true

alpha_0.1.4_release_notes.md

@@ -3,6 +3,12 @@
 ## Major features
 
 * CHACHA20 -- ChaCha20, Poly1305 and ChaCha20-Poly1305 (RFC 8439).
+* TDES -- three-key TDEA (NIST SP 800-67 Rev 2) as a constant-time, table-free bit-sliced engine under `hazmat`,
+  with ECB, CBC, CFB64, CFB8 and CTR (SP 800-38A Appendix E) and TDEA Key Wrap (SP 800-38F TKW) through the key
+  role traits; two-key TDEA decrypts and unwraps only, which `BlockPermutation::DECRYPT_ONLY` makes a compile
+  error for every encrypting route; the `tdes-*` and `tdes2-*` CLI commands, whose `encrypt` refuses input past
+  SP 800-67 Rev 2 Sec 3.4's 2^20 blocks counted as the blocks TDEA processes (8 MiB; 1 MiB for CFB8, 699,048
+  bytes for TKW).
 * AES Key Wrap -- AES_KW and AES_KWP (NIST SP 800-38F; RFC 3394 / RFC 5649) over any 128-bit block permutation,
   with the `KeyWrapper` / `KeyUnwrapper` core traits and the `aes*-kw` / `aes*-kwp` CLI commands.
 * ECDSA -- FIPS 186-5 signatures over P-256, P-384, P-521, secp256k1, brainpoolP256r1, brainpoolP384r1 and
@@ -15,6 +21,10 @@
 
 ## Minor features / bug fixes
 
+* The key-wrap workers `Kw`, `Kwp` and `Tkw` carry their direction in the type, as the cipher modes do:
+  `KeyWrapper` is implemented for the encrypting worker only, so an unwrapper has no wrapping method and a
+  permutation that decrypts only is refused a wrapper at compile time by every route. The `AES_KW_*`, `AES_KWP_*`
+  and `TDES_TKW` aliases gain the `Dir` parameter; `TDES2_TKW` is the decrypting one.
 * Cipher and MAC workers no longer implement `SuspendableKeyed` (#173): a resumed worker is a second copy of a
   nonce, counter or keystream position. The AES modes, CMAC and Ascon-AEAD128 lose their suspended-state
   constants and `hazmat::ModeKey` goes with them; HMAC and HKDF still suspend, and hashes, XOFs and KMAC keep

cli/src/aes_cbc_cmd.rs

@@ -10,10 +10,9 @@
 //! separately.
 
 use crate::helpers::block_mode_helpers::{
-    BLOCK_LEN, CipherDirection, decrypt_stream, encrypt_stream, load_iv, load_key_object,
-    start_encryptor,
+    CipherDirection, decrypt_stream, encrypt_stream, load_iv, load_key_object, start_encryptor,
 };
-use bouncycastle::aes::{AES128Key, AES192Key, AES256Key};
+use bouncycastle::aes::{AES_BLOCK_LEN, AES128Key, AES192Key, AES256Key};
 use bouncycastle::cipher::modes::CBC;
 use bouncycastle::cipher::padding::PKCS7;
 use bouncycastle::core::symmetric_key::{SymmetricDecryptionKey, SymmetricEncryptionKey};
@@ -29,7 +28,7 @@ pub(crate) fn aes128_cbc_cmd(
     run::<_, 16>(
         action,
         &load_key_object::<AES128Key<CBC<PKCS7>>, 16>(key, key_file, "AES-128"),
-        load_iv::<BLOCK_LEN>(iv, iv_file),
+        load_iv::<AES_BLOCK_LEN>(iv, iv_file),
         output_hex,
     );
 }
@@ -45,7 +44,7 @@ pub(crate) fn aes192_cbc_cmd(
     run::<_, 24>(
         action,
         &load_key_object::<AES192Key<CBC<PKCS7>>, 24>(key, key_file, "AES-192"),
-        load_iv::<BLOCK_LEN>(iv, iv_file),
+        load_iv::<AES_BLOCK_LEN>(iv, iv_file),
         output_hex,
     );
 }
@@ -61,7 +60,7 @@ pub(crate) fn aes256_cbc_cmd(
     run::<_, 32>(
         action,
         &load_key_object::<AES256Key<CBC<PKCS7>>, 32>(key, key_file, "AES-256"),
-        load_iv::<BLOCK_LEN>(iv, iv_file),
+        load_iv::<AES_BLOCK_LEN>(iv, iv_file),
         output_hex,
     );
 }
@@ -70,19 +69,27 @@ pub(crate) fn aes256_cbc_cmd(
 fn run<K, const KEY_LEN: usize>(
     action: &CipherDirection,
     key: &K,
-    iv: Option<[u8; BLOCK_LEN]>,
+    iv: Option<[u8; AES_BLOCK_LEN]>,
     output_hex: bool,
 ) where
-    K: SymmetricEncryptionKey<KEY_LEN, BLOCK_LEN, BLOCK_LEN>
-        + SymmetricDecryptionKey<KEY_LEN, BLOCK_LEN, BLOCK_LEN>,
+    K: SymmetricEncryptionKey<KEY_LEN, AES_BLOCK_LEN, AES_BLOCK_LEN>
+        + SymmetricDecryptionKey<KEY_LEN, AES_BLOCK_LEN, AES_BLOCK_LEN>,
 {
     match action {
         CipherDirection::Encrypt => {
             let (enc, generated_iv) = start_encryptor(iv, |rng| key.create_encryptor(rng));
-            encrypt_stream::<_, BLOCK_LEN>(enc, generated_iv.as_ref(), output_hex, None)
-        }
-        CipherDirection::Decrypt => {
-            decrypt_stream::<_, BLOCK_LEN>(iv, |iv| key.create_decryptor(iv), output_hex, None)
+            encrypt_stream::<_, AES_BLOCK_LEN, AES_BLOCK_LEN>(
+                enc,
+                generated_iv.as_ref(),
+                output_hex,
+                None,
+            )
         }
+        CipherDirection::Decrypt => decrypt_stream::<_, AES_BLOCK_LEN, AES_BLOCK_LEN>(
+            iv,
+            |iv| key.create_decryptor(iv),
+            output_hex,
+            None,
+        ),
     }
 }

cli/src/aes_cfb8_cmd.rs

@@ -25,9 +25,9 @@
 //! plaintext byte, corrupts the following 16 bytes, and then decryption resynchronises. Do not
 //! decrypt data you have not authenticated separately.
 
-use crate::helpers::block_mode_helpers::{BLOCK_LEN, CipherDirection, load_iv, load_key_object};
+use crate::helpers::block_mode_helpers::{CipherDirection, load_iv, load_key_object};
 use crate::helpers::stream_mode_helpers::run_stream_mode;
-use bouncycastle::aes::{AES128Key, AES192Key, AES256Key};
+use bouncycastle::aes::{AES_BLOCK_LEN, AES128Key, AES192Key, AES256Key};
 use bouncycastle::cipher::modes::CFB8;
 use bouncycastle::core::symmetric_key::{SymmetricDecryptionKey, SymmetricEncryptionKey};
 use bouncycastle::core::traits::{StreamCipherDecryptor, StreamCipherEncryptor};
@@ -43,7 +43,7 @@ pub(crate) fn aes128_cfb8_cmd(
     run::<_, 16>(
         action,
         &load_key_object::<AES128Key<CFB8>, 16>(key, key_file, "AES-128"),
-        load_iv::<BLOCK_LEN>(iv, iv_file),
+        load_iv::<AES_BLOCK_LEN>(iv, iv_file),
         output_hex,
     );
 }
@@ -59,7 +59,7 @@ pub(crate) fn aes192_cfb8_cmd(
     run::<_, 24>(
         action,
         &load_key_object::<AES192Key<CFB8>, 24>(key, key_file, "AES-192"),
-        load_iv::<BLOCK_LEN>(iv, iv_file),
+        load_iv::<AES_BLOCK_LEN>(iv, iv_file),
         output_hex,
     );
 }
@@ -75,7 +75,7 @@ pub(crate) fn aes256_cfb8_cmd(
     run::<_, 32>(
         action,
         &load_key_object::<AES256Key<CFB8>, 32>(key, key_file, "AES-256"),
-        load_iv::<BLOCK_LEN>(iv, iv_file),
+        load_iv::<AES_BLOCK_LEN>(iv, iv_file),
         output_hex,
     );
 }
@@ -84,13 +84,13 @@ pub(crate) fn aes256_cfb8_cmd(
 fn run<'k, K, const KEY_LEN: usize>(
     action: &CipherDirection,
     key: &'k K,
-    iv: Option<[u8; BLOCK_LEN]>,
+    iv: Option<[u8; AES_BLOCK_LEN]>,
     output_hex: bool,
 ) where
-    K: SymmetricEncryptionKey<KEY_LEN, BLOCK_LEN, 0>
-        + SymmetricDecryptionKey<KEY_LEN, BLOCK_LEN, 0>,
-    K::Encryptor<'k>: StreamCipherEncryptor<BLOCK_LEN>,
-    K::Decryptor<'k>: StreamCipherDecryptor<BLOCK_LEN>,
+    K: SymmetricEncryptionKey<KEY_LEN, AES_BLOCK_LEN, 0>
+        + SymmetricDecryptionKey<KEY_LEN, AES_BLOCK_LEN, 0>,
+    K::Encryptor<'k>: StreamCipherEncryptor<AES_BLOCK_LEN>,
+    K::Decryptor<'k>: StreamCipherDecryptor<AES_BLOCK_LEN>,
 {
-    run_stream_mode::<K, KEY_LEN, BLOCK_LEN>(action, key, iv, output_hex)
+    run_stream_mode::<K, KEY_LEN, AES_BLOCK_LEN>(action, key, iv, output_hex)
 }

cli/src/aes_cfb_cmd.rs

@@ -26,9 +26,9 @@
 //! 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::helpers::block_mode_helpers::{BLOCK_LEN, CipherDirection, load_iv, load_key_object};
+use crate::helpers::block_mode_helpers::{CipherDirection, load_iv, load_key_object};
 use crate::helpers::stream_mode_helpers::run_stream_mode;
-use bouncycastle::aes::{AES128Key, AES192Key, AES256Key};
+use bouncycastle::aes::{AES_BLOCK_LEN, AES128Key, AES192Key, AES256Key};
 use bouncycastle::cipher::modes::CFB;
 use bouncycastle::core::symmetric_key::{SymmetricDecryptionKey, SymmetricEncryptionKey};
 use bouncycastle::core::traits::{StreamCipherDecryptor, StreamCipherEncryptor};
@@ -44,7 +44,7 @@ pub(crate) fn aes128_cfb_cmd(
     run::<_, 16>(
         action,
         &load_key_object::<AES128Key<CFB>, 16>(key, key_file, "AES-128"),
-        load_iv::<BLOCK_LEN>(iv, iv_file),
+        load_iv::<AES_BLOCK_LEN>(iv, iv_file),
         output_hex,
     );
 }
@@ -60,7 +60,7 @@ pub(crate) fn aes192_cfb_cmd(
     run::<_, 24>(
         action,
         &load_key_object::<AES192Key<CFB>, 24>(key, key_file, "AES-192"),
-        load_iv::<BLOCK_LEN>(iv, iv_file),
+        load_iv::<AES_BLOCK_LEN>(iv, iv_file),
         output_hex,
     );
 }
@@ -76,7 +76,7 @@ pub(crate) fn aes256_cfb_cmd(
     run::<_, 32>(
         action,
         &load_key_object::<AES256Key<CFB>, 32>(key, key_file, "AES-256"),
-        load_iv::<BLOCK_LEN>(iv, iv_file),
+        load_iv::<AES_BLOCK_LEN>(iv, iv_file),
         output_hex,
     );
 }
@@ -85,13 +85,13 @@ pub(crate) fn aes256_cfb_cmd(
 fn run<'k, K, const KEY_LEN: usize>(
     action: &CipherDirection,
     key: &'k K,
-    iv: Option<[u8; BLOCK_LEN]>,
+    iv: Option<[u8; AES_BLOCK_LEN]>,
     output_hex: bool,
 ) where
-    K: SymmetricEncryptionKey<KEY_LEN, BLOCK_LEN, 0>
-        + SymmetricDecryptionKey<KEY_LEN, BLOCK_LEN, 0>,
-    K::Encryptor<'k>: StreamCipherEncryptor<BLOCK_LEN>,
-    K::Decryptor<'k>: StreamCipherDecryptor<BLOCK_LEN>,
+    K: SymmetricEncryptionKey<KEY_LEN, AES_BLOCK_LEN, 0>
+        + SymmetricDecryptionKey<KEY_LEN, AES_BLOCK_LEN, 0>,
+    K::Encryptor<'k>: StreamCipherEncryptor<AES_BLOCK_LEN>,
+    K::Decryptor<'k>: StreamCipherDecryptor<AES_BLOCK_LEN>,
 {
-    run_stream_mode::<K, KEY_LEN, BLOCK_LEN>(action, key, iv, output_hex)
+    run_stream_mode::<K, KEY_LEN, AES_BLOCK_LEN>(action, key, iv, output_hex)
 }

cli/src/aes_ecb_cmd.rs

@@ -16,9 +16,9 @@
 //! `aes*-cbc` or `aes*-cfb` under separate authentication, or better an AEAD.
 
 use crate::helpers::block_mode_helpers::{
-    BLOCK_LEN, CipherDirection, decrypt_stream, encrypt_stream, load_key_object, start_encryptor,
+    CipherDirection, decrypt_stream, encrypt_stream, load_key_object, start_encryptor,
 };
-use bouncycastle::aes::{AES128Key, AES192Key, AES256Key};
+use bouncycastle::aes::{AES_BLOCK_LEN, AES128Key, AES192Key, AES256Key};
 use bouncycastle::cipher::modes::hazmat::ecb::ECB;
 use bouncycastle::cipher::padding::NoPadding;
 use bouncycastle::core::symmetric_key::{SymmetricDecryptionKey, SymmetricEncryptionKey};
@@ -69,16 +69,16 @@ pub(crate) fn aes256_ecb_cmd(
 /// the loops write and read no IV, and `NoPadding` makes them refuse a partial final block.
 fn run<K, const KEY_LEN: usize>(action: &CipherDirection, key: &K, output_hex: bool)
 where
-    K: SymmetricEncryptionKey<KEY_LEN, 0, BLOCK_LEN>
-        + SymmetricDecryptionKey<KEY_LEN, 0, BLOCK_LEN>,
+    K: SymmetricEncryptionKey<KEY_LEN, 0, AES_BLOCK_LEN>
+        + SymmetricDecryptionKey<KEY_LEN, 0, AES_BLOCK_LEN>,
 {
     match action {
         CipherDirection::Encrypt => {
             // ECB has no IV: the constructor's RNG draws nothing, and nothing is written.
             let (enc, _) = start_encryptor(None, |rng| key.create_encryptor(rng));
-            encrypt_stream::<_, 0>(enc, None, output_hex, Some(MODE))
+            encrypt_stream::<_, 0, AES_BLOCK_LEN>(enc, None, output_hex, Some(MODE))
         }
-        CipherDirection::Decrypt => decrypt_stream::<_, 0>(
+        CipherDirection::Decrypt => decrypt_stream::<_, 0, AES_BLOCK_LEN>(
             None,
             |no_iv| key.create_decryptor(no_iv),
             output_hex,

cli/src/aes_kw_cmd.rs

@@ -44,7 +44,7 @@
 //!     | bc-rust aes128-kw -d encrypt --key 000102030405060708090a0b0c0d0e0f -x
 //! ```
 
-use crate::helpers::block_mode_helpers::{CipherDirection, load_key_object};
+use crate::helpers::block_mode_helpers::{CipherDirection, InputLimit, load_key_object};
 use crate::helpers::write_bytes_or_hex;
 use bouncycastle::aes::{AES128Key, AES192Key, AES256Key};
 use bouncycastle::cipher::modes::{KW, KWP};
@@ -62,6 +62,7 @@ pub(crate) fn aes128_kw_cmd(
     run::<_, 16>(
         direction,
         &load_key_object::<AES128Key<KW>, 16>(key, key_file, "AES-128-KW"),
+        None,
         output_hex,
         "AES-128-KW",
     );
@@ -76,6 +77,7 @@ pub(crate) fn aes192_kw_cmd(
     run::<_, 24>(
         direction,
         &load_key_object::<AES192Key<KW>, 24>(key, key_file, "AES-192-KW"),
+        None,
         output_hex,
         "AES-192-KW",
     );
@@ -90,6 +92,7 @@ pub(crate) fn aes256_kw_cmd(
     run::<_, 32>(
         direction,
         &load_key_object::<AES256Key<KW>, 32>(key, key_file, "AES-256-KW"),
+        None,
         output_hex,
         "AES-256-KW",
     );
@@ -104,6 +107,7 @@ pub(crate) fn aes128_kwp_cmd(
     run::<_, 16>(
         direction,
         &load_key_object::<AES128Key<KWP>, 16>(key, key_file, "AES-128-KWP"),
+        None,
         output_hex,
         "AES-128-KWP",
     );
@@ -118,6 +122,7 @@ pub(crate) fn aes192_kwp_cmd(
     run::<_, 24>(
         direction,
         &load_key_object::<AES192Key<KWP>, 24>(key, key_file, "AES-192-KWP"),
+        None,
         output_hex,
         "AES-192-KWP",
     );
@@ -132,29 +137,52 @@ pub(crate) fn aes256_kwp_cmd(
     run::<_, 32>(
         direction,
         &load_key_object::<AES256Key<KWP>, 32>(key, key_file, "AES-256-KWP"),
+        None,
         output_hex,
         "AES-256-KWP",
     );
 }
 
 /// Reads all of stdin, wraps or unwraps it under `kek`, and writes the result. `alg` names the
-/// algorithm in error messages.
-fn run<K, const KEK_LEN: usize>(direction: &CipherDirection, kek: &K, output_hex: bool, alg: &str)
-where
+/// algorithm in error messages. Shared with the other block ciphers' key-wrap commands.
+pub(crate) fn run<K, const KEK_LEN: usize>(
+    direction: &CipherDirection,
+    kek: &K,
+    limit: Option<&InputLimit>,
+    output_hex: bool,
+    alg: &str,
+) where
     K: KeyWrappingKey<KEK_LEN> + KeyUnwrappingKey<KEK_LEN>,
 {
+    match direction {
+        CipherDirection::Encrypt => run_with(|input| kek.wrap(input), limit, output_hex, alg),
+        CipherDirection::Decrypt => run_with(|input| kek.unwrap(input), None, output_hex, alg),
+    }
+}
+
+/// Reads all of stdin, applies `op` to it and writes the result; the unwrap-only commands pass
+/// their key's `unwrap` alone, so that no wrapper is ever instantiated for their key type.
+/// `limit`, for a wrapping command whose standard bounds what one key may protect, is checked
+/// against the whole input before `op` runs.
+pub(crate) fn run_with(
+    op: impl FnOnce(&[u8]) -> Result<Vec<u8>, SymmetricCipherError>,
+    limit: Option<&InputLimit>,
+    output_hex: bool,
+    alg: &str,
+) {
     let mut input = Vec::new();
     if let Err(e) = std::io::stdin().read_to_end(&mut input) {
         eprintln!("Error: couldn't read stdin: {e}");
         exit(-1);
     }
+    if let Some(limit) = limit
+        && input.len() as u64 > limit.max_bytes
+    {
+        eprintln!("Error: {}", limit.message);
+        exit(-1);
+    }
 
-    let result = match direction {
-        CipherDirection::Encrypt => kek.wrap(&input),
-        CipherDirection::Decrypt => kek.unwrap(&input),
-    };
-
-    match result {
+    match op(&input) {
         Ok(output) => write_bytes_or_hex(&output, output_hex),
         Err(SymmetricCipherError::DecryptionFailed) => {
             eprintln!(