Crate aes_gcm

AES-GCM: Authenticated Encryption and Associated Data (AEAD) cipher based on AES in Galois/Counter Mode.

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 Notes

This crate has received one security audit by NCC Group, with no significant findings. We would like to thank MobileCoin for funding the audit.

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).

Usage

Simple usage (allocating, no associated data):

use aes_gcm::Aes256Gcm; // Or `Aes128Gcm`
use aes_gcm::aead::{Aead, NewAead, generic_array::GenericArray};

let key = GenericArray::from_slice(b"an example very very secret key.");
let cipher = Aes256Gcm::new(key);

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

let ciphertext = cipher.encrypt(nonce, b"plaintext message".as_ref())
    .expect("encryption failure!"); // NOTE: handle this error to avoid panics!

let plaintext = cipher.decrypt(nonce, ciphertext.as_ref())
    .expect("decryption failure!"); // NOTE: handle this error to avoid panics!

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_gcm::Aes256Gcm; // Or `Aes128Gcm`
use aes_gcm::aead::{AeadInPlace, NewAead, generic_array::GenericArray};
use aes_gcm::aead::heapless::{Vec, consts::U128};

let key = GenericArray::from_slice(b"an example very very secret key.");
let cipher = Aes256Gcm::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
cipher.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
cipher.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
assert_eq!(&buffer, b"plaintext message");

Re-exports

pub use aead;

pub use aes;

Structs

AesGcm	AES-GCM: generic over an underlying AES implementation and nonce size.
Error	Error type.

Constants

A_MAX	Maximum length of associated data
C_MAX	Maximum length of ciphertext
P_MAX	Maximum length of plaintext

Traits

AeadInPlace	In-place stateless AEAD trait.
NewAead	Instantiate either a stateless Aead or stateful AeadMut algorithm.

Type Definitions

Aes128Gcm	aes AES-GCM with a 128-bit key and 96-bit nonce
Aes256Gcm	aes AES-GCM with a 256-bit key and 96-bit nonce
Tag	AES-GCM tags