Module aead

Authenticated Encryption with Associated Data (AEAD).

See Authenticated encryption: relations among notions and analysis of the generic composition paradigm for an introduction to the concept of AEADs.

Randomized Nonce API

RandomizedNonceKey provides a simplified API interface that doesn’t require the caller to handle construction of a NonceSequence or Nonce values themselves.

use aws_lc_rs::aead::{Aad, RandomizedNonceKey, AES_128_GCM};

let key_bytes = &[
    0xa5, 0xf3, 0x8d, 0x0d, 0x2d, 0x7c, 0x48, 0x56, 0xe7, 0xf3, 0xc3, 0x63, 0x0d, 0x40, 0x5b,
    0x9e,
];

// Create AES-128-GCM key
let key = RandomizedNonceKey::new(&AES_128_GCM, key_bytes)?;

let message = "test message";
let mut in_out = Vec::from(message);

// Seal the plaintext message (in_out) and append the tag to the ciphertext.
// The randomized nonce used for encryption will be returned.
let nonce = key.seal_in_place_append_tag(Aad::empty(), &mut in_out)?;

// Open the ciphertext message (in_out), using the provided nonce, and validating the tag.
let plaintext = key.open_in_place(nonce, Aad::empty(), &mut in_out)?;

assert_eq!(message.as_bytes(), plaintext);

TLS AEAD APIs

Systems developers creating TLS protocol implementations should use TlsRecordSealingKey and TlsRecordOpeningKey respectively for AEAD.

Nonce Sequence APIs

The UnboundKey, OpeningKey, SealingKey, and LessSafeKey types are the AEAD API’s provided for compatibility with the original ring API.

Users should prefer RandomizedNonceKey which provides a simplified experience around Nonce construction.

use aws_lc_rs::aead::{
    nonce_sequence, Aad, BoundKey, OpeningKey, SealingKey, UnboundKey, AES_128_GCM,
};
use aws_lc_rs::rand;
use aws_lc_rs::test::from_hex;

let plaintext = "plaintext value";

// Generate random bytes for secret key
let mut key_bytes = [0u8; 16];
rand::fill(&mut key_bytes).expect("Unable to generate key");

// Contextual information must match between encryption and decryption
let aad_content = "aws-lc-rs documentation";
let sequence_id = 0xabcdef01u32.to_be_bytes();

// Buffer containing plaintext. This will be modified to contain the ciphertext.
let mut in_out_buffer = Vec::from(plaintext);

// Construct a SealingKey for encryption
let unbound_key = UnboundKey::new(&AES_128_GCM, &key_bytes).unwrap();
let nonce_sequence = nonce_sequence::Counter64Builder::new()
    .identifier(sequence_id)
    .build();
let mut sealing_key = SealingKey::new(unbound_key, nonce_sequence);

// Encrypt a value using the SealingKey
let aad = Aad::from(aad_content);
sealing_key
    .seal_in_place_append_tag(aad, &mut in_out_buffer)
    .expect("Encryption failed");

// The buffer now contains the ciphertext followed by a "tag" value.
let plaintext_len = in_out_buffer.len() - AES_128_GCM.tag_len();

// Construct an OpeningKey for decryption
let unbound_key = UnboundKey::new(&AES_128_GCM, &key_bytes).unwrap();
let nonce_sequence = nonce_sequence::Counter64Builder::new()
    .identifier(sequence_id)
    .build();
let mut opening_key = OpeningKey::new(unbound_key, nonce_sequence);

// Decrypt the value using the OpeningKey
let aad = Aad::from(aad_content);
opening_key
    .open_in_place(aad, &mut in_out_buffer)
    .expect("Decryption failed");

let decrypted_plaintext = core::str::from_utf8(&in_out_buffer[0..plaintext_len]).unwrap();

assert_eq!(plaintext, decrypted_plaintext);

Prepared Nonce API’s with Nonce Sequence

If you prefer to use the NonceSequence based API’s, and need to know the Nonce explicit nonce used for a cryptographic key operation operation, then SealingKeyPreparedNonce and OpeningKeyPreparedNonce are available to you.

use aws_lc_rs::aead::{
    nonce_sequence::Counter32Builder, Aad, BoundKey, OpeningKey, SealingKey, UnboundKey,
    AES_128_GCM,
};
use std::vec::Vec;

let key_bytes = &[
    0xa5, 0xf3, 0x8d, 0x0d, 0x2d, 0x7c, 0x48, 0x56, 0xe7, 0xf3, 0xc3, 0x63, 0x0d, 0x40, 0x5b,
    0x9e,
];

// Create AES-128-GCM SealingKey
let mut sealing_key = SealingKey::new(
    UnboundKey::new(&AES_128_GCM, key_bytes)?,
    Counter32Builder::new()
        .identifier([0, 1, 2, 3, 4, 5, 6, 7])
        .build(),
);

// Create AES-128-GCM OpeningKey
let mut opening_key = OpeningKey::new(
    UnboundKey::new(&AES_128_GCM, key_bytes)?,
    Counter32Builder::new()
        .identifier([0, 1, 2, 3, 4, 5, 6, 7])
        .build(),
);

let message = "test message";
let mut in_out = Vec::from(message);

// Create a SealingKeyPreparedNonce which consumes a nonce from the underlying sequence
let seal_prepared_nonce = sealing_key.prepare_nonce()?;

// Query the nonce that will be used for our seal operation with our prepared nonce
let seal_nonce_bytes = Vec::from(seal_prepared_nonce.nonce().as_ref());

// Use the prepared nonce and seal the plaintext
seal_prepared_nonce.seal_in_place_append_tag(Aad::empty(), &mut in_out)?;

// Create a OpeningKeyPreparedNonce which consumes a nonce from the underlying sequence
let open_prepared_nonce = opening_key.prepare_nonce()?;

// Query the nonce that will be used for our seal operation with our prepared nonce
let open_nonce_bytes = Vec::from(open_prepared_nonce.nonce().as_ref());

// Since we initialized the Counter32Builder the same between both builders the nonce here
// will match the one from the opening key.
assert_eq!(seal_nonce_bytes.as_slice(), open_nonce_bytes.as_slice());

let plaintext = open_prepared_nonce.open_in_place(Aad::empty(), &mut in_out)?;

assert_eq!(message.as_bytes(), plaintext);

Modules

chacha20_poly1305_openssh

The chacha20-poly1305@openssh.com AEAD-ish construct.

nonce_sequence

Implementations of NonceSequence for use with BoundKeys.

quic

QUIC Header Protection.

Structs

Aad

The additionally authenticated data (AAD) for an opening or sealing operation. This data is authenticated but is not encrypted.

Algorithm

An AEAD Algorithm.

LessSafeKey

Immutable keys for use in situations where OpeningKey/SealingKey and NonceSequence cannot reasonably be used.

Nonce

A nonce for a single AEAD opening or sealing operation.

OpeningKey

An AEAD key for authenticating and decrypting (“opening”), bound to a nonce sequence.

OpeningKeyPreparedNonce

A key operation with a precomputed nonce from a key’s associated NonceSequence.

RandomizedNonceKey

AEAD Cipher key using a randomized nonce.

SealingKey

An AEAD key for encrypting and signing (“sealing”), bound to a nonce sequence.

SealingKeyPreparedNonce

A key operation with a precomputed nonce from a key’s associated NonceSequence.

Tag

An authentication tag.

TlsRecordOpeningKey

AEAD Encryption key used for TLS protocol record encryption.

TlsRecordSealingKey

AEAD Encryption key used for TLS protocol record encryption.

UnboundKey

An AEAD key without a designated role or nonce sequence.

Enums

TlsProtocolId

The Transport Layer Security (TLS) protocol version.

Constants

AES_128_GCM

AES-128 in GCM mode with 128-bit tags and 96 bit nonces.

AES_128_GCM_SIV

AES-128 in GCM mode with nonce reuse resistance, 128-bit tags and 96 bit nonces.

AES_192_GCM

AES-192 in GCM mode with 128-bit tags and 96 bit nonces.

AES_256_GCM

AES-256 in GCM mode with 128-bit tags and 96 bit nonces.

AES_256_GCM_SIV

AES-256 in GCM mode with nonce reuse resistance, 128-bit tags and 96 bit nonces.

CHACHA20_POLY1305

ChaCha20-Poly1305 as described in RFC 7539.

MAX_TAG_LEN

The maximum length of a tag for the algorithms in this module.

NONCE_LEN

All the AEADs we support use 96-bit nonces.

Traits

BoundKey

An AEAD key bound to a nonce sequence.

NonceSequence

A sequences of unique nonces.