Struct chacha20poly1305::XChaCha20Poly1305

pub struct XChaCha20Poly1305 { /* fields omitted */ }

XChaCha20Poly1305 is a 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:

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

It is worth noting that libsodium's default "secretbox" algorithm is XSalsa20Poly1305, not XChaCha20Poly1305, and thus not compatible with this library.

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

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");

Methods

impl XChaCha20Poly1305

pub 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

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

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

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