Crate aes_eme2_blake3

Expand description

§AES-EME2-BLAKE3

Pure Rust implementation of the AES-EME2-BLAKE3 Deterministic Encryption (DE) with Authenticated Encryption (AE) cipher.

Documentation

§Security Notes

aes-eme2-blake3 is designed to provide 100% Nonce Misuse Resistance (NMR). Standard modes like AES-GCM fail catastrophically if a nonce is reused. This library uses a Synthetic Initialization Vector (SIV) architecture. BLAKE3 computes a MAC over the plaintext, associated data (AD), and nonce. This MAC is then used as the tweak for the wide-block EME2 cipher. Reusing a nonce with different data completely changes the tweak, maintaining absolute security.

Furthermore, unlike stream ciphers, EME2 acts as a Strong Pseudorandom Permutation (SPRP). It processes your entire payload as a single, massive cryptographic block. If an attacker alters even a single bit of the ciphertext, the decryption process will scramble the entire plaintext into unrecognizable garbage, guaranteeing the subsequent BLAKE3 authentication check will fail.

All implementations contained in the crate rely on the constant-time guarantees of the underlying aes and blake3 crates, while the EME2 core logic itself avoids data-dependent branching.

§Performance & Architecture

We consciously trade pure throughput for maximum operational security. In our latest benchmarks, AES-EME2-BLAKE3-SIV achieves a peak decryption throughput of ~270 MiB/s, whereas a hardware-accelerated AES-GCM implementation achieves ~1.20 GiB/s (roughly 4.5x faster).

This performance difference is expected and reasonable given our architectural goals. AES-GCM is a single-pass stream cipher, whereas EME2 is a true wide-block tweakable enciphering scheme. It requires multiple passes over the plaintext buffer to build the necessary XOR sums for each block, ensuring that every ciphertext byte depends mathematically on the entire plaintext, effectively providing better resistance against certain classes of attacks compared to standard CTR-based modes.

§Throughput Benchmarks

Payload Size	EME2-SIV Encrypt	EME2-SIV Decrypt	AES-GCM Encrypt	AES-GCM Decrypt
32 B	75.1 MiB/s	61.9 MiB/s	207.3 MiB/s	185.2 MiB/s
64 B	106.8 MiB/s	97.1 MiB/s	354.3 MiB/s	328.3 MiB/s
1 KB	213.3 MiB/s	212.7 MiB/s	995.8 MiB/s	1.01 GiB/s
64 KB	269.4 MiB/s	270.1 MiB/s	1.20 GiB/s	1.21 GiB/s
512 KB	270.9 MiB/s	271.2 MiB/s	1.21 GiB/s	1.20 GiB/s
1 MB	271.6 MiB/s	271.0 MiB/s	1.20 GiB/s	1.14 GiB/s
10 MB	243.9 MiB/s	251.8 MiB/s	1.16 GiB/s	1.17 GiB/s

Note: All benchmarks reflect median throughput measurements across 100 samples.

§License

Licensed under either of:

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.

§Usage

Simple usage (allocating, no associated data):

// NOTE: requires the `getrandom` feature is enabled

use aes_eme2_blake3::{
    aead::{Aead, AeadCore, Generate, Key, KeyInit},
    Aes256Eme2Blake3, Nonce // Or `Aes128Eme2Blake3`
};

let key = Key::<Aes256Eme2Blake3>::generate();
let cipher = Aes256Eme2Blake3::new(&key);

let nonce = Nonce::generate(); // MUST be unique per message
let ciphertext = cipher.encrypt(&nonce, b"plaintext message".as_ref()).map_err(|_| "encrypt failed")?;

let plaintext = cipher.decrypt(&nonce, ciphertext.as_ref()).map_err(|_| "decrypt failed")?;
assert_eq!(&plaintext, b"plaintext message");

§In-place Usage

The AeadInOut::encrypt_in_place and AeadInOut::decrypt_in_place methods accept any type that impls the aead::Buffer trait which contains the plaintext for encryption or ciphertext for decryption.

Enabling the arrayvec feature of this crate will provide an impl of aead::Buffer for arrayvec::ArrayVec (re-exported from the aead crate as aead::arrayvec::ArrayVec), and enabling the bytes feature of this crate will provide an impl of aead::Buffer for bytes::BytesMut (re-exported from the aead crate as aead::bytes::BytesMut).

It can then be passed as the buffer parameter to the in-place encrypt and decrypt methods:

// NOTE: requires the `arrayvec` and `getrandom` features are enabled

use aes_eme2_blake3::{
    aead::{AeadCore, AeadInOut, Generate, Key, KeyInit, arrayvec::ArrayVec},
    Aes256Eme2Blake3, Nonce // Or `Aes128Eme2Blake3`
};

let key = Key::<Aes256Eme2Blake3>::generate();
let cipher = Aes256Eme2Blake3::new(&key);

let nonce = Nonce::generate(); // MUST be unique per message
let mut buffer: ArrayVec<u8, 128> = ArrayVec::new(); // Note: buffer needs 24-bytes overhead for auth tag
buffer.try_extend_from_slice(b"plaintext message").unwrap();

// Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
cipher.encrypt_in_place(&nonce, b"", &mut buffer).map_err(|_| "encrypt failed")?;

// `buffer` now contains the message ciphertext
assert_ne!(buffer.as_ref(), b"plaintext message");

// Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
cipher.decrypt_in_place(&nonce, b"", &mut buffer).map_err(|_| "decrypt failed")?;
assert_eq!(buffer.as_ref(), b"plaintext message");

Re-exports§

pub use aead;
pub use aes;aes

Structs§

Eme2Blake3: A SIV (Synthetic Initialization Vector) AEAD cipher using EME2 and BLAKE3.
Error: Error type.

Enums§

TagPosition: Enum which specifies tag position used by an AEAD algorithm.

Traits§

AeadCore: Authenticated Encryption with Associated Data (AEAD) algorithm.
AeadInOut: In-place and inout AEAD trait which handles the authentication tag as a return value/separate parameter.
KeyInit: Types which can be initialized from a key.
KeySizeUser: Types which use key for initialization.
ZeroizeMarkerzeroize: A marker trait used to conditionally enforce ZeroizeOnDrop bounds when the zeroize feature is enabled.

Type Aliases§

Aes128Eme2Blake3aes: EME2-BLAKE3 with AES-128.
Aes256Eme2Blake3aes: EME2-BLAKE3 with AES-256.
Key: Key used by KeySizeUser implementors.
Nonce: External nonce for Eme2Blake3.
Tag: Tag for Eme2Blake3.