Crate balloon_hash

source ·
Expand description

RustCrypto: Balloon Hash

crate Docs Build Status Apache2/MIT licensed Rust Version Project Chat

Pure Rust implementation of the Balloon password hashing function.

Documentation

About

This crate contains an implementation of the Balloon password hashing function as specified in the paper Balloon Hashing: A Memory-Hard Function Providing Provable Protection Against Sequential Attacks.

This algorithm is first practical password hashing function that provides:

  • Memory hardness which is proven in the random-oracle model
  • Password-independent access
  • Performance which meets or exceeds the best heuristically secure password-hashing algorithms

Minimum Supported Rust Version

Rust 1.65 or higher.

Minimum supported Rust version can be changed in the future, but it will be done with a minor version bump.

SemVer Policy

  • All on-by-default features of this library are covered by SemVer
  • MSRV is considered exempt from SemVer as noted above

License

Licensed under either of:

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Usage (simple with default params)

Note: this example requires the rand_core crate with the std feature enabled for rand_core::OsRng (embedded platforms can substitute their own RNG)

Add the following to your crate’s Cargo.toml to import it:

[dependencies]
balloon-hash = "0.2"
rand_core = { version = "0.6", features = ["std"] }
sha2 = "0.9"

The zeroize crate feature will zeroize allocated memory created when using the Balloon::hash function. It will do nothing when the alloc crate feature is not active.

The following example demonstrates the high-level password hashing API:

use balloon_hash::{
    password_hash::{
        rand_core::OsRng,
        PasswordHash, PasswordHasher, PasswordVerifier, SaltString
    },
    Balloon
};
use sha2::Sha256;

let password = b"hunter42"; // Bad password; don't actually use!
let salt = SaltString::generate(&mut OsRng);

// Balloon with default params
let balloon = Balloon::<Sha256>::default();

// Hash password to PHC string ($balloon$v=1$...)
let password_hash = balloon.hash_password(password, &salt)?.to_string();

// Verify password against PHC string
let parsed_hash = PasswordHash::new(&password_hash)?;
assert!(balloon.verify_password(password, &parsed_hash).is_ok());

Re-exports

Structs

Enums

  • Algorithm
    Balloon primitive type: variants of the algorithm.
  • Error
    Error type.

Traits

Type Definitions