Crate aes_siv 

RustCrypto: AES-SIV (Misuse-Resistant Authenticated Encryption Cipher)

AES-SIV (RFC 5297) is an Authenticated Encryption with Associated Data (AEAD) cipher which also provides nonce reuse misuse resistance.

Documentation

Security Warning

No security audits of this crate have ever been performed, and it has not been thoroughly assessed to ensure its operation is constant-time on common CPU architectures.

USE AT YOUR OWN RISK!

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Usage

Simple usage (allocating, no associated data):

// NOTE: requires the `getrandom` feature is enabled

use aes_siv::{
    aead::{Aead, AeadCore, Generate, Key, KeyInit},
    Aes256SivAead, Nonce // Or `Aes128SivAead`
};

let key = Key::<Aes256SivAead>::generate();
let cipher = Aes256SivAead::new(&key);

let nonce = Nonce::generate(); // MUST be 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 AeadInOut::encrypt_in_place and AeadInOut::decrypt_in_place methods accept any type that impls the aead::Buffer trait which contains the plaintext for encryption or ciphertext for decryption.

Enabling the arrayvec feature of this crate will provide an impl of aead::Buffer for arrayvec::ArrayVec (re-exported from the aead crate as aead::arrayvec::ArrayVec), and enabling the bytes feature of this crate will provide an impl of aead::Buffer for bytes::BytesMut (re-exported from the aead crate as aead::bytes::BytesMut).

It can then be passed as the buffer parameter to the in-place encrypt and decrypt methods:

// NOTE: requires the `arrayvec` and `getrandom` features are enabled

use aes_siv::{
    aead::{AeadCore, AeadInOut, Generate, Key, KeyInit, arrayvec::ArrayVec},
    Aes256SivAead, Nonce, // Or `Aes128SivAead`
};

let key = Key::<Aes256SivAead>::generate();
let cipher = Aes256SivAead::new(&key);

let nonce = Nonce::generate(); // MUST be unique per message
let mut buffer: ArrayVec<u8, 128> = ArrayVec::new(); // Note: buffer needs 16-bytes overhead for auth tag
buffer.try_extend_from_slice(b"plaintext message").unwrap();

// 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.as_ref(), 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.as_ref(), b"plaintext message");

Re-exports

pub use aead;

Modules

siv

The Synthetic Initialization Vector (SIV) misuse-resistant block cipher mode of operation (RFC 5297). The interface is based on the Rogaway paper.

Structs

Error

Error type.

SivAead

Convenience wrapper around Siv interface.

Traits

AeadCore

Authenticated Encryption with Associated Data (AEAD) algorithm.

AeadInOut

In-place and inout AEAD trait which handles the authentication tag as a return value/separate parameter.

KeyInit

Types which can be initialized from a 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)