Module dryoc::dryocbox

Expand description

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.

If the serde feature is enabled, the serde::Deserialize and serde::Serialize traits will be implemented for DryocBox.

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