Expand description
AES-SIV (RFC 5297): Authenticated Encryption with Associated Data (AEAD) cipher which also provides nonce reuse misuse resistance.
Usage
Simple usage (allocating, no associated data):
use aes_siv::{
aead::{Aead, KeyInit, OsRng},
Aes256SivAead, Nonce // Or `Aes128SivAead`
};
let key = Aes256SivAead::generate_key(&mut OsRng);
let cipher = Aes256SivAead::new(&key);
let nonce = Nonce::from_slice(b"any unique nonce"); // 128-bits; 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 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_siv::{
aead::{AeadInPlace, KeyInit, OsRng, heapless::Vec},
Aes256SivAead, Nonce, // Or `Aes128SivAead`
};
let key = Aes256SivAead::generate_key(&mut OsRng);
let cipher = Aes256SivAead::new(&key);
let nonce = Nonce::from_slice(b"any unique nonce"); // 128-bits; unique per message
let mut buffer: Vec<u8, 128> = Vec::new(); // Note: buffer needs 16-bytes overhead for auth tag tag
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)?;
// `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)?;
assert_eq!(&buffer, b"plaintext message");
Re-exports
pub use aead;
Modules
Structs
Error type.
The SivAead
type wraps the more powerful Siv
interface in a more
commonly used Authenticated Encryption with Associated Data (AEAD) API,
which accepts a key, nonce, and associated data when encrypting/decrypting.
Traits
Authenticated Encryption with Associated Data (AEAD) algorithm core trait.
In-place stateless AEAD trait.
Types which can be initialized from key.
Types which use key for initialization.
Type Definitions
AES-PMAC-SIV in AEAD mode with 256-bit key size (128-bit security)
AES-CMAC-SIV in AEAD mode with 256-bit key size (128-bit security)
AES-PMAC-SIV in AEAD mode with 512-bit key size (256-bit security)
AES-CMAC-SIV in AEAD mode with 512-bit key size (256-bit security)
SIV AEAD modes based on CMAC
Key used by KeySizeUser
implementors.
AES-SIV nonces
pmac
SIV AEAD modes based on PMAC
AES-SIV tags (i.e. the Synthetic Initialization Vector value)