[−][src]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 audit security 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 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 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 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 = 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 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");
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 |