Crate aes_siv

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

• siv
  The Synthetic Initialization Vector (SIV) misuse-resistant block cipher mode of operation (RFC 5297).

Structs

• Error
  Error type.
• SivAead
  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

• AeadCore
  Authenticated Encryption with Associated Data (AEAD) algorithm core trait.
• AeadInPlace
  In-place stateless AEAD trait.
• KeyInit
  Types which can be initialized from key.
• KeySizeUser
  Types which use key for initialization.

Type Aliases

• Aes128PmacSivAeadpmac
  AES-PMAC-SIV in AEAD mode with 256-bit key size (128-bit security)
• Aes128SivAead
  AES-CMAC-SIV in AEAD mode with 256-bit key size (128-bit security)
• Aes256PmacSivAeadpmac
  AES-PMAC-SIV in AEAD mode with 512-bit key size (256-bit security)
• Aes256SivAead
  AES-CMAC-SIV in AEAD mode with 512-bit key size (256-bit security)
• CmacSivAead
  SIV AEAD modes based on CMAC
• Key
  Key used by KeySizeUser implementors.
• Nonce
  AES-SIV nonces
• PmacSivAeadpmac
  SIV AEAD modes based on PMAC
• Tag
  AES-SIV tags (i.e. the Synthetic Initialization Vector value)