Crate libcrux_aead 

This crate provides AEAD (Authenticated Encryption with Associate Data).

We currently support four AEAD algorithms:

• ChaCha20Poly1305
• XChaCha20Poly1305
• AES-GCM 128
• AES-GCM 256

These can either be used directly, using the chacha20poly1305, xchacha20poly1305, aesgcm128 and aesgcm256 submodules, or using the multiplexed API, which allows chosing the used algorithm dynamically at run time.

Static API

For example, to use the static API to encrypt something using ChaCha20Poly1305:

use libcrux_aead::chacha20poly1305::*;
use libcrux_traits::aead::typed_owned::Aead as _;
use libcrux_secrets::{Classify, ClassifyRef, Declassify, DeclassifyRef, U8};
let key_bytes = [0u8; 32].classify();
let tag_bytes = [0u8; TAG_LEN].classify();
let nonce_bytes = [123u8; NONCE_LEN].classify();

let msg: &[U8; MSG_LEN] = b"squeamish ossifrage".classify_ref();
let mut ciphertext = [0u8; MSG_LEN];
let mut tag = Tag::from(tag_bytes);

let key = Key::from(key_bytes);
let nonce = Nonce::from(nonce_bytes);

key.encrypt(&mut ciphertext, &mut tag, &nonce, &[/* no aad */], msg)
    .expect("Encryption error");

// Ciphertext and tag contain encrypted data
assert_eq!(
    ciphertext,
    [ 181, 223,  66, 115, 105, 181,  98, 178,
      247, 139, 196, 238, 169, 225, 143,  94,
      174, 123, 232 ]
);
assert_eq!(
    tag.as_ref().declassify_ref(),
    &[ 155, 112, 155, 212, 133, 38, 145, 115,
        27, 221, 245, 237, 125, 28,  22, 101 ]
);

And, for decrypting:

let mut plaintext = [0u8; MSG_LEN].classify();
let mut tag = Tag::from(tag_bytes);

let key = Key::from(key_bytes);
let nonce = Nonce::from(nonce_bytes);

key.decrypt(&mut plaintext, &nonce,  &[/* no aad */], &ciphertext, &tag)
    .expect("Decryption error");

assert_eq!( plaintext.declassify_ref(), b"squeamish ossifrage");

Multiplexed API

If you need to select the AEAD algorithm at runtime, you can use the multiplexed API. Here, the algorithm is selected through an enum variant, and the methods new_key, new_nonce etc. check that the lengths match that of the algorithm.

use libcrux_aead::*;
use libcrux_traits::aead::typed_refs::Aead as _;

let msg: &[U8; MSG_LEN] = b"squeamish ossifrage".classify_ref();
let mut ciphertext = [0u8; MSG_LEN];
let mut tag_bytes = [0u8; chacha20poly1305::TAG_LEN].classify();

let algo = Aead::ChaCha20Poly1305;
let key = algo.new_key(&key_bytes)
              .expect("key should have correct length");
let nonce = algo.new_nonce(&nonce_bytes)
                .expect("nonce should have correct length");
let tag = algo.new_tag_mut(&mut tag_bytes)
              .expect("tag should have correct length");

key.encrypt(&mut ciphertext, tag, nonce, &[/* no aad */], msg)
    .expect("Encryption error");

// Ciphertext and tag contain encrypted data
assert_eq!(
    ciphertext,
    [ 181, 223,  66, 115, 105, 181,  98, 178,
      247, 139, 196, 238, 169, 225, 143,  94,
      174, 123, 232 ]
);
assert_eq!(
    tag_bytes.declassify(),
    [ 155, 112, 155, 212, 133, 38, 145, 115,
       27, 221, 245, 237, 125, 28,  22, 101 ]
);

Decrypting works similar:

use libcrux_aead::*;
use libcrux_traits::aead::typed_refs::Aead as _;

let mut plaintext = [0u8; MSG_LEN].classify();

let algo = Aead::ChaCha20Poly1305;
let key = algo.new_key(&key_bytes)
              .expect("key should have correct length");
let nonce = algo.new_nonce(&nonce_bytes)
                .expect("nonce should have correct length");
let tag = algo.new_tag(& tag_bytes)
              .expect("tag should have correct length");

key.decrypt(&mut plaintext, nonce, &[/* no aad */], &ciphertext, tag)
    .expect("Decryption error");

// Ciphertext and tag contain encrypted data
assert_eq!(plaintext.declassify_ref(), b"squeamish ossifrage");

Modules

aesgcm128

aesgcm256

chacha20poly1305

xchacha20poly1305

Enums

Aead

A multiplexed AEAD, allowing algorithm selection at run time.

Type Aliases

KeyRef

A reference to a multiplexed AEAD key.

NonceRef

A reference to a multiplexed AEAD nonce.

TagMut

A mutable reference to a multiplexed AEAD tag.

TagRef

A reference to a multiplexed AEAD tag.