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
//! Generic implementation of [EME2 mode][1] for block ciphers.
//!
//! [](https://docs.rs/eme2/)
//!
//! Mode functionality is accessed using traits from re-exported [`cipher`] crate.
//! EME2 (ECB-Mask-ECB) is a wide-block cipher mode of operation that acts as a
//! Strong Pseudorandom Permutation (SPRP).
//!
//! ## ⚠️ 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` 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
//!
//! ### Encryption with a tweak
//!
//! ```
//! use aes::cipher::KeyIvInit;
//! use eme2::Eme2;
//!
//! 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 using standard KeyIvInit (hashes the tweak via `Eme2::hash_ad`)
//! 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[..]);
//! ```
//!
//! ### Encryption with associated data
//!
//! ```
//! use eme2::Eme2;
//! use eme2::cipher::KeyInit;
//!
//! type Aes128Eme2 = Eme2<aes::Aes128>;
//!
//! let key = [0x42; 48];
//! let associated_data = b"associated data";
//! 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 cipher = <Aes128Eme2 as KeyInit>::new(&key.into());
//!
//! // Encrypt in-place, hashing the associated data into the tweak internally
//! cipher.encrypt_with_ad(associated_data, &mut buf).expect("encryption succeeded");
//! assert_ne!(buf[..], plaintext[..]);
//!
//! // Decrypt in-place
//! cipher.decrypt_with_ad(associated_data, &mut buf).expect("decryption succeeded");
//! assert_eq!(buf[..], plaintext[..]);
//! ```
//!
//! [1]: https://ieeexplore.ieee.org/servlet/opac?punumber=11277321
pub use crate;
pub use cipher;