MobileCoin: Oblivious AES-GCM

WARNING: You should use the aes-gcm crate, not this one. This crate is a patch/fork of the execellent RustCrypto crate to support a very, very niche use-case for MobileCoin, and as such it's maintenance and security are necessarily going to lag behind that of RustCrypto's crate.

lib.rs:

WARNING

You should use the aes-gcm crate, not this one. This crate is a patch/fork of the execellent RustCrypto crate to support a very, very niche use-case for MobileCoin, and as such it's maintenance and security are necessarily going to lag behind that of RustCrypto's crate.

Original README

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

fn main() -> Result<(), Box> {

use mc_oblivious_aes_gcm::{ aead::{Aead, KeyInit, OsRng}, Aes256Gcm, Nonce // Or Aes128Gcm };

let key = Aes256Gcm::generate_key(&mut OsRng); let cipher = Aes256Gcm::new(&key); let nonce = Nonce::from_slice(b"unique nonce"); // 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");

Ok(())

}

## 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 mc_oblivious_aes_gcm::{
    aead::{AeadInPlace, KeyInit, OsRng, heapless::Vec},
    Aes256Gcm, Nonce, // Or `Aes128Gcm`
};

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

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