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

pure	pure Pure Rust crypto primitives. Can be used if your app targets WASM or some other constrained environment.
rcrypto	rust-crypto rust-crypto cryptographic backend.
sodium	exonum_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.