# Crate chacha20poly1305

source · [−]## Expand description

## RustCrypto: ChaCha20Poly1305

Pure Rust implementation of **ChaCha20Poly1305** (RFC 8439): 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.

### About

ChaCha20Poly1305 is notable for being simple and fast when implemented in pure software. The underlying ChaCha20 stream cipher uses a simple combination of add, rotate, and XOR instructions (a.k.a. “ARX”), and the Poly1305 hash function is likewise extremely simple.

While it hasn’t received approval from certain standards bodies (i.e. NIST) the algorithm is widely used and deployed. Notably it’s mandatory to implement in the Transport Layer Security (TLS) protocol. The underlying ChaCha20 cipher is also widely used as a cryptographically secure random number generator, including internal use by the Rust standard library.

### 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).

### License

Licensed under either of:

at your option.

#### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

### Supported Algorithms

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.

## Usage

```
use chacha20poly1305::{
aead::{Aead, AeadCore, KeyInit, OsRng},
ChaCha20Poly1305, Nonce
};
let key = ChaCha20Poly1305::generate_key(&mut OsRng);
let cipher = ChaCha20Poly1305::new(&key);
let nonce = ChaCha20Poly1305::generate_nonce(&mut OsRng); // 96-bits; unique per message
let ciphertext = cipher.encrypt(&nonce, b"plaintext message".as_ref())?;
let plaintext = cipher.decrypt(&nonce, ciphertext.as_ref())?;
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::{
aead::{AeadCore, AeadInPlace, KeyInit, OsRng, heapless::Vec},
ChaCha20Poly1305, Nonce,
};
let key = ChaCha20Poly1305::generate_key(&mut OsRng);
let cipher = ChaCha20Poly1305::new(&key);
let nonce = ChaCha20Poly1305::generate_nonce(&mut OsRng); // 96-bits; unique per message
let mut buffer: Vec<u8, 128> = Vec::new(); // Note: buffer needs 16-bytes overhead for auth tag
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)?;
// `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)?;
assert_eq!(&buffer, b"plaintext message");
```

`XChaCha20Poly1305`

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

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::{
aead::{Aead, AeadCore, KeyInit, OsRng},
XChaCha20Poly1305, XNonce
};
let key = XChaCha20Poly1305::generate_key(&mut OsRng);
let cipher = XChaCha20Poly1305::new(&key);
let nonce = XChaCha20Poly1305::generate_nonce(&mut OsRng); // 192-bits; unique per message
let ciphertext = cipher.encrypt(&nonce, b"plaintext message".as_ref())?;
let plaintext = cipher.decrypt(&nonce, ciphertext.as_ref())?;
assert_eq!(&plaintext, b"plaintext message");
```

## Re-exports

`pub use aead;`

## Modules

Type aliases for many constants.

## Structs

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

Error type.

## Traits

Authenticated Encryption with Associated Data (AEAD) algorithm core trait.

In-place stateless AEAD trait.

Types which can be initialized from key.

Types which use key for initialization.

## Type Definitions

`reduced-round`

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

`reduced-round`

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

ChaCha20Poly1305 Authenticated Encryption with Additional Data (AEAD).

Key type (256-bits/32-bytes).

Nonce type (96-bits/12-bytes).

Poly1305 tag.

`reduced-round`

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

`reduced-round`

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

XChaCha20Poly1305 Authenticated Encryption with Additional Data (AEAD).

XNonce type (192-bits/24-bytes).