[−][src]Module orion::hazardous::stream::xchacha20

XChaCha20 as specified in the draft-irtf-cfrg-xchacha-03.

Parameters:

  • secret_key: The secret key.
  • nonce: The nonce value.
  • initial_counter: The initial counter value. In most cases, this is 0.
  • ciphertext: The encrypted data.
  • plaintext: The data to be encrypted.
  • dst_out: Destination array that will hold the ciphertext/plaintext after encryption/decryption.

Errors:

An error will be returned if:

  • The length of dst_out is less than plaintext or ciphertext.
  • plaintext or ciphertext is empty.
  • 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.

Panics:

A panic will occur if:

  • More than 2^32-1 * 64 bytes of data are processed.

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:

Example:

use orion::hazardous::stream::xchacha20;

let secret_key = xchacha20::SecretKey::generate();
let nonce = xchacha20::Nonce::generate();
let message = "Data to protect".as_bytes();

// Length of this message is 15

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 crate::hazardous::stream::chacha20::SecretKey;

Structs

Nonce

A type that represents a Nonce that XChaCha20, XChaCha20Poly1305 and StreamXChaCha20Poly1305 use.

Constants

XCHACHA_NONCESIZE

The nonce size for XChaCha20.

Functions

decrypt

XChaCha20 decryption as specified in the draft RFC.

encrypt

XChaCha20 encryption as specified in the draft RFC.