[−][src]Crate chacha20poly1305
ChaCha20Poly1305
(RFC 8439) is an
Authenticated Encryption with Associated Data (AEAD)
cipher amenable to fast, constant-time implementations in software, based on
the ChaCha20 stream cipher and Poly1305 universal hash function.
This crate also contains the following ChaCha20Poly1305
variants:
XChaCha20Poly1305
- ChaCha20Poly1305 variant with an extended 192-bit (24-byte) nonce.ChaCha8Poly1305
/ChaCha12Poly1305
- nonstandard, reduced round variants (gated under thereduced-round
Cargo feature). See the Too Much Crypto paper for background and rationale on when these constructions shoudl be used. When in doubt, preferChaCha20Poly1305
.
Performance Notes
By default this crate will use portable software implementations of the underlying ChaCha20 and Poly1305 ciphers it's based on.
When targeting modern x86/x86_64 CPUs, use the following RUSTFLAGS
to
take advantage of AVX2 acceleration:
RUSTFLAGS="-Ctarget-feature=+avx2"
Ideally target the haswell
or skylake
architectures as a baseline:
RUSTFLAGS="-Ctarget-cpu=haswell -Ctarget-feature=+avx2"
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 chacha20poly1305::ChaCha20Poly1305; // Or `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 = ChaCha20Poly1305::new(key); let nonce = GenericArray::from_slice(b"unique nonce"); // 12-bytes; unique per message 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");
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 Aead::encrypt_in_place
and Aead::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 chacha20poly1305::ChaCha20Poly1305; // Or `XChaCha20Poly1305` use aead::{Aead, NewAead}; use aead::generic_array::{GenericArray, typenum::U128}; use aead::heapless::Vec; let key = GenericArray::clone_from_slice(b"an example very very secret key."); let aead = ChaCha20Poly1305::new(key); let nonce = GenericArray::from_slice(b"unique nonce"); // 128-bits; unique per message 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 aead.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 aead.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!"); assert_eq!(&buffer, b"plaintext message");
Re-exports
pub use aead; |
Structs
ChaCha12Poly1305 | ChaCha12Poly1305 (reduced round variant) Authenticated Encryption with Additional Data (AEAD). |
ChaCha20Poly1305 | ChaCha20Poly1305 Authenticated Encryption with Additional Data (AEAD). |
ChaCha8Poly1305 | ChaCha8Poly1305 (reduced round variant) Authenticated Encryption with Additional Data (AEAD). |
XChaCha20Poly1305 | XChaCha20Poly1305 is a ChaCha20Poly1305 variant with an extended
192-bit (24-byte) nonce. The |
Type Definitions
Tag | Poly1305 tags |