Module dryocstream

Expand description

§Encrypted streams

DryocStream provides libsodium-compatible authenticated encryption for an ordered sequence of messages, also known as a secret stream. It uses a shared secret key. Each message is encrypted and authenticated separately, while shared stream state links the messages and requires ordered processing. A tag can mark ordinary messages, rekeying points, or the expected end of the stream.

Use DryocStream to encrypt messages written in order to a file or network connection. A modified, reordered, or duplicated message is rejected when it is pulled; a removed message is detected when the next message is pulled. Removing the end of a stream cannot be detected automatically: the sender must use Tag::Final, and the application must reject a stream that ends without that tag.

The shared key can be generated directly or derived with Kdf, Session, or a password-hashing function such as crypto_pwhash.

DryocStream::init_push generates a public header for each stream. Send the header to the receiving side before the ciphertexts. Never reuse the same key and header for another stream.

§Rustaceous API example

use dryoc::dryocstream::*;
use dryoc::types::*;
let message1 = b"Arbitrary data to encrypt";
let message2 = b"split into";
let message3 = b"three messages";

// Generate a random secret key for this stream
let key = Key::generate();

// Initialize the push side, type annotations required on return type
let (mut push_stream, header): (_, Header) = DryocStream::init_push(&key);

// Encrypt a series of messages
let c1 = push_stream
    .push_to_vec(message1, None, Tag::Message)
    .expect("Encrypt failed");
let c2 = push_stream
    .push_to_vec(message2, None, Tag::Message)
    .expect("Encrypt failed");
let c3 = push_stream
    .push_to_vec(message3, None, Tag::Final)
    .expect("Encrypt failed");

// Initialize the pull side using header generated by the push side
let mut pull_stream = DryocStream::init_pull(&key, &header);

// Decrypt the encrypted messages, type annotations required
let (m1, tag1) = pull_stream.pull_to_vec(&c1, None).expect("Decrypt failed");
let (m2, tag2) = pull_stream.pull_to_vec(&c2, None).expect("Decrypt failed");
let (m3, tag3) = pull_stream.pull_to_vec(&c3, None).expect("Decrypt failed");

assert_eq!(message1, m1.as_slice());
assert_eq!(message2, m2.as_slice());
assert_eq!(message3, m3.as_slice());

assert_eq!(tag1, Tag::Message);
assert_eq!(tag2, Tag::Message);
assert_eq!(tag3, Tag::Final);

§Additional resources

See the libsodium documentation for more about secret streams
For public-key encryption, see DryocBox
For individual messages encrypted with a shared key, see DryocSecretBox
See the protected module for an example that stores keys in protected memory

Modules§

protectedprotected: Protected memory type aliases for DryocStream

Structs§

DryocStream: Secret-key authenticated encrypted streams
Pull: Indicates a pull stream
Push: Indicates a push stream

Enums§

Tag: Secret stream message tag.

Traits§

Mode: Stream mode marker trait: Push or Pull.

Type Aliases§

Header: Stack-allocated header data for authenticated secret streams.
Key: Stack-allocated secret for authenticated secret streams.