Crate xsalsa20poly1305

source ·
Expand description

RustCrypto: XSalsa20Poly1305

crate Docs Apache2/MIT licensed Rust Version Project Chat Build Status

🚨 DEPRECATED! 🚨

Please switch to the crypto_secretbox crate.

This crate is deprecated and will not receive further updates.

About

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.

Documentation

Security Notes

This crate has received one security audit by Cure53 (version 0.8.0), with no significant findings. We would like to thank Threema for funding the audit.

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.

Usage

use xsalsa20poly1305::{
    aead::{Aead, KeyInit, OsRng},
    XSalsa20Poly1305, Nonce
};

let key = XSalsa20Poly1305::generate_key(&mut OsRng);
let cipher = XSalsa20Poly1305::new(&key);
let nonce = XSalsa20Poly1305::generate_nonce(&mut OsRng); // 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 xsalsa20poly1305::{
    aead::{AeadInPlace, KeyInit, OsRng, heapless::Vec},
    XSalsa20Poly1305, Nonce,
};

let key = XSalsa20Poly1305::generate_key(&mut OsRng);
let cipher = XSalsa20Poly1305::new(&key);
let nonce = XSalsa20Poly1305::generate_nonce(&mut OsRng); // 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");
use xsalsa20poly1305::XSalsa20Poly1305;
use xsalsa20poly1305::aead::{AeadInPlace, KeyInit, generic_array::GenericArray};
use xsalsa20poly1305::aead::heapless::Vec;

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

Similarly, enabling the arrayvec feature of this crate will provide an impl of aead::Buffer for arrayvec::ArrayVec (re-exported from the aead crate as aead::arrayvec::ArrayVec).

Re-exports

Modules

  • consts
    Type aliases for many constants.

Structs

  • Error
    Error type.
  • 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

Traits

  • AeadCore
    Authenticated Encryption with Associated Data (AEAD) algorithm core trait.
  • AeadInPlace
    In-place stateless AEAD trait.
  • KeyInit
    Types which can be initialized from key.
  • KeySizeUser
    Types which use key for initialization.

Type Definitions