eme2 0.2.1

EME2 (ECB-Mask-ECB) wide-block cipher mode of operation
Documentation 
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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

# eme2

[![Docs][docs-image]][docs-link]
![Apache2/MIT licensed][license-image]
![Rust Version][rustc-image]

Generic implementation of the [EME2][EME2-IEEE] (ECB-Mask-ECB) wide-block cipher mode of operation.

Mode functionality is accessed using traits from the re-exported [`cipher`][cipher-doc] crate.

## Standards and Specifications

This crate implements **IEEE Std 1619.2 EME2-AES**, which is the original academic **EME\***
specification instantiated with a 128-bit block cipher and a concrete key schedule (one master
key split into Key1/Key2/Key3) in place of EME*'s independent masks L and R. The two specs
describe the same algorithm, so there is a single implementation ([`Eme2::hash_ad`],
`encrypt_with_ad`, `decrypt_with_ad`); the `_eme2`/`_emestar`-suffixed method names are kept
as aliases only so callers can cite whichever spec they care about.

### Reference Documents
*   **EME2 (Standard):** [IEEE Std 1619.2-2008: IEEE Standard for Wide-Block Encryption for Shared Storage Media][EME2-IEEE] (located at `docs/eme2-ieee.pdf`)
*   **EME\* (Academic Paper):** ["EME*: extending EME to handle arbitrary-length messages with associated data" (Shai Halevi, 2004)][EME-Paper] (located at `docs/2004-125.pdf`)

## Cipher Compatibility

**This crate ONLY supports block ciphers with a 16-byte (128-bit) block size.** 

EME2 mathematically requires a 128-bit polynomial ($x^{128} + x^7 + x^2 + x + 1$) for its internal tweak processing. Ciphers with larger block sizes (such as `Threefish256`, `Threefish512`, or `Threefish1024`) are structurally incompatible with EME2 and are safely rejected at compile time by the crate's generic trait bounds (`BlockSizeUser<BlockSize = U16>`).

The implementation is explictly tested against standard 128-bit block ciphers to guarantee compatibility across the ecosystem:
*   `aes-128`
*   `aes-256`
*   `serpent`

## 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`:

```rust
// CTR Mode Initialization
let cipher = Ctr128BE::<Aes128>::new(&key.into(), &nonce.into());

// EME2 Mode Initialization
let cipher = Eme2::<Aes128>::new(&key.into(), &tweak.into());
```

However, **execution differs**. Stream ciphers use the `StreamCipher` trait because their encryption and decryption processes are mathematically identical (XORing a keystream). EME2 is a **Wide-Block Cipher**, meaning its encryption and decryption passes are mathematically asymmetric. Therefore, it does not implement `StreamCipher` and instead exposes explicit `.encrypt()` and `.decrypt()` methods:

```rust
// Stream Ciphers (CTR)
cipher.apply_keystream(&mut data); // Handles both encryption and decryption

// Wide-Block Ciphers (EME2)
cipher.encrypt(&mut data).expect("encryption succeeded");
cipher.decrypt(&mut data).expect("decryption succeeded");
```

## Usage Examples

### 1. Encryption with a tweak

```rust
use aes::Aes256;
use cipher::KeyIvInit;
use eme2::Eme2;

type Aes256Eme2 = Eme2<Aes256>;

let key = [0x42; 64]; // Partitioned internally into Key1, Key2, and Key3
let tweak = [0x11; 16];
let mut data = vec![0u8; 64];

// Initialization using KeyIvInit trait (hashes the tweak via `Eme2::hash_ad`)
let cipher = Aes256Eme2::new(&key.into(), &tweak.into());

cipher.encrypt(&mut data).expect("encryption succeeded");
cipher.decrypt(&mut data).expect("decryption succeeded");
```

### 2. Encryption with associated data

```rust
use aes::Aes256;
use cipher::KeyInit;
use eme2::Eme2;

type Aes256Eme2 = Eme2<Aes256>;

let key = [0x42; 64];
let mut data = vec![0u8; 64];

let cipher = <Aes256Eme2 as cipher::KeyInit>::new(&key.into());

let associated_data = b"associated data";
cipher.encrypt_with_ad(associated_data, &mut data).expect("encryption succeeded");
cipher.decrypt_with_ad(associated_data, &mut data).expect("decryption succeeded");
```

## ⚠️ 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.

## License

Licensed under either of:

 * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
 * [MIT license](http://opensource.org/licenses/MIT)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.

[//]: # (badges)

[docs-image]: https://docs.rs/eme2/badge.svg
[docs-link]: https://docs.rs/eme2/
[license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
[rustc-image]: https://img.shields.io/badge/rustc-1.87+-blue.svg

[//]: # (general links)

[EME2-IEEE]: https://ieeexplore.ieee.org/servlet/opac?punumber=11277321
[EME-Paper]: https://eprint.iacr.org/2004/125.pdf
[cipher-doc]: https://docs.rs/cipher/