Crate eax[−][src]
EAX: Authenticated Encryption and Associated Data (AEAD) cipher based on AES in counter mode.
Usage
Simple usage (allocating, no associated data):
use aes::Aes256; use eax::Eax; use eax::aead::{Aead, NewAead, generic_array::GenericArray}; let key = GenericArray::from_slice(b"an example very very secret key."); let cipher = Eax::<Aes256>::new(key); let nonce = GenericArray::from_slice(b"my unique nonces"); // 128-bits; unique per message let ciphertext = cipher.encrypt(nonce, b"plaintext message".as_ref()) .expect("encryption failure!"); // NOTE: handle this error to avoid panics! let plaintext = cipher.decrypt(nonce, ciphertext.as_ref()) .expect("decryption failure!"); // NOTE: handle this error to avoid panics! 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 AeadInPlace::encrypt_in_place
and AeadInPlace::decrypt_in_place
methods accept any type that impls the aead::Buffer
trait which
contains the plaintext for encryption or ciphertext for decryption.
Note that if you enable the heapless
feature of this crate,
you will receive an impl of aead::Buffer
for heapless::Vec
(re-exported from the aead
crate as [aead::heapless::Vec
]),
which can then be passed as the buffer
parameter to the in-place encrypt
and decrypt methods:
use aes::Aes256; use eax::Eax; use eax::aead::{AeadInPlace, NewAead, generic_array::GenericArray}; use eax::aead::heapless::{Vec, consts::U128}; let key = GenericArray::from_slice(b"an example very very secret key."); let cipher = Eax::<Aes256>::new(key); let nonce = GenericArray::from_slice(b"my unique nonces"); // 128-bits; unique per message let mut buffer: Vec<u8, U128> = Vec::new(); buffer.extend_from_slice(b"plaintext message"); // 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, 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, 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::{AeadInPlace, NewAead, generic_array::GenericArray}; use eax::aead::heapless::{Vec, consts::U8, consts::U128}; let key = GenericArray::from_slice(b"an example very very secret key."); let cipher = Eax::<Aes256, U8>::new(key); let nonce = GenericArray::from_slice(b"my unique nonces"); // 128-bits; unique per message let mut buffer: Vec<u8, U128> = Vec::new(); buffer.extend_from_slice(b"plaintext message"); // Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext let tag = cipher.encrypt_in_place_detached(nonce, b"", &mut buffer).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, b"plaintext message"); // Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext cipher.decrypt_in_place_detached(nonce, b"", &mut buffer, &tag).expect("decryption failure!"); assert_eq!(&buffer, b"plaintext message");
Re-exports
pub use aead; | |
pub use cipher; |
Modules
online | Online1 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 core trait. |
AeadInPlace | In-place stateless AEAD trait. |
NewAead | Instantiate either a stateless |
Type Definitions
Nonce | EAX nonces |
Tag | EAX tags |