Crate eax 

RustCrypto: EAX

Pure Rust implementation of the EAX Authenticated Encryption with Associated Data (AEAD) cipher.

Documentation

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

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):

use aes::Aes256;
use eax::{
    aead::{Aead, AeadCore, Generate, Key, KeyInit, array::Array},
    Eax, Nonce
};

pub type Aes256Eax = Eax<Aes256>;

let key = Key::<Aes256Eax>::generate();
let cipher = Aes256Eax::new(&key);
let nonce = Nonce::generate(); // 128-bits; MUST be unique per message
let ciphertext = cipher.encrypt(&nonce, b"plaintext message".as_ref())?;
let plaintext = cipher.decrypt(&nonce, ciphertext.as_ref())?;
assert_eq!(&plaintext, b"plaintext message");

In-place Usage (eliminates alloc requirement)

This crate has an optional alloc feature which can be disabled in e.g. microcontroller environments that don’t have a heap.

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::Aes256;
use eax::{
    aead::{
        arrayvec::ArrayVec,
        AeadCore, AeadInOut, Generate, Key, KeyInit,
    },
    Eax, Nonce
};

pub type Aes256Eax = Eax<Aes256>;

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

let nonce = Nonce::generate(); // 128-bits; MUST be unique per message

let mut buffer: ArrayVec<u8, 128> = ArrayVec::new();
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).expect("encryption failure!");

// `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).expect("decryption failure!");
assert_eq!(buffer.as_ref(), b"plaintext message");

Custom Tag Length

The tag for eax is usually 16 bytes long but it can be shortened if needed. The second generic argument of Eax can be set to the tag length:

use aes::Aes256;
use eax::Eax;
use eax::aead::{AeadInOut, KeyInit, array::Array};
use eax::aead::arrayvec::ArrayVec;
use eax::aead::consts::{U8, U128};

let key = Array::from_slice(b"an example very very secret key.");
let cipher = Eax::<Aes256, U8>::new(key);

let nonce = Array::from_slice(b"my unique nonces"); // 128-bits; unique per message

let mut buffer: ArrayVec<u8, 128> = ArrayVec::new();
buffer.try_extend_from_slice(b"plaintext message").unwrap();

// Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
let tag = cipher.encrypt_inout_detached(nonce, b"", buffer.as_mut_slice().into()).expect("encryption failure!");

// The tag has only 8 bytes, compared to the usual 16 bytes
assert_eq!(tag.len(), 8);

// `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_inout_detached(nonce, b"", buffer.as_mut_slice().into(), &tag).expect("decryption failure!");
assert_eq!(buffer.as_ref(), b"plaintext message");

Re-exports

pub use aead;

pub use cipher;

Modules

online

Online¹ variant of the EAX mode.

Structs

Eax

EAX: generic over an underlying block cipher implementation.

Error

Error type.

Constants

A_MAX

Maximum length of associated data

C_MAX

Maximum length of ciphertext

P_MAX

Maximum length of plaintext

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.

Type Aliases

Key

Key used by KeySizeUser implementors.

Nonce

EAX nonces

Tag

EAX tags