Struct chacha20poly1305::XChaCha20Poly1305

pub struct XChaCha20Poly1305 { /* fields omitted */ }

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

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;
use aead::{Aead, NewAead, generic_array::GenericArray};

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

let nonce = GenericArray::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");

Trait Implementations

impl Drop for XChaCha20Poly1305

fn drop(&mut self)

Executes the destructor for this type.

impl Clone for XChaCha20Poly1305

fn clone(&self) -> XChaCha20Poly1305

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl NewAead for XChaCha20Poly1305

type KeySize = U32

The size of the key array required by this algorithm.

fn new(key: GenericArray<u8, U32>) -> Self

Construct a new stateful instance for the given key.

impl Aead for XChaCha20Poly1305

type NonceSize = U24

The length of a nonce.

type TagSize = U16

The maximum length of the nonce.

type CiphertextOverhead = U0

The upper bound amount of additional space required to support a ciphertext vs. a plaintext.

fn encrypt_in_place_detached(
    &self,
    nonce: &GenericArray<u8, Self::NonceSize>,
    associated_data: &[u8],
    buffer: &mut [u8]
) -> Result<Tag, Error>

Encrypt the data in-place, returning the authentication tag

fn decrypt_in_place_detached(
    &self,
    nonce: &GenericArray<u8, Self::NonceSize>,
    associated_data: &[u8],
    buffer: &mut [u8],
    tag: &Tag
) -> Result<(), Error>

Decrypt the message in-place, returning an error in the event the provided authentication tag does not match the given ciphertext (i.e. ciphertext is modified/unauthentic)

fn encrypt<'msg, 'aad>(
    &self,
    nonce: &GenericArray<u8, Self::NonceSize>,
    plaintext: impl Into<Payload<'msg, 'aad>>
) -> Result<Vec<u8>, Error>

Encrypt the given plaintext payload, and return the resulting ciphertext as a vector of bytes.

fn encrypt_in_place(
    &self,
    nonce: &GenericArray<u8, Self::NonceSize>,
    associated_data: &[u8],
    buffer: &mut impl Buffer
) -> Result<(), Error>

Encrypt the given buffer containing a plaintext message in-place.

fn decrypt<'msg, 'aad>(
    &self,
    nonce: &GenericArray<u8, Self::NonceSize>,
    ciphertext: impl Into<Payload<'msg, 'aad>>
) -> Result<Vec<u8>, Error>

Decrypt the given ciphertext slice, and return the resulting plaintext as a vector of bytes.

fn decrypt_in_place(
    &self,
    nonce: &GenericArray<u8, Self::NonceSize>,
    associated_data: &[u8],
    buffer: &mut impl Buffer
) -> Result<(), Error>

Decrypt the message in-place, returning an error in the event the provided authentication tag does not match the given ciphertext.