diff --git a/Cargo.lock b/Cargo.lock index 0ba51b47..1a69876c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -306,8 +306,9 @@ dependencies = [ [[package]] name = "password-hash" version = "0.6.0-rc.4" -source = "git+https://github.com/RustCrypto/traits#c1a92e9ac52f9201e1a3503b2ecd63007027b157" +source = "git+https://github.com/RustCrypto/traits#c45480e68908f7f1b37624cd89be10b35ef63a59" dependencies = [ + "getrandom", "phc", ] diff --git a/argon2/Cargo.toml b/argon2/Cargo.toml index 6a25e054..26c25efc 100644 --- a/argon2/Cargo.toml +++ b/argon2/Cargo.toml @@ -36,7 +36,7 @@ hex-literal = "1" default = ["alloc", "getrandom", "simple"] alloc = ["password-hash?/alloc"] -getrandom = ["simple", "phc/getrandom"] +getrandom = ["simple", "password-hash/getrandom"] parallel = ["dep:rayon"] simple = ["password-hash", "phc"] zeroize = ["dep:zeroize"] diff --git a/argon2/src/lib.rs b/argon2/src/lib.rs index d9cefcc3..ac4f9e03 100644 --- a/argon2/src/lib.rs +++ b/argon2/src/lib.rs @@ -35,19 +35,20 @@ #![cfg_attr(all(feature = "alloc", feature = "getrandom"), doc = "```")] #![cfg_attr(not(all(feature = "alloc", feature = "getrandom")), doc = "```ignore")] //! # fn main() -> Result<(), Box> { +//! // NOTE: example requires `getrandom` feature is enabled +//! //! use argon2::{ -//! password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, phc::Salt}, +//! password_hash::{PasswordHasher, PasswordVerifier, phc::PasswordHash}, //! Argon2 //! }; //! //! let password = b"hunter42"; // Bad password; don't actually use! -//! let salt = Salt::generate(); // Note: needs the `getrandom` feature of `argon2` enabled //! -//! // Argon2 with default params (Argon2id v19) +//! // Argon2 with default params (Argon2id v19), generating a random salt //! let argon2 = Argon2::default(); //! //! // Hash password to PHC string ($argon2id$v=19$...) -//! let password_hash = argon2.hash_password(password, &salt)?.to_string(); +//! let password_hash = argon2.hash_password(password)?.to_string(); //! //! // Verify password against PHC string. //! // @@ -66,16 +67,14 @@ #![cfg_attr(all(feature = "alloc", feature = "getrandom"), doc = "```")] #![cfg_attr(not(all(feature = "alloc", feature = "getrandom")), doc = "```ignore")] //! # fn main() -> Result<(), Box> { +//! // NOTE: example requires `getrandom` feature is enabled +//! //! use argon2::{ -//! password_hash::{ -//! phc::{PasswordHash, Salt}, -//! PasswordHasher, PasswordVerifier, -//! }, +//! password_hash::{PasswordHasher, PasswordVerifier, phc::PasswordHash}, //! Algorithm, Argon2, Params, Version //! }; //! //! let password = b"hunter42"; // Bad password; don't actually use! -//! let salt = Salt::generate(); // Note: needs the `getrandom` feature of `argon2` enabled //! //! // Argon2 with default params (Argon2id v19) and pepper //! let argon2 = Argon2::new_with_secret( @@ -83,11 +82,10 @@ //! Algorithm::default(), //! Version::default(), //! Params::default() -//! ) -//! .unwrap(); +//! )?; //! -//! // Hash password to PHC string ($argon2id$v=19$...) -//! let password_hash = argon2.hash_password(password, &salt)?.to_string(); +//! // Hash password to PHC string ($argon2id$v=19$...), generating a random salt +//! let password_hash = argon2.hash_password(password)?.to_string(); //! //! // Verify password against PHC string. //! // @@ -640,13 +638,17 @@ impl CustomizedPasswordHasher for Argon2<'_> { #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] cpu_feat_avx2: self.cpu_feat_avx2, } - .hash_password(password, salt) + .hash_password_with_salt(password, salt) } } #[cfg(all(feature = "alloc", feature = "password-hash"))] impl PasswordHasher for Argon2<'_> { - fn hash_password(&self, password: &[u8], salt: &[u8]) -> password_hash::Result { + fn hash_password_with_salt( + &self, + password: &[u8], + salt: &[u8], + ) -> password_hash::Result { let salt = Salt::new(salt).map_err(|_| password_hash::Error::SaltInvalid)?; let output_len = self @@ -719,7 +721,7 @@ mod tests { let params = Params::new(m_cost, t_cost, p_cost, None).unwrap(); let hasher = Argon2::new(Algorithm::default(), version, params); let hash = hasher - .hash_password(EXAMPLE_PASSWORD, EXAMPLE_SALT) + .hash_password_with_salt(EXAMPLE_PASSWORD, EXAMPLE_SALT) .unwrap(); assert_eq!(hash.version.unwrap(), version.into()); diff --git a/argon2/tests/kat.rs b/argon2/tests/kat.rs index 97660782..cbde31e9 100644 --- a/argon2/tests/kat.rs +++ b/argon2/tests/kat.rs @@ -366,7 +366,7 @@ fn hashtest( assert_eq!(out, expected_raw_hash); // Test hash encoding - let phc_hash = ctx.hash_password(pwd, salt).unwrap().to_string(); + let phc_hash = ctx.hash_password_with_salt(pwd, salt).unwrap().to_string(); assert_eq!(phc_hash, expected_phc_hash); let hash = PasswordHash::new(alternative_phc_hash).unwrap(); diff --git a/argon2/tests/phc_strings.rs b/argon2/tests/phc_strings.rs index e2936aab..01a39ca0 100644 --- a/argon2/tests/phc_strings.rs +++ b/argon2/tests/phc_strings.rs @@ -211,7 +211,10 @@ fn check_hash_encoding_parameters_order() { let password = b"password"; let salt = [0u8; 8]; - let password_hash = ctx.hash_password(password, &salt).unwrap().to_string(); + let password_hash = ctx + .hash_password_with_salt(password, &salt) + .unwrap() + .to_string(); // The parameters shall appear in the m,t,p,keyid,data order assert_eq!( diff --git a/balloon-hash/Cargo.toml b/balloon-hash/Cargo.toml index aee306fc..1b18ba18 100644 --- a/balloon-hash/Cargo.toml +++ b/balloon-hash/Cargo.toml @@ -31,7 +31,7 @@ sha2 = "0.11.0-rc.3" default = ["alloc", "getrandom", "password-hash"] alloc = ["password-hash/alloc"] -getrandom = ["phc/getrandom"] +getrandom = ["password-hash/getrandom"] parallel = ["dep:rayon"] password-hash = ["dep:password-hash", "dep:phc"] zeroize = ["dep:zeroize"] diff --git a/balloon-hash/src/lib.rs b/balloon-hash/src/lib.rs index e66fe8d3..9be4a46e 100644 --- a/balloon-hash/src/lib.rs +++ b/balloon-hash/src/lib.rs @@ -9,42 +9,26 @@ //! # 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: -//! -//! ```toml -//! [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: //! -#![cfg_attr(feature = "getrandom", doc = "```")] -#![cfg_attr(not(feature = "getrandom"), doc = "```ignore")] +#![cfg_attr(all(feature = "alloc", feature = "getrandom"), doc = "```")] +#![cfg_attr(not(all(feature = "alloc", feature = "getrandom")), doc = "```ignore")] //! # fn main() -> Result<(), Box> { +//! // NOTE: example requires `getrandom` feature is enabled +//! //! use balloon_hash::{ -//! password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, phc::Salt}, +//! password_hash::{PasswordHasher, PasswordVerifier, phc::PasswordHash}, //! Balloon //! }; //! use sha2::Sha256; //! //! let password = b"hunter42"; // Bad password; don't actually use! -//! let salt = Salt::generate(); // Note: needs the `getrandom` feature of `balloon-hash` enabled //! //! // Balloon with default params //! let balloon = Balloon::::default(); //! //! // Hash password to PHC string ($balloon$v=1$...) -//! let password_hash = balloon.hash_password(password, &salt)?.to_string(); +//! let password_hash = balloon.hash_password(password)?.to_string(); //! //! // Verify password against PHC string //! let parsed_hash = PasswordHash::new(&password_hash)?; @@ -235,7 +219,7 @@ where } } - Self::new(algorithm, params, self.secret).hash_password(password, salt) + Self::new(algorithm, params, self.secret).hash_password_with_salt(password, salt) } } @@ -245,7 +229,11 @@ where D: Digest + FixedOutputReset, Array: ArrayDecoding, { - fn hash_password(&self, password: &[u8], salt: &[u8]) -> password_hash::Result { + fn hash_password_with_salt( + &self, + password: &[u8], + salt: &[u8], + ) -> password_hash::Result { let salt = Salt::new(salt).map_err(|_| password_hash::Error::SaltInvalid)?; let hash = self.hash(password, &salt)?; let output = Output::new(&hash).map_err(|_| password_hash::Error::OutputSize)?; diff --git a/balloon-hash/tests/balloon.rs b/balloon-hash/tests/balloon.rs index 9e1031e7..72b1db7b 100644 --- a/balloon-hash/tests/balloon.rs +++ b/balloon-hash/tests/balloon.rs @@ -92,7 +92,7 @@ fn hash_simple_retains_configured_params() { let params = Params::new(s_cost, t_cost, p_cost).unwrap(); let hasher = Balloon::::new(Algorithm::default(), params, None); let hash = hasher - .hash_password(EXAMPLE_PASSWORD, EXAMPLE_SALT) + .hash_password_with_salt(EXAMPLE_PASSWORD, EXAMPLE_SALT) .unwrap(); assert_eq!(hash.version.unwrap(), 1); diff --git a/password-auth/src/lib.rs b/password-auth/src/lib.rs index cbcd4323..5cb70024 100644 --- a/password-auth/src/lib.rs +++ b/password-auth/src/lib.rs @@ -61,13 +61,13 @@ fn generate_phc_hash(password: &[u8], salt: &[u8]) -> password_hash::Result Result<(), Box> { +//! // NOTE: example requires `getrandom` feature is enabled +//! //! use pbkdf2::{ -//! password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, phc::Salt}, +//! password_hash::{PasswordHasher, PasswordVerifier, phc::PasswordHash}, //! Pbkdf2 //! }; //! //! let password = b"hunter42"; // Bad password; don't actually use! -//! let salt = Salt::generate(); //! //! // Hash password to PHC string ($pbkdf2-sha256$...) -//! let password_hash = Pbkdf2.hash_password(password, &salt)?.to_string(); +//! let password_hash = Pbkdf2.hash_password(password)?.to_string(); //! //! // Verify password against PHC string //! let parsed_hash = PasswordHash::new(&password_hash)?; diff --git a/pbkdf2/src/simple.rs b/pbkdf2/src/simple.rs index 015100c6..34cc02a7 100644 --- a/pbkdf2/src/simple.rs +++ b/pbkdf2/src/simple.rs @@ -65,7 +65,7 @@ impl CustomizedPasswordHasher for Pbkdf2 { } impl PasswordHasher for Pbkdf2 { - fn hash_password(&self, password: &[u8], salt: &[u8]) -> Result { + fn hash_password_with_salt(&self, password: &[u8], salt: &[u8]) -> Result { self.hash_password_customized(password, salt, None, None, Params::default()) } } diff --git a/scrypt/Cargo.toml b/scrypt/Cargo.toml index a5362b1b..1ed18b51 100644 --- a/scrypt/Cargo.toml +++ b/scrypt/Cargo.toml @@ -27,7 +27,7 @@ phc = { version = "0.6.0-rc.0", optional = true, features = ["rand_core"] } default = ["simple", "rayon"] alloc = ["password-hash?/alloc"] -getrandom = ["simple", "phc/getrandom"] +getrandom = ["simple", "password-hash/getrandom"] rayon = ["dep:rayon"] simple = ["dep:password-hash", "dep:phc"] diff --git a/scrypt/src/lib.rs b/scrypt/src/lib.rs index ceff27ff..badf72ce 100644 --- a/scrypt/src/lib.rs +++ b/scrypt/src/lib.rs @@ -15,6 +15,8 @@ #![cfg_attr(all(feature = "alloc", feature = "getrandom"), doc = "```")] #![cfg_attr(not(all(feature = "alloc", feature = "getrandom")), doc = "```ignore")] //! # fn main() -> Result<(), Box> { +//! // NOTE: example requires `getrandom` feature is enabled +//! //! use scrypt::{ //! password_hash::{ //! PasswordHasher, PasswordVerifier, phc::{PasswordHash, Salt} @@ -23,10 +25,9 @@ //! }; //! //! let password = b"hunter42"; // Bad password; don't actually use! -//! let salt = Salt::generate(); //! //! // Hash password to PHC string ($scrypt$...) -//! let password_hash = Scrypt.hash_password(password, &salt)?.to_string(); +//! let password_hash = Scrypt.hash_password(password)?.to_string(); //! //! // Verify password against PHC string //! let parsed_hash = PasswordHash::new(&password_hash)?; diff --git a/scrypt/src/simple.rs b/scrypt/src/simple.rs index f9546dad..f2b759a1 100644 --- a/scrypt/src/simple.rs +++ b/scrypt/src/simple.rs @@ -58,7 +58,7 @@ impl CustomizedPasswordHasher for Scrypt { } impl PasswordHasher for Scrypt { - fn hash_password(&self, password: &[u8], salt: &[u8]) -> Result { + fn hash_password_with_salt(&self, password: &[u8], salt: &[u8]) -> Result { self.hash_password_customized(password, salt, None, None, Params::default()) } } diff --git a/yescrypt/Cargo.toml b/yescrypt/Cargo.toml index d7c8b977..99895a69 100644 --- a/yescrypt/Cargo.toml +++ b/yescrypt/Cargo.toml @@ -28,7 +28,8 @@ password-hash = { version = "0.6.0-rc.4", optional = true, default-features = fa hex-literal = "1" [features] -default = ["simple"] +default = ["getrandom"] +getrandom = ["simple", "password-hash/getrandom"] simple = ["dep:mcf", "dep:password-hash"] [package.metadata.docs.rs] diff --git a/yescrypt/src/lib.rs b/yescrypt/src/lib.rs index eb3313a7..6a11d8a1 100644 --- a/yescrypt/src/lib.rs +++ b/yescrypt/src/lib.rs @@ -25,15 +25,15 @@ //! # Usage //! ## Password Hashing -//! NOTE: the `simple` crate feature must be enabled (on-by-default) -#![cfg_attr(feature = "simple", doc = "```")] -#![cfg_attr(not(feature = "simple"), doc = "```ignore")] +#![cfg_attr(feature = "getrandom", doc = "```")] +#![cfg_attr(not(feature = "getrandom"), doc = "```ignore")] //! # fn main() -> yescrypt::password_hash::Result<()> { +//! // NOTE: example requires `getrandom` feature is enabled +//! //! use yescrypt::{Yescrypt, PasswordHasher, PasswordVerifier}; //! //! let password = b"pleaseletmein"; // don't actually use this as a password! -//! let salt = b"WZaPV7LSUEKMo34."; // unique per password, ideally 16-bytes and random -//! let password_hash = Yescrypt.hash_password(password, salt)?; +//! let password_hash = Yescrypt.hash_password(password)?; //! assert!(password_hash.as_str().starts_with("$y$")); //! //! // verify password is correct for the given hash diff --git a/yescrypt/src/simple.rs b/yescrypt/src/simple.rs index 3f07cf82..53fa9c21 100644 --- a/yescrypt/src/simple.rs +++ b/yescrypt/src/simple.rs @@ -69,7 +69,7 @@ impl CustomizedPasswordHasher for Yescrypt { } impl PasswordHasher for Yescrypt { - fn hash_password(&self, password: &[u8], salt: &[u8]) -> Result { + fn hash_password_with_salt(&self, password: &[u8], salt: &[u8]) -> Result { self.hash_password_customized(password, salt, None, None, Params::default()) } }