Crate pwbox

source · []
Expand description

Password-based encryption and decryption for Rust.


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.


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.


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();
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");



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


rust-crypto cryptographic backend.


Crypto primitives based on libsodium.


Output of a Cipher.

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

Password-encrypted box suitable for (de)serialization.

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

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

Password-encrypted data.

Builder for PwBoxes.

Password-encrypted box restored after deserialization.

Scrypt key derivation function parameterized as per the original paper.

Container for data obtained after opening a PwBox.


Errors occurring during erasing a PwBox.

Errors occurring during PwBox operations.


Authenticated symmetric cipher.

Key derivation function (KDF).

Message authentication code.

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

Symmetric cipher without built-in authentication.