Crate chacha20poly1305

source ·
Expand description

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 contains pure Rust implementations of ChaCha20Poly1305 (with optional AVX2 acceleration) as well as the following variants thereof:

  • XChaCha20Poly1305 - ChaCha20Poly1305 variant with an extended 192-bit (24-byte) nonce.
  • [ChaCha8Poly1305] / [ChaCha12Poly1305] - non-standard, reduced-round variants (gated under the reduced-round Cargo feature). See the Too Much Crypto paper for background and rationale on when these constructions could be used. When in doubt, prefer ChaCha20Poly1305.
  • [XChaCha8Poly1305] / [XChaCha12Poly1305] - same as above, but with an extended 192-bit (24-byte) nonce.

Security Notes

This crate has received one security audit by NCC Group, with no significant findings. We would like to thank MobileCoin for funding the audit.

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 chacha20poly1305::{ChaCha20Poly1305, Key, Nonce}; // Or `XChaCha20Poly1305`
use chacha20poly1305::aead::{Aead, NewAead};

let key = Key::from_slice(b"an example very very secret key."); // 32-bytes
let cipher = ChaCha20Poly1305::new(key);

let nonce = Nonce::from_slice(b"unique nonce"); // 12-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 chacha20poly1305::{ChaCha20Poly1305, Key, Nonce}; // Or `XChaCha20Poly1305`
use chacha20poly1305::aead::{AeadInPlace, NewAead};
use chacha20poly1305::aead::heapless::Vec;

let key = Key::from_slice(b"an example very very secret key.");
let cipher = ChaCha20Poly1305::new(key);

let nonce = Nonce::from_slice(b"unique nonce"); // 128-bits; 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");

XChaCha20Poly1305

ChaCha20Poly1305 variant with an extended 192-bit (24-byte) nonce.

The xchacha20 Cargo feature must be enabled in order to use this (which it is by default).

The construction is an adaptation of the same techniques used by XSalsa20 as described in the paper “Extending the Salsa20 Nonce” to the 96-bit nonce variant of ChaCha20, which derive a separate subkey/nonce for each extended nonce:

https://cr.yp.to/snuffle/xsalsa-20081128.pdf

No authoritative specification exists for XChaCha20Poly1305, however the construction has “rough consensus and running code” in the form of several interoperable libraries and protocols (e.g. libsodium, WireGuard) and is documented in an (expired) IETF draft, which also applies the proof from the XSalsa20 paper to the construction in order to demonstrate that XChaCha20 is secure if ChaCha20 is secure (see Section 3.1):

https://tools.ietf.org/html/draft-arciszewski-xchacha-03

It is worth noting that NaCl/libsodium’s default “secretbox” algorithm is XSalsa20Poly1305, not XChaCha20Poly1305, and thus not compatible with this library. If you are interested in that construction, please see the xsalsa20poly1305 crate:

https://docs.rs/xsalsa20poly1305/

Usage

use chacha20poly1305::{XChaCha20Poly1305, Key, XNonce};
use chacha20poly1305::aead::{Aead, NewAead};

let key = Key::from_slice(b"an example very very secret key."); // 32-bytes
let aead = XChaCha20Poly1305::new(key);

let nonce = XNonce::from_slice(b"extra long unique nonce!"); // 24-bytes; unique
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");

Re-exports

Structs

  • ChaChaPoly1305
    Generic ChaCha+Poly1305 Authenticated Encryption with Additional Data (AEAD) construction.

Type Definitions

  • ChaCha20Poly1305
    ChaCha20Poly1305 Authenticated Encryption with Additional Data (AEAD).
  • Key
    Key type (256-bits/32-bytes).
  • Nonce
    Nonce type (96-bits/12-bytes).
  • Tag
    Poly1305 tag.
  • XChaCha20Poly1305
    XChaCha20Poly1305 Authenticated Encryption with Additional Data (AEAD).
  • XNonce
    XNonce type (192-bits/24-bytes).