Crate chacha20poly1305

ChaCha20Poly1305 (RFC 8439) is an Authenticated Encryption with Associated Data (AEAD) cipher amenable to fast, constant-time implementations in software, based on the ChaCha20 stream cipher and Poly1305 universal hash function.

This crate also contains an implementation of XChaCha20Poly1305 - a variant of ChaCha20Poly1305 with an extended 192-bit (24-byte) nonce.

Security Warning

No security audits of this crate have ever been performed, and it has not been thoroughly assessed to ensure its operation is constant-time on common CPU architectures.

Where possible the implementation uses constant-time hardware intrinsics, or otherwise falls back to an implementation which contains no secret-dependent branches or table lookups, however it's possible LLVM may insert such operations in certain scenarios.

Usage

use chacha20poly1305::ChaCha20Poly1305; // Or `XChaCha20Poly1305`
use aead::{Aead, NewAead, generic_array::GenericArray};

let key = GenericArray::clone_from_slice(b"an example very very secret key."); // 32-bytes
let aead = ChaCha20Poly1305::new(key);

let nonce = GenericArray::from_slice(b"unique nonce"); // 12-bytes; unique per message
let ciphertext = aead.encrypt(nonce, b"plaintext message".as_ref()).expect("encryption failure!");
let plaintext = aead.decrypt(nonce, ciphertext.as_ref()).expect("decryption failure!");
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 Aead::encrypt_in_place and Aead::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 chacha20poly1305::ChaCha20Poly1305; // Or `XChaCha20Poly1305`
use aead::{Aead, NewAead};
use aead::generic_array::{GenericArray, typenum::U128};
use aead::heapless::Vec;

let key = GenericArray::clone_from_slice(b"an example very very secret key.");
let aead = ChaCha20Poly1305::new(key);

let nonce = GenericArray::from_slice(b"unique nonce"); // 128-bits; unique per message

let mut buffer: Vec<u8, U128> = Vec::new();
buffer.extend_from_slice(b"plaintext message");

// Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
aead.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
aead.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
assert_eq!(&buffer, b"plaintext message");

Re-exports

pub use aead;

Structs

ChaCha20Poly1305	ChaCha20Poly1305 Authenticated Encryption with Additional Data (AEAD).
XChaCha20Poly1305	XChaCha20Poly1305 is a ChaCha20Poly1305 variant with an extended 192-bit (24-byte) nonce. The xchacha20poly1305 Cargo feature must be enabled in order to use this (which it is by default).

Type Definitions

Tag	Poly1305 tags