Crate balloon_hash
source ·Expand description
RustCrypto: Balloon Hash
Pure Rust implementation of the Balloon password hashing function.
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
pub use password_hash;
Structs
- Balloon context.
- Balloon password hash parameters.
- PasswordHash
password-hash
Password hash. - Salt string.
Enums
- Balloon primitive type: variants of the algorithm.
- Error type.
Traits
- PasswordHasher
password-hash
Trait for password hashing functions. - PasswordVerifier
password-hash
Trait for password verification.
Type Definitions
- Result with balloon’s
Error
type.