Crate xsalsa20poly1305
source · [−]Expand description
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::{
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 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");
Re-exports
pub use aead;
Modules
Type aliases for many constants.
Structs
Error type.
XSalsa20Poly1305 (a.k.a. NaCl crypto_secretbox
) authenticated
encryption cipher.
Constants
Size of an XSalsa20Poly1305 key in bytes
Size of an XSalsa20Poly1305 nonce in bytes
Size of a Poly1305 tag in bytes
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.