Module dryoc::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

The public keys of the sender and recipient must be known ahead of time, but the sender’s secret key can be used once and discarded, if desired. The DryocBox::seal and corresponding DryocBox::unseal functions do just this, by generating an ephemeral secret key, deriving a nonce, and including the sender’s public key in the box.

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::gen();
let recipient_keypair = KeyPair::gen();

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

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::gen();
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

protected

nightly Protected memory type aliases for DryocBox

Structs

DryocBox

A libsodium public-key authenticated encrypted box.

Type Definitions

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.