Module dryocsecretbox 

Secret-key authenticated encryption

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

You should use a DryocSecretBox when you want to:

• exchange messages between two or more parties
• 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

Every holder of the shared key can create valid messages. In a group, secretbox authenticates membership in the group, not which member sent a message.

Secretbox nonces are public, but a nonce must never repeat with the same key. Store each nonce with its ciphertext or use a counter that cannot repeat for that key.

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

Rustaceous API example

use dryoc::dryocsecretbox::*;

// Generate a random secret key and nonce
let secret_key = Key::generate();
let nonce = Nonce::generate();
let message = b"A message to encrypt";

// Encrypt `message`, into a Vec-based box
let dryocsecretbox = DryocSecretBox::encrypt_to_vecbox(message, &nonce, &secret_key);

// Convert into a libsodium-compatible box
let sodium_box = dryocsecretbox.to_vec();

// Read the same box we just made into a new DryocBox
let dryocsecretbox = DryocSecretBox::from_bytes(&sodium_box).expect("unable to load box");

// Decrypt the box we previously encrypted,
let decrypted = dryocsecretbox
    .decrypt_to_vec(&nonce, &secret_key)
    .expect("unable to decrypt");

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

Additional resources

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

Re-exports

pub use crate::types::*;

Modules

protectedprotected

Protected memory type aliases for DryocSecretBox

Structs

DryocSecretBox

An authenticated secret-key encrypted box, compatible with a libsodium box. Use with either VecBox or protected::LockedBox type aliases.

Type Aliases

Key

Stack-allocated secret for authenticated secret box.

Mac

Stack-allocated secret box message authentication code.

Nonce

Stack-allocated nonce for authenticated secret box.

VecBox

Vec-based authenticated secret box.