Crate pwbox

Password-based encryption and decryption for Rust.

Overview

This crate provides the container for password-based encryption, PwBox, which can be composed of key derivation and authenticated symmetric Cipher cryptographic primitives. In turn, authenticated symmetric ciphers can be composed from an UnauthenticatedCipher and a message authentication code (Mac). The crate provides several pluggable cryptographic Suites with these primitives:

• Sodium
• RustCrypto (provides compatibility with Ethereum keystore; see its docs for more details)
• PureCrypto (pure Rust implementation; good for comiling into WASM or for other constrained environments).

There is also Eraser, which allows to (de)serialize PwBoxes from any serde-compatible format, such as JSON or TOML.

Naming

PwBox name was produced by combining two libsodium names: pwhash for password-based KDFs and *box for ciphers.

Crate Features

• std (enabled by default): Enables types from the Rust standard library. Switching this feature off can be used for constrained environments, such as WASM. Note that the crate still requires an allocator (that is, the alloc crate) even if the std feature is disabled.
• exonum_sodiumoxide (enabled by default), rust-crypto, pure (both disabled by default): Provide the cryptographic backends described above.

Examples

Using the Sodium cryptosuite:

use rand::thread_rng;
use pwbox::{Eraser, ErasedPwBox, Suite, sodium::Sodium};

// Create a new box.
let pwbox = Sodium::build_box(&mut thread_rng())
    .seal(b"correct horse", b"battery staple")?;

// Serialize box.
let mut eraser = Eraser::new();
eraser.add_suite::<Sodium>();
let erased: ErasedPwBox = eraser.erase(&pwbox)?;
println!("{}", serde_json::to_string_pretty(&erased)?);
// Deserialize box back.
let plaintext = eraser.restore(&erased)?.open(b"correct horse")?;
assert_eq!(&*plaintext, b"battery staple");

Modules

purepure

Pure Rust crypto primitives. Can be used if your app targets WASM or some other constrained environment.

rcryptorust-crypto

rust-crypto cryptographic backend.

sodiumexonum_sodiumoxide

Crypto primitives based on libsodium.

Structs

CipherOutput

Output of a Cipher.

CipherWithMac

Authenticated cipher constructed from an ordinary symmetric cipher and a MAC construction.

ErasedPwBox

Password-encrypted box suitable for (de)serialization.

Eraser

Helper structure to convert password-encrypted boxes to a serializable format and back.

MacMismatch

Error corresponding to MAC mismatch in Cipher::open().

PwBox

Password-encrypted data.

PwBoxBuilder

Builder for PwBoxes.

RestoredPwBox

Password-encrypted box restored after deserialization.

ScryptParams

Scrypt key derivation function parameterized as per the original paper.

SensitiveData

Container for data obtained after opening a PwBox.

Enums

EraseError

Errors occurring during erasing a PwBox.

Error

Errors occurring during PwBox operations.

Traits

Cipher

Authenticated symmetric cipher.

DeriveKey

Key derivation function (KDF).

Mac

Message authentication code.

Suite

Cryptographic suite providing ciphers and KDFs for password-based encryption.

UnauthenticatedCipher

Symmetric cipher without built-in authentication.