eme2_extended/
lib.rs

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

eme2_extended/
lib.rs
