Module dryocbox 

Public-key authenticated encryption

DryocBox implements libsodium’s public-key authenticated encryption, also known as a box. This implementation uses X25519 for key derivation, the XSalsa20 stream cipher, and Poly1305 for message authentication.

You should use a DryocBox when you want to:

• exchange messages between two parties
• authenticate the messages with public keys, rather than a pre-shared secret
• avoid secret sharing between parties

DryocBox::encrypt authenticates the sender, so the sender and recipient public keys must be known ahead of time. DryocBox::seal instead sends an anonymous sealed box: it generates a one-time ephemeral keypair and stores the ephemeral public key with the ciphertext. Sealed boxes authenticate the ciphertext for the recipient, but not the sender’s identity.

Box nonces are public, but a nonce must never repeat for the same pair of keypairs. The two parties share one nonce space across both communication directions unless they use direction-specific keys. Callers of DryocBox::encrypt must coordinate this uniqueness. DryocBox::seal derives its nonce from a newly generated ephemeral public key and the recipient public key.

With the serde feature, serde::Deserialize and serde::Serialize are implemented for DryocBox. With wincode, wincode::SchemaRead and wincode::SchemaWrite are implemented.

Rustaceous API example

use dryoc::dryocbox::*;

// Randomly generate sender/recipient keypairs. Under normal circumstances, the
// sender would only know the recipient's public key, and the recipient would
// only know the sender's public key.
let sender_keypair = KeyPair::generate();
let recipient_keypair = KeyPair::generate();

// Randomly generate a nonce
let nonce = Nonce::generate();

let message = b"All that glitters is not gold";

// Encrypt the message into a Vec<u8>-based box.
let dryocbox = DryocBox::encrypt_to_vecbox(
    message,
    &nonce,
    &recipient_keypair.public_key,
    &sender_keypair.secret_key,
)
.expect("unable to encrypt");

// Convert into a libsodium compatible box as a Vec<u8>
let sodium_box = dryocbox.to_vec();

// Load the libsodium box into a DryocBox
let dryocbox = DryocBox::from_bytes(&sodium_box).expect("failed to read box");

// Decrypt the same box back to the original message, with the sender/recipient
// keypairs flipped.
let decrypted = dryocbox
    .decrypt_to_vec(
        &nonce,
        &sender_keypair.public_key,
        &recipient_keypair.secret_key,
    )
    .expect("unable to decrypt");

assert_eq!(message, decrypted.as_slice());

Sealed box example

use dryoc::dryocbox::*;

let recipient_keypair = KeyPair::generate();
let message = b"Now is the winter of our discontent.";

let dryocbox = DryocBox::seal_to_vecbox(message, &recipient_keypair.public_key.clone())
    .expect("unable to seal");

let decrypted = dryocbox
    .unseal_to_vec(&recipient_keypair)
    .expect("unable to unseal");

assert_eq!(message, decrypted.as_slice());

Additional resources

• See https://libsodium.gitbook.io/doc/public-key_cryptography/authenticated_encryption for additional details on crypto boxes
• For secret-key based encryption, see DryocSecretBox
• For stream encryption, see DryocStream
• See the protected mod for an example using the protected memory features with DryocBox

Re-exports

pub use crate::types::*;

Modules

protectedprotected

Protected memory type aliases for DryocBox

Structs

DryocBox

A libsodium public-key authenticated encrypted box.

Type Aliases

KeyPair

Stack-allocated public/secret keypair for authenticated public-key boxes.

Mac

Stack-allocated message authentication code for authenticated public-key boxes.

Nonce

Stack-allocated nonce for authenticated public-key boxes.

PublicKey

Stack-allocated public key for authenticated public-key boxes.

SecretKey

Stack-allocated secret key for authenticated public-key boxes.

VecBox

Vec-based authenticated public-key box.