Module streaming

Available on crate feature dep_orion only.

Streaming AEAD based on XChaCha20Poly1305.

About:

This implementation is based on and compatible with the “secretstream” API of libsodium.

Parameters:

• secret_key: The secret key.
• nonce: The nonce value.
• ad: Additional data to authenticate (this is not encrypted and can be None).
• plaintext: The data to be encrypted.
• ciphertext: The encrypted data with, a Poly1305 tag and a StreamTag indicating its function.
• dst_out: Destination array that will hold the ciphertext/plaintext after encryption/decryption.
• tag: Indicates the type of message. The tag is a part of the output when encrypting. It is encrypted and authenticated.

ad: “A typical use for these data is to authenticate version numbers, timestamps or monotonically increasing counters in order to discard previous messages and prevent replay attacks.” See [libsodium docs] for more information.

dst_out: The output buffer may have a capacity greater than the input. If this is the case, only the first input length amount of bytes in dst_out are modified, while the rest remain untouched.

Errors:

An error will be returned if:

• The length of dst_out is less than plaintext + ABYTES when calling seal_chunk().
• The length of dst_out is less than ciphertext - ABYTES when calling open_chunk().
• The length of the ciphertext is less than ABYTES.
• The received mac does not match the calculated mac when calling open_chunk(). This can indicate a dropped or reordered message within the stream.
• More than 2^32-3 * 64 bytes of data are processed when sealing/opening a single chunk.
• ABYTES + plaintext.len() overflows when encrypting.

Panics:

A panic will occur if:

• 64 + (ciphertext.len() - ABYTES) overflows u64::MAX when decrypting.

Security:

• It is critical for security that a given nonce is not re-used with a given key.
• The nonce can be randomly generated using a CSPRNG. Nonce::generate() can be used for this.
• To securely generate a strong key, use SecretKey::generate().
• The lengths of the messages are not hidden, only their contents.
• It is recommended to use StreamTag::Finish as the tag for the last message. This allows the decrypting side to detect if messages at the end of the stream are lost.

Example:

use orion::hazardous::aead::streaming::*;

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

// Length of the above message is 15 and then we accommodate 17
// for the mac and tag.
let mut dst_out_ct = [0u8; 15 + ABYTES];
let mut dst_out_pt = [0u8; 15];

let mut ctx_enc = StreamXChaCha20Poly1305::new(&secret_key, &nonce);

// Encrypt and place tag + ciphertext + mac in dst_out_ct
ctx_enc.seal_chunk(message, Some(ad), &mut dst_out_ct, &StreamTag::Message)?;

let mut ctx_dec = StreamXChaCha20Poly1305::new(&secret_key, &nonce);

// Decrypt and save the tag the message was encrypted with.
let tag = ctx_dec.open_chunk(&dst_out_ct, Some(ad), &mut dst_out_pt)?;

assert_eq!(tag, StreamTag::Message);
assert_eq!(dst_out_pt.as_ref(), message);

Structs

Nonce

A type that represents a Nonce that XChaCha20, XChaCha20-Poly1305 use.

SecretKey

A type to represent the SecretKey that Chacha20, XChaCha20, ChaCha20-Poly1305 and XChaCha20-Poly1305 use.

StreamXChaCha20Poly1305

Streaming XChaCha20Poly1305 state.

Enums

StreamTag

Tag that indicates the type of message.

Constants

ABYTES

Size of additional data appended to each message.

TAG_SIZE

The size of a StreamTag.