Crate crypto_secretbox
source ·Expand description
§RustCrypto: crypto_secretbox
crypto_secretbox
is an authenticated symmetric encryption cipher
amenable to fast, constant-time implementations in software, combining either the
Salsa20 stream cipher (with XSalsa20 192-bit nonce extension) or
ChaCha20 stream cipher with the Poly1305 universal hash function,
which acts as a message authentication code.
This algorithm has largely been replaced by the newer IETF variant of 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.
USE AT YOUR OWN RISK!
§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 crypto_secretbox::{
aead::{Aead, AeadCore, 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 crypto_secretbox::{
aead::{AeadCore, 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 crypto_secretbox::XSalsa20Poly1305;
use crypto_secretbox::aead::{AeadCore, AeadInPlace, KeyInit, generic_array::GenericArray};
use crypto_secretbox::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§
Modules§
- Type aliases for many constants.
Structs§
- Error type.
- The NaCl
crypto_secretbox
authenticated symmetric encryption primitive, generic
Traits§
- Authenticated Encryption with Associated Data (AEAD) algorithm core trait.
- In-place stateless AEAD trait.
- Key derivation function: trait for abstracting over HSalsa20 and HChaCha20.
- Types which can be initialized from key.
- Types which use key for initialization.
Type Aliases§
- Key type.
- Nonce type.
- Poly1305 tag.
crypto_secretbox
instantiated with the XSalsa20 stream cipher.