Leverage password-hash/getrandom (#769)

Companion PR to RustCrypto/traits#2123

The aforementioned traits PR renames `PasswordHash::hash_password` to
`hash_password_with_salt`, so this PR updates the method name change
accordingly.

When the `getrandom` feature is enabled, it provides a new
`PasswordHash::hash_password` which *just* accepts a password as an
argument, relying on `getrandom` to internally generate a salt.

This updates all the code examples to use the new API so users don't
have to deal with randomly generating a salt.

Author: tarcieri

Cargo.lock

@@ -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"]

argon2/Cargo.toml

@@ -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<dyn core::error::Error>> {
+//! // 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,28 +67,25 @@
 #![cfg_attr(all(feature = "alloc", feature = "getrandom"), doc = "```")]
 #![cfg_attr(not(all(feature = "alloc", feature = "getrandom")), doc = "```ignore")]
 //! # fn main() -> Result<(), Box<dyn core::error::Error>> {
+//! // 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(
 //!     b"secret pepper",
 //!     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<PasswordHash> 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<PasswordHash> for Argon2<'_> {
-    fn hash_password(&self, password: &[u8], salt: &[u8]) -> password_hash::Result<PasswordHash> {
+    fn hash_password_with_salt(
+        &self,
+        password: &[u8],
+        salt: &[u8],
+    ) -> password_hash::Result<PasswordHash> {
         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());

argon2/src/lib.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();

argon2/tests/kat.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!(

argon2/tests/phc_strings.rs

@@ -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"]

balloon-hash/Cargo.toml

@@ -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<dyn core::error::Error>> {
+//! // 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::<Sha256>::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<u8, D::OutputSize>: ArrayDecoding,
 {
-    fn hash_password(&self, password: &[u8], salt: &[u8]) -> password_hash::Result<PasswordHash> {
+    fn hash_password_with_salt(
+        &self,
+        password: &[u8],
+        salt: &[u8],
+    ) -> password_hash::Result<PasswordHash> {
         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)?;

balloon-hash/src/lib.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::<Sha256>::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);

balloon-hash/tests/balloon.rs

@@ -61,13 +61,13 @@ fn generate_phc_hash(password: &[u8], salt: &[u8]) -> password_hash::Result<Pass
     // Algorithms below are in order of preference
     //
     #[cfg(feature = "argon2")]
-    return Argon2::default().hash_password(password, salt);
+    return Argon2::default().hash_password_with_salt(password, salt);
 
     #[cfg(feature = "scrypt")]
-    return Scrypt.hash_password(password, salt);
+    return Scrypt.hash_password_with_salt(password, salt);
 
     #[cfg(feature = "pbkdf2")]
-    return Pbkdf2.hash_password(password, salt);
+    return Pbkdf2.hash_password_with_salt(password, salt);
 }
 
 /// Verify the provided password against the provided password hash.

password-auth/src/lib.rs

@@ -33,7 +33,7 @@ belt-hash = "0.2.0-rc.3"
 
 [features]
 default = ["hmac"]
-getrandom = ["simple", "phc/getrandom"]
+getrandom = ["simple", "password-hash/getrandom"]
 simple = ["hmac", "dep:password-hash", "dep:phc", "sha2"]
 
 [package.metadata.docs.rs]