Struct privatebox::PrivateBox

pub struct PrivateBox<T: RngCore> { /* fields omitted */ }

A wrapper around XChaChaPoly1305 for convenient encryption

Implementations

impl<T: RngCore> PrivateBox<T>

Generates basic containers that store encrypted data

Basic Usage

let mut privatebox = PrivateBox::new(b"0123456789abcdef0123456789abcdef", OsRng);
let header = b"stored plain text";
let metadata = b"plain text";

let container = privatebox.encrypt(b"secret data", &*header, &*metadata)?;
assert_ne!(&container, b"secret data");

let (decrypted_message, authenticated_header) = privatebox.decrypt(&container, &*metadata)?;
assert_eq!(decrypted_message, b"secret data");
assert_eq!(authenticated_header, b"stored plain text");

Associated Data

Associated data in an AEAD is data that is authenticated but not encrypted. It is provided during the encryption and decryption stage. It does not necessarily have to be stored with the ciphertext. Hence PrivateBox::encrypt has an authenticated header (stored in container) and metadata (stored separately). The metadata thus is provided separately from the container during PrivateBox::decrypt. When doing detached encryption/decryption there is just assoc_data as storage is handled by user. For use cases check out this stackexchange answer

Nonces

Nonces are arbitrary numbers used in encryption and are one time use per key. PrivateBox uses XChaChaPoly1305 which is ChaChaPoly1305 with an extended nonce (24 bytes instead of 12). Therefore it is OK (libsodium ref) to use a random number generator for nonce generation. The random number generator provided upon the creation of PrivateBox is used to generate nonces. The generator is not cloned during encryption so each pass produces a different nonce.

Features

Enabling alloc (on by default) lets you access PrivateBox::encrypt and PrivateBox::decrypt

pub fn new(key: &[u8; 32], rng: T) -> Self

Creates a new PrivateBox with a symmetric key and a random number generator

• key - a 32 byte symmetric key
• rng - a random number generator that generates nonces, implements RngCore

Examples

use privatebox::PrivateBox;
use rand_core::{RngCore, OsRng};

// Key must have a length of 32 bytes.
let mut key = [0u8; 32];
OsRng.fill_bytes(&mut key);

let privatebox = PrivateBox::new(&key, OsRng);

pub fn encrypt_detached(
    &mut self,
    data: &mut [u8],
    assoc_data: &[u8]
) -> Result<[u8; 40], PrivateBoxError>

Encrypts message in place with associated data and returns a detached prefix for the data.

• message - data to be encrypted in place
• assoc_data - associated data to be used

The prefix is needed to decrypt the data with PrivateBox::decrypt The prefix is an array of bytes with nonce first, tag second.

This method does not use memory allocation and suitable in the build without alloc

Examples

let mut privatebox = PrivateBox::new(&[1;32], OsRng); 

let mut message = *b"secret data";
let assoc_data = *b"plain text";

let detached_prefix = privatebox.encrypt_detached(&mut message, &assoc_data);
assert_ne!(&message, b"secret data");

pub fn decrypt_detached(
    &self,
    message: &mut [u8],
    assoc_data: &[u8],
    detached_prefix: &[u8; 40]
) -> Result<(), PrivateBoxError>

Decrypts message in place using associated data and prefix returned by the PrivateBox::encrypt method.

• message - data to be encrypted in place
• assoc_data - associated data to be used in decryption

The method doesn’t use memory allocation and is suitable in the build without alloc

Examples

let mut privatebox = PrivateBox::new(&[1;32], OsRng); 

let mut message = *b"secret data";

let detached_prefix = privatebox.encrypt_detached(&mut message, &[])?;
assert_ne!(&message, b"secret data");

privatebox.decrypt_detached(&mut message, &[], &detached_prefix)?;
assert_eq!(&message, b"secret data");

pub fn encrypt(
    &mut self,
    message: &[u8],
    header: &[u8],
    metadata: &[u8]
) -> Result<Vec<u8>, PrivateBoxError>

This is supported on crate feature alloc only.

Encrypts message and outputs a container with all necessary data to decrypt

• message - data to be encrypted
• header - data to be authenticated and stored in the container
• metadata - data to be authenticated but not stored

Examples

let mut privatebox = PrivateBox::new(&[1;32], OsRng); 

let message = *b"secret data";
let header = *b"attached data";
let metadata = *b"detached data";

let container = privatebox.encrypt(&message, &header, &metadata)?;

pub fn decrypt(
    &self,
    container: &[u8],
    metadata: &[u8]
) -> Result<(Vec<u8>, Vec<u8>), PrivateBoxError>

This is supported on crate feature alloc only.

Decrypts a container and outputs the authenticated header and decrypted message

During decryption the header and provided metadata is concatenated to produce the full associated data. Successful decryption means that the provided metadata was authenticated.

• container - the container outputed by PrivateBox::encrypt
• metadata - authenticated data not stored in the container

Examples

let mut privatebox = PrivateBox::new(&[1;32], OsRng); 

let message = *b"secret data";
let header = *b"attached data";
let metadata = *b"detached data";

let container = privatebox.encrypt(&message, &header, &metadata)?;

// Note only the metadata is required for decryption
let (decrypted_message, authenticated_header) = privatebox.decrypt(&container, &metadata)?;
assert_eq!(&decrypted_message, &message);
assert_eq!(&authenticated_header, &header);

pub fn parse_insecure_header(
    &self,
    container: &[u8]
) -> Result<Vec<u8>, PrivateBoxError>

This is supported on crate feature alloc only.

Retrieve the insecure header data from a container

• container - container outputted by PrivateBox::encrypt

The header data is not authenticated, it is insecure. It may have been altered so use at your own risk.

Examples

let mut privatebox = PrivateBox::new(&[1;32], OsRng); 
let header = &[4, 4, 1, 1];

let container = privatebox.encrypt(&*b"data", header, &[])?;
let insecure_header = privatebox.parse_insecure_header(&container)?;

// In this case header and insecure header are the same (but not guranteed)
assert_eq!(&insecure_header, header);