[−][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 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
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 |