Crate aes_gcm

RustCrypto: AES-GCM

Pure Rust implementation of the AES-GCM Authenticated Encryption with Associated Data (AEAD) cipher.

Documentation

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

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

use aes_gcm::{
    aead::{Aead, AeadCore, KeyInit, OsRng},
    Aes256Gcm, Nonce, Key // Or `Aes128Gcm`
};

// The encryption key can be generated randomly:
let key = Aes256Gcm::generate_key(OsRng);

// Transformed from a byte array:
let key: &[u8; 32] = &[42; 32];
let key: &Key<Aes256Gcm> = key.into();

// Note that you can get byte array from slice using the `TryInto` trait:
let key: &[u8] = &[42; 32];
let key: [u8; 32] = key.try_into()?;

// Alternatively, the key can be transformed directly from a byte slice
// (panicks on length mismatch):
let key = Key::<Aes256Gcm>::from_slice(key);

let cipher = Aes256Gcm::new(&key);
let nonce = Aes256Gcm::generate_nonce(&mut OsRng); // 96-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_gcm::{
    aead::{AeadCore, AeadInPlace, KeyInit, OsRng, heapless::Vec},
    Aes256Gcm, Nonce, // Or `Aes128Gcm`
};

let key = Aes256Gcm::generate_key(&mut OsRng);
let cipher = Aes256Gcm::new(&key);
let nonce = Aes256Gcm::generate_nonce(&mut OsRng); // 96-bits; unique per message

let mut buffer: Vec<u8, 128> = Vec::new(); // Note: buffer needs 16-bytes overhead for auth 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");

Similarly, 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]).

Re-exports

• pub use aead;
• pub use aes;

Modules

• private 🔒

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

• 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.
• TagSize
  Trait implemented for valid tag sizes, i.e. [U12][consts::U12], [U13][consts::U13], [U14][consts::U14], [U15][consts::U15] and [U16][consts::U16].

Type Aliases

• Aes128Gcm
  AES-GCM with a 128-bit key and 96-bit nonce.
• Aes256Gcm
  AES-GCM with a 256-bit key and 96-bit nonce.
• Block 🔒
  AES block.
• Ctr32BE 🔒
  Counter mode with a 32-bit big endian counter.
• Key
  Key used by KeySizeUser implementors.
• Nonce
  AES-GCM nonces.
• Tag
  AES-GCM tags.