Crate xsalsa20poly1305

XSalsa20Poly1305 (a.k.a. NaCl crypto_secretbox) is an authenticated encryption cipher amenable to fast, constant-time implementations in software, based on the Salsa20 stream cipher (with XSalsa20 192-bit nonce extension) and the Poly1305 universal hash function, which acts as a message authentication code.

This algorithm has largely been replaced by the newer ChaCha20Poly1305 (and the associated XChaCha20Poly1305) AEAD ciphers (RFC 8439), but is useful for interoperability with legacy NaCl-based protocols.

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

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

// 24-bytes; unique per message
// Use `xsalsa20poly1305::generate_nonce()` to randomly generate one
let nonce = GenericArray::from_slice(b"extra long unique nonce!");

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 xsalsa20poly1305::XSalsa20Poly1305;
use xsalsa20poly1305::aead::{AeadInPlace, NewAead, generic_array::GenericArray};
use xsalsa20poly1305::aead::heapless::{Vec, consts::U128};

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

let nonce = GenericArray::from_slice(b"extra long unique nonce!"); // 24-bytes; unique

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

Re-exports

pub use aead;

Structs

XSalsa20Poly1305

XSalsa20Poly1305 (a.k.a. NaCl crypto_secretbox) authenticated encryption cipher.

Constants

KEY_SIZE	Size of an XSalsa20Poly1305 key in bytes
NONCE_SIZE	Size of an XSalsa20Poly1305 nonce in bytes
TAG_SIZE	Size of a Poly1305 tag in bytes

Functions

generate_nonce

rand_core Generate a random nonce: every message MUST have a unique nonce!

Type Definitions

Key	Key type.
Nonce	EXtended Salsa20 nonce (192-bit/24-byte)
Tag	Poly1305 tags