[][src]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 the following ChaCha20Poly1305 variants:

  • XChaCha20Poly1305 - ChaCha20Poly1305 variant with an extended 192-bit (24-byte) nonce.
  • ChaCha8Poly1305 / ChaCha12Poly1305 - nonstandard, reduced round variants (gated under the reduced-round Cargo feature). See the Too Much Crypto paper for background and rationale on when these constructions shoudl be used. When in doubt, prefer ChaCha20Poly1305.

Performance Notes

By default this crate will use portable software implementations of the underlying ChaCha20 and Poly1305 ciphers it's based on.

When targeting modern x86/x86_64 CPUs, use the following RUSTFLAGS to take advantage of AVX2 acceleration:

RUSTFLAGS="-Ctarget-feature=+avx2"

Ideally target the haswell or skylake architectures as a baseline:

RUSTFLAGS="-Ctarget-cpu=haswell -Ctarget-feature=+avx2"

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

ChaCha12Poly1305

ChaCha12Poly1305 (reduced round variant) Authenticated Encryption with Additional Data (AEAD).

ChaCha20Poly1305

ChaCha20Poly1305 Authenticated Encryption with Additional Data (AEAD).

ChaCha8Poly1305

ChaCha8Poly1305 (reduced round variant) 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