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

Where possible the implementation uses constant-time hardware intrinsics, or otherwise falls back to an implementation which contains no secret-dependent branches or table lookups, however it's possible LLVM may insert such operations in certain scenarios.

Usage

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

let key = GenericArray::clone_from_slice(b"an example very very secret key.");
let aead = Aes256Gcm::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 the aead crate, you will receive an impl of aead::Buffer for the heapless::Vec type, which can then be passed as the buffer parameter to the in-place encrypt and decrypt methods.

In Cargo.toml, add:

[dependencies.aead]
version = "0.2"
default-features = false
features = ["heapless"]

[dependencies.aes-gcm]
version = "0.2"
default-features = false

Re-exports

pub use aead;

Structs

AesGcm

AES-GCM

Constants

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

Type Definitions

Aes128Gcm	AES-GCM with a 128-bit key
Aes256Gcm	AES-GCM with a 256-bit key
Tag	AES-GCM tags