Module dryocbox 

Public-key authenticated encryption

DryocBox provides libsodium-compatible public-key authenticated encryption, also known as a box. It uses X25519 to establish a shared key, XSalsa20 to encrypt the message, and Poly1305 to detect tampering.

Use a DryocBox when a sender and recipient have each other’s public keys and need to exchange encrypted messages. The recipient can verify that a message was created with the sender’s secret key. A box is not a public signature: the recipient can also create messages that appear to come from the sender.

DryocBox::seal provides anonymous encryption instead. It creates a new temporary keypair for each message and stores the temporary public key with the ciphertext. A sealed box proves that the ciphertext was not changed, but it does not identify the sender. For sealed boxes that stay confidential against future quantum computers, use DryocSealedBox, which has the same seal/open methods.

Nonces are public, but a nonce must never repeat for the same sender and recipient keypair. The two parties share one nonce space unless they use separate keys for each direction. Callers of DryocBox::encrypt must enforce this rule. DryocBox::seal handles nonce generation internally.

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

Rustaceous API example

use dryoc::dryocbox::*;
use dryoc::types::*;

// In a real exchange, each party keeps its secret key private and shares
// only its public key.
let sender_keypair = StackKeyPair::generate();
let recipient_keypair = StackKeyPair::generate();

// Generate a random nonce. At 24 bytes, the chance of a random nonce
// repeating is negligible.
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");

// Serialize the box in libsodium's wire format, then read it back.
let sodium_box = dryocbox.to_vec();
let dryocbox = DryocBox::from_bytes(&sodium_box).expect("failed to read box");

// Decrypt with the recipient's secret key and the sender's public key.
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 = StackKeyPair::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
    .open_to_vec(&recipient_keypair)
    .expect("unable to open");

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

Additional resources

• See the libsodium documentation for more about authenticated public-key encryption
• For shared-key encryption, see DryocSecretBox
• For encrypted message streams, see DryocStream
• See the protected module for an example that stores keys in protected memory

Modules

protectedprotected

Protected memory type aliases for DryocBox

Structs

DryocBox

A libsodium public-key authenticated encrypted box.

Type Aliases

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.

StackKeyPair

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

VecBoxalloc

Vec-based authenticated public-key box.