pbkdf2: initial MCF (Customized)PasswordHasher support

Initial support for computing password hash strings in
Modular Crypt Format (MCF) instead of the PHC string format.

Tested against a vector from passlib:

https://passlib.readthedocs.io/en/stable/lib/passlib.hash.pbkdf2_digest.html

Author: tarcieri

.readme/Cargo.toml

@@ -8,5 +8,5 @@ publish = false
 [dependencies]
 password-hash = "0.6.0-rc.3"
 argon2 = { path = "../argon2" }
-pbkdf2 = { path = "../pbkdf2", features = ["password-hash"] }
+pbkdf2 = { path = "../pbkdf2", features = ["phc"] }
 scrypt = { path = "../scrypt", features = ["phc"] }

Cargo.lock

@@ -20,3 +20,5 @@ opt-level = 2
 argon2 = { path = "./argon2" }
 pbkdf2 = { path = "./pbkdf2" }
 scrypt = { path = "./scrypt" }
+
+password-hash = { git = "https://github.com/RustCrypto/traits" }

Cargo.toml

@@ -22,7 +22,7 @@ password-hash = { version = "0.6.0-rc.7", features = ["alloc", "getrandom", "phc
 
 # optional dependencies
 argon2 = { version = "0.6.0-rc.5", optional = true, default-features = false, features = ["alloc", "password-hash"] }
-pbkdf2 = { version = "0.13.0-rc.5", optional = true, default-features = false, features = ["password-hash"] }
+pbkdf2 = { version = "0.13.0-rc.5", optional = true, default-features = false, features = ["phc"] }
 scrypt = { version = "0.12.0-rc.6", optional = true, default-features = false, features = ["phc"] }
 
 [features]

password-auth/Cargo.toml

@@ -122,7 +122,7 @@ pub fn is_hash_obsolete(hash: &str) -> Result<bool, ParseError> {
         || hash.params != default_params_string::<scrypt::Params>());
 
     #[cfg(feature = "pbkdf2")]
-    return Ok(hash.algorithm != *pbkdf2::Algorithm::default().ident()
+    return Ok(hash.algorithm != pbkdf2::Algorithm::default().into()
         || hash.params != default_params_string::<pbkdf2::Params>());
 
     Ok(true)

password-auth/src/lib.rs

@@ -18,7 +18,8 @@ digest = { version = "0.11.0-rc.4", features = ["mac"] }
 
 # optional dependencies
 hmac = { version = "0.13.0-rc.3", default-features = false, optional = true }
-password-hash = { version = "0.6.0-rc.7", default-features = false, optional = true, features = ["phc"] }
+mcf = { version = "0.6.0-rc.2", optional = true }
+password-hash = { version = "0.6.0-rc.7", default-features = false, optional = true }
 sha1 = { version = "0.11.0-rc.3", default-features = false, optional = true }
 sha2 = { version = "0.11.0-rc.3", default-features = false, optional = true }
 
@@ -32,8 +33,9 @@ belt-hash = "0.2.0-rc.3"
 
 [features]
 default = ["hmac"]
-getrandom = ["password-hash", "password-hash/getrandom"]
-password-hash = ["hmac", "dep:password-hash", "sha2"]
+getrandom = ["password-hash/getrandom"]
+mcf = ["hmac", "password-hash/alloc", "dep:mcf", "sha2"]
+phc = ["hmac", "password-hash/phc", "sha2"]
 rand_core = ["password-hash/rand_core"]
 
 [package.metadata.docs.rs]

pbkdf2/Cargo.toml

@@ -2,7 +2,10 @@ use core::{
     fmt::{self, Display},
     str::FromStr,
 };
-use password_hash::{Error, phc::Ident};
+use password_hash::Error;
+
+#[cfg(feature = "phc")]
+use password_hash::phc::Ident;
 
 /// PBKDF2 variants.
 ///
@@ -24,13 +27,25 @@ pub enum Algorithm {
 impl Algorithm {
     /// PBKDF2 (SHA-1) algorithm identifier
     #[cfg(feature = "sha1")]
-    pub const PBKDF2_SHA1_IDENT: Ident = Ident::new_unwrap("pbkdf2");
+    pub const PBKDF2_SHA1_ID: &'static str = "pbkdf2";
 
     /// PBKDF2 (SHA-256) algorithm identifier
-    pub const PBKDF2_SHA256_IDENT: Ident = Ident::new_unwrap("pbkdf2-sha256");
+    pub const PBKDF2_SHA256_ID: &'static str = "pbkdf2-sha256";
 
     /// PBKDF2 (SHA-512) algorithm identifier
-    pub const PBKDF2_SHA512_IDENT: Ident = Ident::new_unwrap("pbkdf2-sha512");
+    pub const PBKDF2_SHA512_ID: &'static str = "pbkdf2-sha512";
+
+    /// PBKDF2 (SHA-1) algorithm identifier
+    #[cfg(all(feature = "phc", feature = "sha1"))]
+    pub(crate) const PBKDF2_SHA1_IDENT: Ident = Ident::new_unwrap(Self::PBKDF2_SHA1_ID);
+
+    /// PBKDF2 (SHA-256) algorithm identifier
+    #[cfg(feature = "phc")]
+    pub(crate) const PBKDF2_SHA256_IDENT: Ident = Ident::new_unwrap(Self::PBKDF2_SHA256_ID);
+
+    /// PBKDF2 (SHA-512) algorithm identifier
+    #[cfg(feature = "phc")]
+    pub(crate) const PBKDF2_SHA512_IDENT: Ident = Ident::new_unwrap(Self::PBKDF2_SHA512_ID);
 
     /// Default algorithm suggested by the [OWASP cheat sheet]:
     ///
@@ -45,25 +60,20 @@ impl Algorithm {
         id.as_ref().parse()
     }
 
-    /// Get the [`Ident`] that corresponds to this PBKDF2 [`Algorithm`].
-    pub fn ident(&self) -> &'static Ident {
+    /// Get the Modular Crypt Format algorithm identifier for this algorithm.
+    pub const fn to_str(self) -> &'static str {
         match self {
             #[cfg(feature = "sha1")]
-            Algorithm::Pbkdf2Sha1 => &Self::PBKDF2_SHA1_IDENT,
-            Algorithm::Pbkdf2Sha256 => &Self::PBKDF2_SHA256_IDENT,
-            Algorithm::Pbkdf2Sha512 => &Self::PBKDF2_SHA512_IDENT,
+            Algorithm::Pbkdf2Sha1 => Self::PBKDF2_SHA1_ID,
+            Algorithm::Pbkdf2Sha256 => Self::PBKDF2_SHA256_ID,
+            Algorithm::Pbkdf2Sha512 => Self::PBKDF2_SHA512_ID,
         }
     }
-
-    /// Get the identifier string for this PBKDF2 [`Algorithm`].
-    pub fn as_str(&self) -> &str {
-        self.ident().as_str()
-    }
 }
 
 impl AsRef<str> for Algorithm {
     fn as_ref(&self) -> &str {
-        self.as_str()
+        self.to_str()
     }
 }
 
@@ -75,7 +85,7 @@ impl Default for Algorithm {
 
 impl Display for Algorithm {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str(self.as_str())
+        f.write_str(self.to_str())
     }
 }
 
@@ -87,21 +97,27 @@ impl FromStr for Algorithm {
     }
 }
 
+#[cfg(feature = "phc")]
 impl From<Algorithm> for Ident {
     fn from(alg: Algorithm) -> Ident {
-        *alg.ident()
+        match alg {
+            #[cfg(feature = "sha1")]
+            Algorithm::Pbkdf2Sha1 => Algorithm::PBKDF2_SHA1_IDENT,
+            Algorithm::Pbkdf2Sha256 => Algorithm::PBKDF2_SHA256_IDENT,
+            Algorithm::Pbkdf2Sha512 => Algorithm::PBKDF2_SHA512_IDENT,
+        }
     }
 }
 
 impl<'a> TryFrom<&'a str> for Algorithm {
     type Error = Error;
 
     fn try_from(name: &'a str) -> password_hash::Result<Algorithm> {
-        match name.try_into() {
+        match name {
             #[cfg(feature = "sha1")]
-            Ok(Self::PBKDF2_SHA1_IDENT) => Ok(Algorithm::Pbkdf2Sha1),
-            Ok(Self::PBKDF2_SHA256_IDENT) => Ok(Algorithm::Pbkdf2Sha256),
-            Ok(Self::PBKDF2_SHA512_IDENT) => Ok(Algorithm::Pbkdf2Sha512),
+            Self::PBKDF2_SHA1_ID => Ok(Algorithm::Pbkdf2Sha1),
+            Self::PBKDF2_SHA256_ID => Ok(Algorithm::Pbkdf2Sha256),
+            Self::PBKDF2_SHA512_ID => Ok(Algorithm::Pbkdf2Sha512),
             _ => Err(Error::Algorithm),
         }
     }

pbkdf2/src/algorithm.rs

@@ -21,6 +21,10 @@
 //!
 //! [KDF]: https://github.com/RustCrypto/KDFs
 //!
+//! ## Low-level API
+//!
+//! This API operates directly on byte slices:
+//!
 //! ```
 //! # #[cfg(feature = "hmac")] {
 //! use hex_literal::hex;
@@ -57,49 +61,54 @@
 //! rand_core = { version = "0.6", features = ["std"] }
 //! ```
 //!
+//! ## PHC string API
+//!
+//! This crate can produce and verify password hash strings encoded in the Password Hashing
+//! Competition (PHC) string format.
+//!
 //! The following example demonstrates the high-level password hashing API:
 //!
-#![cfg_attr(feature = "password-hash", doc = "```")]
-#![cfg_attr(not(feature = "password-hash"), doc = "```ignore")]
+#![cfg_attr(all(feature = "getrandom", feature = "phc"), doc = "```")]
+#![cfg_attr(not(all(feature = "getrandom", feature = "phc")), doc = "```ignore")]
 //! # fn main() -> Result<(), Box<dyn core::error::Error>> {
 //! // NOTE: example requires `getrandom` feature is enabled
 //!
 //! use pbkdf2::{
-//!     password_hash::{PasswordHasher, PasswordVerifier, phc::PasswordHash},
+//!     password_hash::{PasswordHasher, PasswordVerifier},
+//!     phc::PasswordHash,
 //!     Pbkdf2
 //! };
 //!
 //! let pbkdf2 = Pbkdf2::default(); // Uses `Algorithm::default()` and `Params::RECOMMENDED`
 //! let password = b"hunter2"; // Bad password; don't actually use!
 //!
 //! // Hash password to PHC string ($pbkdf2-sha256$...)
-//! let password_hash = pbkdf2.hash_password(password)?.to_string();
+//! let pwhash: PasswordHash = pbkdf2.hash_password(password)?;
+//! let pwhash_string = pwhash.to_string();
 //!
 //! // Verify password against PHC string
-//! let parsed_hash = PasswordHash::new(&password_hash)?;
-//! assert!(pbkdf2.verify_password(password, &parsed_hash).is_ok());
+//! let parsed_hash = PasswordHash::new(&pwhash_string)?;
+//! pbkdf2.verify_password(password, &parsed_hash)?;
 //! # Ok(())
 //! # }
 //! ```
 
-#[cfg(feature = "password-hash")]
-extern crate alloc;
-
-#[cfg(feature = "password-hash")]
-pub use password_hash;
+#[cfg(feature = "mcf")]
+pub mod mcf;
+#[cfg(feature = "phc")]
+pub mod phc;
 
-#[cfg(feature = "password-hash")]
+#[cfg(any(feature = "mcf", feature = "phc"))]
 mod algorithm;
-#[cfg(feature = "password-hash")]
+#[cfg(any(feature = "mcf", feature = "phc"))]
 mod params;
-#[cfg(feature = "password-hash")]
-mod phc;
 
+#[cfg(any(feature = "mcf", feature = "phc"))]
+pub use crate::{algorithm::Algorithm, params::Params};
 #[cfg(feature = "hmac")]
 pub use hmac;
-
-#[cfg(feature = "password-hash")]
-pub use crate::{algorithm::Algorithm, params::Params, phc::Pbkdf2};
+#[cfg(any(feature = "mcf", feature = "phc"))]
+pub use password_hash;
 
 use digest::{FixedOutput, InvalidLength, KeyInit, Update, typenum::Unsigned};
 
@@ -242,3 +251,42 @@ where
     pbkdf2_hmac::<D>(password, salt, rounds, &mut buf);
     buf
 }
+
+/// PBKDF2 type for use with [`PasswordHasher`].
+#[cfg(any(feature = "mcf", feature = "phc"))]
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub struct Pbkdf2 {
+    /// Algorithm to use
+    algorithm: Algorithm,
+
+    /// Default parameters to use.
+    params: Params,
+}
+
+#[cfg(any(feature = "mcf", feature = "phc"))]
+impl Pbkdf2 {
+    /// Initialize [`Pbkdf2`] with default parameters.
+    pub const fn new(algorithm: Algorithm, params: Params) -> Self {
+        Self { algorithm, params }
+    }
+}
+
+#[cfg(any(feature = "mcf", feature = "phc"))]
+impl From<Algorithm> for Pbkdf2 {
+    fn from(algorithm: Algorithm) -> Self {
+        Self {
+            algorithm,
+            params: Params::default(),
+        }
+    }
+}
+
+#[cfg(any(feature = "mcf", feature = "phc"))]
+impl From<Params> for Pbkdf2 {
+    fn from(params: Params) -> Self {
+        Self {
+            algorithm: Algorithm::default(),
+            params,
+        }
+    }
+}