1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
//! Generic implementation of [EME2 mode][1] extended for arbitrary block ciphers.
//!
//! [](https://docs.rs/eme2-extended/)
//!
//! Mode functionality is accessed using traits from re-exported [`cipher`] crate.
//! EME2-extended (ECB-Mask-ECB) is a wide-block cipher mode of operation that acts as a
//! Strong Pseudorandom Permutation (SPRP).
//!
//! Unlike standard EME2 which is limited to 128-bit block ciphers, this crate
//! utilizes an `EmePoly` trait to provide compile-time verified Galois Field
//! polynomials for 128-bit, 256-bit, 512-bit, and 1024-bit block sizes, securely
//! supporting ciphers like `Threefish`.
//!
//! ## ⚠️ Security Warning: Hazmat!
//!
//! This crate does not ensure ciphertexts are authentic! Thus ciphertext integrity
//! is not verified, which can lead to serious vulnerabilities!
//! It is highly recommended to use EME2 in combination with a strong MAC to provide robust authenticated encryption.
//!
//! ## Migrating from Stream Ciphers (e.g., CTR Mode)
//!
//! Because `eme2-extended` strictly implements RustCrypto's `KeyIvInit` traits, instantiating the cipher
//! is a 1:1 drop-in replacement for stream ciphers like `ctr`. However, **execution differs**:
//!
//! * **Stream Ciphers (CTR):** Encryption and decryption are mathematically identical, so they use the `StreamCipher` trait and expose `.apply_keystream(&mut data)`.
//! * **Wide-Block Ciphers (EME2):** Encryption and decryption are asymmetric. Thus, EME2 does not implement `StreamCipher` and instead exposes explicit `.encrypt(&mut data)` and `.decrypt(&mut data)` methods.
//!
//! ## Examples
//!
//! ### IEEE Std 1619.2 (EME2)
//!
//! ```
//! use aes::cipher::KeyIvInit;
//! use eme2_extended::Eme2;
//!
//! type Aes128Eme2 = Eme2<aes::Aes128>;
//!
//! let key = [0x42; 48]; // Key1 || Key2 || Key3
//! let tweak = [0x24; 16];
//! let plaintext = b"hello world! this is my plaintext! it needs to be longer.";
//! let mut buf = plaintext.to_vec();
//!
//! // Initialize using standard KeyIvInit (uses EME2 tweak hashing)
//! let cipher = Aes128Eme2::new(&key.into(), &tweak.into());
//!
//! // Encrypt in-place
//! cipher.encrypt(&mut buf).expect("encryption succeeded");
//! assert_ne!(buf[..], plaintext[..]);
//!
//! // Decrypt in-place
//! cipher.decrypt(&mut buf).expect("decryption succeeded");
//! assert_eq!(buf[..], plaintext[..]);
//! ```
//!
//! ### EME* Compatibility Mode
//!
//! ```
//! use eme2_extended::Eme2;
//! use eme2_extended::cipher::KeyInit;
//!
//! type Aes128Eme2 = Eme2<aes::Aes128>;
//!
//! let key = [0x42; 48];
//! let tweak = [0x24; 16];
//! let plaintext = b"hello world! this is my plaintext! it needs to be longer.";
//! let mut buf = plaintext.to_vec();
//!
//! // Initialize cipher using the base KeyInit trait
//! let mut cipher = <Aes128Eme2 as KeyInit>::new(&key.into());
//!
//! // Calculate and apply EME* tweak
//! let t_star = cipher.hash_ad_emestar(&tweak);
//! cipher.set_tweak(t_star);
//!
//! // Encrypt in-place
//! cipher.encrypt(&mut buf).expect("encryption succeeded");
//! assert_ne!(buf[..], plaintext[..]);
//!
//! // Decrypt in-place
//! cipher.decrypt(&mut buf).expect("decryption succeeded");
//! assert_eq!(buf[..], plaintext[..]);
//! ```
//!
//! [1]: https://ieeexplore.ieee.org/servlet/opac?punumber=11277321
pub use cipher;
pub use crate;