Struct eax::online::Eax

pub struct Eax<Cipher, Op> where
    Cipher: BlockCipher<BlockSize = U16> + NewBlockCipher + Clone,
    Cipher::ParBlocks: ArrayLength<Block<Cipher>>,
    Op: CipherOp,  { /* fields omitted */ }

Online¹ variant of the EAX mode.

This type is generic to support substituting alternative cipher implementations.

In contrast to Eax, can be used in an online¹ fashion and operates in-place.

Authentication

Due to AE (authenticated encryption) nature of EAX, it is vital to verify that both public (also called associated) and privacy-protected (encrypted) data has not been tampered with.

Because of this, it is required for the consumers to explicitly call finish after the encryption/decryption operation is complete. This will either return a tag (when encrypting) used to authenticate data or a Result (when decrypting) that signifies whether the data is authentic, which is when the resulting tag is equal to the one created during encryption.

Example

use eax::{Error, online::{Eax, Decrypt, Encrypt}};
use aes::Aes256;
use block_cipher::generic_array::GenericArray;

let key = GenericArray::from_slice(b"an example very very secret key.");

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

let assoc = b"my associated data";
let plaintext = b"plaintext message";

let mut buffer: [u8; 17] = *plaintext;

// Encrypt a simple message
let mut cipher = Eax::<Aes256, Encrypt>::with_key_and_nonce(key, nonce);
cipher.update_assoc(&assoc[..]);
cipher.encrypt(&mut buffer[..9]);
cipher.encrypt(&mut buffer[9..]);
let tag = cipher.finish();

assert_ne!(buffer, *plaintext);

let mut cloned = buffer;

// Now decrypt it, using the same key and nonce
let mut cipher = Eax::<Aes256, Decrypt>::with_key_and_nonce(key, nonce);
cipher.update_assoc(&assoc[..]);
cipher.decrypt_unauthenticated_hazmat(&mut buffer[..5]);
cipher.decrypt_unauthenticated_hazmat(&mut buffer[5..10]);
cipher.decrypt_unauthenticated_hazmat(&mut buffer[10..]);
let res = cipher.finish(&tag);

assert_eq!(res, Ok(()));
assert_eq!(buffer, *plaintext);

// Decrypting the ciphertext with tampered associated data should fail
let mut cipher = Eax::<Aes256, Decrypt>::with_key_and_nonce(key, nonce);

cipher.update_assoc(b"tampered");
cipher.decrypt_unauthenticated_hazmat(&mut cloned);
let res = cipher.finish(&tag);

assert_eq!(res, Err(Error));

Implementations

impl<Cipher, Op> Eax<Cipher, Op> where
    Cipher: BlockCipher<BlockSize = U16> + NewBlockCipher + Clone,
    Cipher::ParBlocks: ArrayLength<Block<Cipher>>,
    Op: CipherOp, 

pub fn with_key_and_nonce(
    key: &Key<Cipher>,
    nonce: &Nonce<Cipher::BlockSize>
) -> Self

Creates a stateful EAX instance that is capable of processing both the associated data and the plaintext in an "on-line" fashion.

pub fn update_assoc(&mut self, aad: &[u8])

Process the associated data (AD).

pub fn tag_clone(&self) -> Tag

Derives the tag from the encrypted/decrypted message so far.

If the encryption/decryption operation is finished, finish method must be called instead.

impl<Cipher> Eax<Cipher, Encrypt> where
    Cipher: BlockCipher<BlockSize = U16> + NewBlockCipher + Clone,
    Cipher::ParBlocks: ArrayLength<Block<Cipher>>, 

pub fn encrypt(&mut self, msg: &mut [u8])

Applies encryption to the plaintext.

#[must_use = "tag must be saved to later verify decrypted data"]pub fn finish(self) -> Tag

Finishes the encryption stream, returning the derived tag.

This must be called after the stream encryption is finished.

impl<Cipher> Eax<Cipher, Decrypt> where
    Cipher: BlockCipher<BlockSize = U16> + NewBlockCipher + Clone,
    Cipher::ParBlocks: ArrayLength<Block<Cipher>>, 

pub fn decrypt_unauthenticated_hazmat(&mut self, msg: &mut [u8])

Applies decryption to the ciphertext without verifying the authenticity of decrypted message.

To correctly verify the authenticity, use the finish associated function.

☣️ BEWARE! ☣️

This is a low-level operation that simultaneously decrypts the data and calculates an intermediate tag used to verify the authenticity of the data (used when the online decryption is finished).

Because this is exposed solely as a building block operation, an extra care must be taken when using this function.

Specifically, when misused this may be vulnerable to a chosen-ciphertext attack (IND-CCA). Due to online nature of this function, the decryption and partial tag calculation is done simultaneously, per chunk. An attacker might choose ciphertexts to be decrypted and, while the final decryption will fail because the attacker can't calculate tag authenticating the message, obtained decryptions may leak information about the decryption scheme (e.g. leaking parts of the secret key).

#[must_use = "decrypted data stream must be verified for authenticity"]pub fn finish(self, expected: &Tag) -> Result<(), Error>

Finishes the decryption stream, verifying whether the associated and decrypted data stream has not been tampered with.

This must be called after the stream decryption is finished.