aws_lc_rs

Module 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 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§

Macros§

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§

Constants§

Traits§