Expand description
XChaCha20 as specified in the draft RFC.
Parameters:
secret_key
: The secret key.nonce
: The nonce value.initial_counter
: The initial counter value. In most cases this is0
.ciphertext
: The encrypted data.plaintext
: The data to be encrypted.dst_out
: Destination array that will hold the ciphertext/plaintext after encryption/decryption.
Exceptions:
An exception will be thrown if:
- The length of
dst_out
is less thanplaintext
orciphertext
. plaintext
orciphertext
are empty.plaintext
orciphertext
are longer than (2^32)-2.- The
initial_counter
is high enough to cause a potential overflow.
Even though dst_out
is allowed to be of greater length than plaintext
, the ciphertext
produced by chacha20
/xchacha20
will always be of the same length as the plaintext
.
Security:
- It is critical for security that a given nonce is not re-used with a given key. Should this happen, the security of all data that has been encrypted with that given key is compromised.
- Functions herein do not provide any data integrity. If you need
data integrity, which is nearly always the case, you should use an AEAD construction instead.
See orions
aead
module for this. - Only a nonce for XChaCha20 is big enough to be randomly generated using a CSPRNG.
Nonce::generate()
can be used for this. - To securely generate a strong key, use
SecretKey::generate()
.
Recommendation:
- It is recommended to use XChaCha20Poly1305 when possible.
Example:
use orion::hazardous::stream::xchacha20;
let secret_key = xchacha20::SecretKey::generate().unwrap();
let nonce = xchacha20::Nonce::generate().unwrap();
// Length of this message is 15
let message = "Data to protect".as_bytes();
let mut dst_out_pt = [0u8; 15];
let mut dst_out_ct = [0u8; 15];
xchacha20::encrypt(&secret_key, &nonce, 0, message, &mut dst_out_ct);
xchacha20::decrypt(&secret_key, &nonce, 0, &dst_out_ct, &mut dst_out_pt);
assert_eq!(dst_out_pt, message);
Re-exports
pub use hazardous::stream::chacha20::SecretKey;
Structs
A type that represents a
Nonce
that XChaCha20 and XChaCha20Poly1305 use.