Skip to main content

Crate aes_gcm_siv

Crate aes_gcm_siv 

Source
Expand description

§RustCrypto: AES-GCM-SIV (Misuse-Resistant Authenticated Encryption Cipher)

crate Docs Apache2/MIT licensed Rust Version Project Chat Build Status

AES-GCM-SIV (RFC 8452) is a state-of-the-art high-performance Authenticated Encryption with Associated Data (AEAD) cipher which also provides nonce reuse misuse resistance.

Suitable as a general purpose symmetric encryption cipher, AES-GCM-SIV also removes many of the “sharp edges” of AES-GCM, providing significantly better security bounds while simultaneously eliminating the most catastrophic risks of nonce reuse that exist in AES-GCM.

Decryption performance is equivalent to AES-GCM. Encryption is marginally slower.

See also:

Documentation

§Security Warning

No security audits of this crate have ever been performed.

Some of this crate’s dependencies were audited by by NCC Group as part of an audit of the aes-gcm crate, including the AES implementations (both AES-NI and a portable software implementation), as well as the polyval crate which is used as an authenticator. There were no significant findings.

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

USE AT YOUR OWN RISK!

§License

Licensed under either of:

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

// NOTE: requires the `getrandom` feature is enabled

use aes_gcm_siv::{
    aead::{Aead, AeadCore, Generate, Key, KeyInit},
    Aes256GcmSiv, Nonce // Or `Aes128GcmSiv`
};

let key = Key::<Aes256GcmSiv>::generate();
let cipher = Aes256GcmSiv::new(&key);

let nonce = Nonce::generate(); // MUST be 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 AeadInOut::encrypt_in_place and AeadInOut::decrypt_in_place methods accept any type that impls the aead::Buffer trait which contains the plaintext for encryption or ciphertext for decryption.

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]), and enabling the bytes feature of this crate will provide an impl of aead::Buffer for bytes::BytesMut (re-exported from the aead crate as [aead::bytes::BytesMut]).

It can then be passed as the buffer parameter to the in-place encrypt and decrypt methods:

ⓘ
// NOTE: requires the `arrayvec` and `getrandom` features are enabled

use aes_gcm_siv::{
    aead::{AeadInOut, AeadCore, Buffer, Generate, Key, KeyInit, arrayvec::ArrayVec},
    Aes256GcmSiv, Nonce, // Or `Aes128GcmSiv`
};

let key = Key::<Aes256GcmSiv>::generate();
let cipher = Aes256GcmSiv::new(&key);

let nonce = Nonce::generate(); // 96-bits; unique per message
let mut buffer: ArrayVec<u8, 128> = ArrayVec::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.as_ref(), 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.as_ref(), b"plaintext message");

Re-exports§

pub use aead;
pub use aes;

Structs§

AesGcmSiv
AES-GCM-SIV: Misuse-Resistant Authenticated Encryption Cipher (RFC 8452).
Error
Error type.

Constants§

A_MAX
Maximum length of associated data (from RFC8452 § 6).
C_MAX
Maximum length of ciphertext (from RFC8452 § 6).
P_MAX
Maximum length of plaintext (from RFC8452 § 6).

Traits§

AeadCore
Authenticated Encryption with Associated Data (AEAD) algorithm.
AeadInOut
In-place and inout AEAD trait which handles the authentication tag as a return value/separate parameter.
KeyInit
Types which can be initialized from a key.
KeySizeUser
Types which use key for initialization.

Type Aliases§

Aes128GcmSiv
AES-GCM-SIV with a 128-bit key.
Aes256GcmSiv
AES-GCM-SIV with a 256-bit key.
Key
Key used by KeySizeUser implementors.
Nonce
AES-GCM-SIV nonces.
Tag
AES-GCM-SIV tags.