[][src]Crate aes_gcm_siv

AES-GCM-SIV (RFC 8452): high-performance Authenticated Encryption with Associated Data (AEAD) cipher which also provides nonce reuse misuse resistance.

Suitable as a general purpose symmetric encryption cipher, AES-GCM-SIV also removes many of the "sharp edges" of AES-GCM, providing significantly better security bounds while simultaneously eliminating the most catastrophic risks of nonce reuse that exist in AES-GCM.

Decryption performance is equivalent to AES-GCM. Encryption is marginally slower.

See also:

Performance Notes

By default this crate will use software implementations of both AES and the POLYVAL universal hash function.

When targeting modern x86/x86_64 CPUs, use the following RUSTFLAGS to take advantage of high performance AES-NI and CLMUL CPU intrinsics:

RUSTFLAGS="-Ctarget-cpu=sandybridge -Ctarget-feature=+aes,+sse2,+sse4.1,+ssse3"

Security Warning

No security audits of this crate have ever been performed.

Some of this crate's dependencies were audited by by NCC Group as part of an audit of the aes-gcm crate, including the AES implementations (both AES-NI and a portable software implementation), as well as the polyval crate which is used as an authenticator. There were no significant findings.

All implementations contained in the crate are designed to execute in constant time, either by relying on hardware intrinsics (i.e. AES-NI and CLMUL on x86/x86_64), or using a portable implementation which is only constant time on processors which implement constant-time multiplication.

It is not suitable for use on processors with a variable-time multiplication operation (e.g. short circuit on multiply-by-zero / multiply-by-one, such as certain 32-bit PowerPC CPUs and some non-ARM microcontrollers).



Simple usage (allocating, no associated data):

use aes_gcm_siv::Aes256GcmSiv; // Or `Aes128GcmSiv`
use aead::{Aead, NewAead, generic_array::GenericArray};

let key = GenericArray::clone_from_slice(b"an example very very secret key.");
let aead = Aes256GcmSiv::new(key);

let nonce = GenericArray::from_slice(b"unique nonce"); // 96-bits; unique per message
let ciphertext = aead.encrypt(nonce, b"plaintext message".as_ref()).expect("encryption failure!");
let plaintext = aead.decrypt(nonce, ciphertext.as_ref()).expect("decryption failure!");
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 Aead::encrypt_in_place and Aead::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_gcm_siv::Aes256GcmSiv; // Or `Aes128GcmSiv`
use aead::{Aead, NewAead};
use aead::generic_array::{GenericArray, typenum::U128};
use aead::heapless::Vec;

let key = GenericArray::clone_from_slice(b"an example very very secret key.");
let aead = Aes256GcmSiv::new(key);

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

let mut buffer: Vec<u8, U128> = Vec::new();
buffer.extend_from_slice(b"plaintext message");

// Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
aead.encrypt_in_place(nonce, b"", &mut buffer).expect("encryption failure!");

// `buffer` now contains the message ciphertext
assert_ne!(&buffer, b"plaintext message");

// Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
aead.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
assert_eq!(&buffer, b"plaintext message");


pub use aead;



AES-GCM-SIV: Misuse-Resistant Authenticated Encryption Cipher (RFC 8452)



Maximum length of associated data (from RFC 8452 Section 6)


Maximum length of ciphertext (from RFC 8452 Section 6)


Maximum length of plaintext (from RFC 8452 Section 6)

Type Definitions


AES-GCM-SIV with a 128-bit key


AES-GCM-SIV with a 256-bit key