Module aws_lc_rs::aead

source ·
Expand description

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 compatability 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);

Modules§

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.
  • RandomizedNonceKey
    AEAD Cipher key using a randomized nonce.
  • SealingKey
    An AEAD key for encrypting and signing (“sealing”), bound to a nonce sequence.
  • 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_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§