password-hash: add generic H param to traits (#2110)

Adds a generic `H` parameter to the `(Customized)PasswordHasher` and
`PasswordVerifier` traits which specifies the return type and the hash
type respectively.

A generic parameter is used instead of an associated constant in order
to support overlapping impls. Notably multiple commonly used password
hashing algorithms (e.g. PBKDF2, scrypt) support encoding in either the
Modular Crypt Format (MCF) or Password Hashing Competition (PHC) string
format, which are implemented as the `mcf::PasswordHash` and
`phc::PasswordHash` types respectively.

We already have open issues to add MCF support where we currently don't
support it (RustCrypto/password-hashes#727,
RustCrypto/password-hashes#747).

The blanket impl of `PasswordVerifier` for `CustomizedPasswordHasher` is
retained, but only for `phc::PasswordHash`, as supporting it for MCF
requires algorithmic-specific interpretation of the hash. However,
algorithms can provide their own impls of
`PasswordVerifier<mcf::PasswordHash>`.

Author: tarcieri

password-hash/src/lib.rs

@@ -49,16 +49,20 @@ use core::{
 pub type Version = u32;
 
 /// Trait for password hashing functions.
-pub trait PasswordHasher {
+///
+/// Generic around a password hash to be returned (typically [`PasswordHash`])
+pub trait PasswordHasher<H> {
     /// Simple API for computing a [`PasswordHash`] from a password and
     /// salt value.
     ///
     /// Uses the default recommended parameters for a given algorithm.
-    fn hash_password(&self, password: &[u8], salt: &[u8]) -> Result<PasswordHash>;
+    fn hash_password(&self, password: &[u8], salt: &[u8]) -> Result<H>;
 }
 
 /// Trait for password hashing functions which support customization.
-pub trait CustomizedPasswordHasher {
+///
+/// Generic around a password hash to be returned (typically [`PasswordHash`])
+pub trait CustomizedPasswordHasher<H> {
     /// Algorithm-specific parameters.
     type Params: Clone + Debug + Default + Display + FromStr<Err = Error>;
 
@@ -74,24 +78,26 @@ pub trait CustomizedPasswordHasher {
         algorithm: Option<&str>,
         version: Option<Version>,
         params: Self::Params,
-    ) -> Result<PasswordHash>;
+    ) -> Result<H>;
 }
 
 /// Trait for password verification.
 ///
-/// Automatically impl'd for any type that impls [`PasswordHasher`].
+/// Generic around a password hash to be returned (typically [`PasswordHash`])
+///
+/// Automatically impl'd for any type that impls [`PasswordHasher`] with [`PasswordHash`] as `H`.
 ///
 /// This trait is object safe and can be used to implement abstractions over
 /// multiple password hashing algorithms. One such abstraction is provided by
 /// the [`PasswordHash::verify_password`] method.
-pub trait PasswordVerifier {
+pub trait PasswordVerifier<H> {
     /// Compute this password hashing function against the provided password
     /// using the parameters from the provided password hash and see if the
     /// computed output matches.
-    fn verify_password(&self, password: &[u8], hash: &PasswordHash) -> Result<()>;
+    fn verify_password(&self, password: &[u8], hash: &H) -> Result<()>;
 }
 
-impl<T: CustomizedPasswordHasher> PasswordVerifier for T {
+impl<T: CustomizedPasswordHasher<PasswordHash>> PasswordVerifier<PasswordHash> for T {
     fn verify_password(&self, password: &[u8], hash: &PasswordHash) -> Result<()> {
         #[allow(clippy::single_match)]
         match (&hash.salt, &hash.hash) {
@@ -136,7 +142,7 @@ pub trait McfHasher {
     /// Verify a password hash in MCF format against the provided password.
     fn verify_mcf_hash(&self, password: &[u8], mcf_hash: &str) -> Result<()>
     where
-        Self: PasswordVerifier,
+        Self: PasswordVerifier<PasswordHash>,
     {
         self.verify_password(password, &self.upgrade_mcf_hash(mcf_hash)?)
     }

password-hash/src/phc.rs

@@ -158,7 +158,7 @@ impl PasswordHash {
 
     /// Generate a password hash using the supplied algorithm.
     pub fn generate(
-        phf: impl PasswordHasher,
+        phf: impl PasswordHasher<Self>,
         password: impl AsRef<[u8]>,
         salt: &[u8],
     ) -> crate::Result<Self> {
@@ -169,7 +169,7 @@ impl PasswordHash {
     /// [`PasswordHasher`] trait objects.
     pub fn verify_password(
         &self,
-        phfs: &[&dyn PasswordVerifier],
+        phfs: &[&dyn PasswordVerifier<Self>],
         password: impl AsRef<[u8]>,
     ) -> crate::Result<()> {
         for &phf in phfs {

password-hash/tests/hashing.rs

@@ -1,9 +1,8 @@
 //! Password hashing tests
 
 use core::{fmt::Display, str::FromStr};
-use password_hash::PasswordHasher;
-pub use password_hash::{
-    CustomizedPasswordHasher,
+use password_hash::{
+    CustomizedPasswordHasher, PasswordHasher,
     errors::{Error, Result},
     phc::{Decimal, Ident, Output, ParamsString, PasswordHash, Salt},
 };
@@ -13,13 +12,7 @@ const ALG: Ident = Ident::new_unwrap("example");
 /// Stub password hashing function for testing.
 pub struct StubPasswordHasher;
 
-impl PasswordHasher for StubPasswordHasher {
-    fn hash_password(&self, password: &[u8], salt: &[u8]) -> Result<PasswordHash> {
-        self.hash_password_customized(password, salt, None, None, StubParams)
-    }
-}
-
-impl CustomizedPasswordHasher for StubPasswordHasher {
+impl CustomizedPasswordHasher<PasswordHash> for StubPasswordHasher {
     type Params = StubParams;
 
     fn hash_password_customized(
@@ -55,6 +48,12 @@ impl CustomizedPasswordHasher for StubPasswordHasher {
     }
 }
 
+impl PasswordHasher<PasswordHash> for StubPasswordHasher {
+    fn hash_password(&self, password: &[u8], salt: &[u8]) -> Result<PasswordHash> {
+        self.hash_password_customized(password, salt, None, None, StubParams)
+    }
+}
+
 /// Stub parameters
 #[derive(Clone, Debug, Default)]
 pub struct StubParams;