pub struct Eax<Cipher, Op, M = U16> where
Cipher: BlockCipher<BlockSize = U16> + BlockEncrypt + Clone + KeyInit,
Op: CipherOp,
M: TagSize, { /* private fields */ }
Expand description
Online1 variant of the EAX mode.
This type is generic to support substituting alternative cipher implementations.
In contrast to Eax
, can be used in an online1 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}, cipher::generic_array::GenericArray};
use aes::Aes256;
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
sourceimpl<Cipher, Op, M> Eax<Cipher, Op, M> where
Cipher: BlockCipher<BlockSize = U16> + BlockEncrypt + Clone + KeyInit,
Op: CipherOp,
M: TagSize,
impl<Cipher, Op, M> Eax<Cipher, Op, M> where
Cipher: BlockCipher<BlockSize = U16> + BlockEncrypt + Clone + KeyInit,
Op: CipherOp,
M: TagSize,
sourcepub fn with_key_and_nonce(
key: &Key<Cipher>,
nonce: &Nonce<Cipher::BlockSize>
) -> Self
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.
sourcepub fn update_assoc(&mut self, aad: &[u8])
pub fn update_assoc(&mut self, aad: &[u8])
Process the associated data (AD).
sourceimpl<Cipher, M> Eax<Cipher, Encrypt, M> where
Cipher: BlockCipher<BlockSize = U16> + BlockEncrypt + Clone + KeyInit,
M: TagSize,
impl<Cipher, M> Eax<Cipher, Encrypt, M> where
Cipher: BlockCipher<BlockSize = U16> + BlockEncrypt + Clone + KeyInit,
M: TagSize,
sourceimpl<Cipher, M> Eax<Cipher, Decrypt, M> where
Cipher: BlockCipher<BlockSize = U16> + BlockEncrypt + Clone + KeyInit,
M: TagSize,
impl<Cipher, M> Eax<Cipher, Decrypt, M> where
Cipher: BlockCipher<BlockSize = U16> + BlockEncrypt + Clone + KeyInit,
M: TagSize,
sourcepub fn decrypt_unauthenticated_hazmat(&mut self, msg: &mut [u8])
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).
Auto Trait Implementations
impl<Cipher, Op, M> RefUnwindSafe for Eax<Cipher, Op, M> where
Cipher: RefUnwindSafe,
M: RefUnwindSafe,
Op: RefUnwindSafe,
impl<Cipher, Op, M> Send for Eax<Cipher, Op, M> where
Cipher: Send,
M: Send,
Op: Send,
impl<Cipher, Op, M> Sync for Eax<Cipher, Op, M> where
Cipher: Sync,
M: Sync,
Op: Sync,
impl<Cipher, Op, M> Unpin for Eax<Cipher, Op, M> where
Cipher: Unpin,
M: Unpin,
Op: Unpin,
impl<Cipher, Op, M> UnwindSafe for Eax<Cipher, Op, M> where
Cipher: UnwindSafe,
M: UnwindSafe,
Op: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more