Module dryoc::dryocstream

Encrypted streams

DryocStream implements libsodium’s secret-key authenticated stream encryption, also known as a secretstream. This implementation uses the XChaCha20 stream cipher, and Poly1305 for message authentication.

You should use a DryocStream when you want to:

• read and write messages from/to a file or network socket
• exchange messages between two parties
• send messages in a particular sequence, and authenticate the order of messages
• provide a way to determine the start and end of a sequence of messages
• use a shared secret, which could be pre-shared, or derived using one or more of:
  • Kdf
  • Kx
  • a passphrase with a strong password hashing function, such as crypto_pwhash

Rustaceous API example

use dryoc::dryocstream::*;
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::gen();

// 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 https://libsodium.gitbook.io/doc/secret-key_cryptography/secretstream for additional details on secret streams
• For public-key based encryption, see DryocBox
• For secret-key based encryption, see DryocSecretBox
• See the protected mod for an example using the protected memory features with DryocStream

Re-exports

• pub use crate::types::*;

Modules

• protectednightly
  Protected memory type aliases for DryocStream

Structs

• DryocStream
  Secret-key authenticated encrypted streams
• Pull
  Indicates a pull stream
• Push
  Indicates a push stream
• Tag
  Message tag definitions

Traits

• Mode
  Stream mode marker trait

Type Definitions

• Header
  Stack-allocated header data for authenticated secret streams.
• Key
  Stack-allocated secret for authenticated secret streams.
• Nonce
  Stack-allocated nonce for authenticated secret streams.