Crate aes256ctr_poly1305aes

source ·
Expand description

Aes256CtrPoly1305Aes is an Authenticated Encryption with Associated Data (AEAD) cipher amenable to fast, constant-time implementations in software, based on the AES256-CTR stream cipher and the [Poly1305-AES MAC] 4 which uses the Poly1305 universal hash function in combination with the AES-128 block cipher.

A lot code is copied from the chacha20poly1305 crate

This crate contains pure Rust implementations of Aes256CtrPoly1305Aes (with optional AVX2 acceleration) as well as the following variants thereof:

All implementations contained in the crate are designed to execute in constant time, either by relying on hardware intrinsics (i.e. AVX2 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).

Usage

use aes256ctr_poly1305aes::{Aes256CtrPoly1305Aes, Key, Nonce};
use aes256ctr_poly1305aes::aead::Aead;

// 64 bytes key
let key = Key::from_slice(b"This is an example of a very secret key. Keep it always secret!!");
let cipher = Aes256CtrPoly1305Aes::new(key);

let nonce = Nonce::from_slice(b"my unique nonce!"); // 16-bytes; unique per message

let ciphertext = cipher.encrypt(nonce, b"plaintext message".as_ref())
    .expect("encryption failure!");  // NOTE: handle this error to avoid panics!
let plaintext = cipher.decrypt(nonce, ciphertext.as_ref())
    .expect("decryption failure!");  // NOTE: handle this error to avoid panics!

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 AeadInPlace::encrypt_in_place and AeadInPlace::decrypt_in_place methods accept any type that impls the aead::Buffer trait which contains the plaintext for encryption or ciphertext for decryption.

Note that if you enable the heapless feature of this crate, you will receive an impl of aead::Buffer for heapless::Vec (re-exported from the aead crate as [aead::heapless::Vec]), which can then be passed as the buffer parameter to the in-place encrypt and decrypt methods:

use aes256ctr_poly1305aes::{Aes256CtrPoly1305Aes, Key, Nonce};
use aes256ctr_poly1305aes::aead::{AeadInPlace, NewAead};
use aes256ctr_poly1305aes::aead::heapless::Vec;

// 64 bytes key
let key = Key::from_slice(b"This is an example of a very secret key. Keep it always secret!!");
let cipher = Aes256CtrPoly1305Aes::new(key);

let nonce = Nonce::from_slice(b"my unique nonce!"); // 16-bytes; unique per message

let mut buffer: Vec<u8, 128> = Vec::new();
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).expect("encryption failure!");

// `buffer` now contains the message ciphertext
assert_ne!(&buffer, b"plaintext message");

// Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
cipher.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
assert_eq!(&buffer, b"plaintext message");

Re-exports

Modules

  • cipher 🔒
    Core AEAD cipher implementation a StreamCipher and Poly1305.

Structs

  • Aes256CtrPoly1305Aes
    Authenticated Encryption with Additional Data (AEAD) using AES256-CTR and Poly1305-AES.

Type Aliases

  • Aes256Ctr 🔒
  • Key
    Key type (512-bits/64-bytes).
  • Nonce
    Nonce type (128-bits/16-bytes).
  • Tag
    Poly1305 tag.