yescrypt: impl password-hash traits (#765)

Now that the password hash traits have been decoupled from the PHC
format, this impls them for `yescrypt`, replacing the previous `simple`
API with one based on the traits.

In the process this also bumps `mcf` to the latest prerelease which
included some useful changes to make this work.

Author: tarcieri

Cargo.lock

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

Cargo.toml

@@ -22,7 +22,7 @@ base64ct = { version = "1.8", default-features = false, features = ["alloc"] }
 
 # optional dependencies
 getrandom = { version = "0.3", optional = true, default-features = false }
-mcf = { version = "0.2", optional = true, default-features = false, features = ["alloc", "base64"] }
+mcf = { version = "=0.6.0-pre", optional = true, default-features = false, features = ["alloc", "base64"] }
 subtle = { version = "2", optional = true, default-features = false }
 
 [features]

sha-crypt/Cargo.toml

@@ -21,14 +21,15 @@ sha2 = { version = "0.11.0-rc.3", default-features = false }
 subtle = { version = "2", default-features = false }
 
 # optional dependencies
-mcf = { version = "0.2", optional = true, default-features = false, features = ["alloc", "base64"] }
+mcf = { version = "=0.6.0-pre", optional = true, default-features = false, features = ["alloc", "base64"] }
+password-hash = { version = "0.6.0-rc.4", optional = true, default-features = false }
 
 [dev-dependencies]
 hex-literal = "1"
 
 [features]
 default = ["simple"]
-simple = ["dep:mcf"]
+simple = ["dep:mcf", "dep:password-hash"]
 
 [package.metadata.docs.rs]
 all-features = true

yescrypt/Cargo.toml

@@ -9,10 +9,6 @@ pub type Result<T> = core::result::Result<T, Error>;
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 #[non_exhaustive]
 pub enum Error {
-    /// Invalid password hashing algorithm.
-    #[cfg(feature = "simple")]
-    Algorithm,
-
     /// Encoding error (i.e. Base64)
     Encoding,
 
@@ -21,22 +17,14 @@ pub enum Error {
 
     /// Invalid params
     Params,
-
-    /// Invalid password
-    #[cfg(feature = "simple")]
-    Password,
 }
 
 impl fmt::Display for Error {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
-            #[cfg(feature = "simple")]
-            Error::Algorithm => write!(f, "password hash must begin with `$y$`"),
             Error::Encoding => write!(f, "yescrypt encoding invalid"),
             Error::Internal => write!(f, "internal error"),
             Error::Params => write!(f, "yescrypt params invalid"),
-            #[cfg(feature = "simple")]
-            Error::Password => write!(f, "invalid password"),
         }
     }
 }
@@ -48,3 +36,14 @@ impl From<TryFromIntError> for Error {
         Error::Internal
     }
 }
+
+#[cfg(feature = "simple")]
+impl From<Error> for password_hash::Error {
+    fn from(err: Error) -> Self {
+        match err {
+            Error::Encoding => password_hash::Error::EncodingInvalid,
+            Error::Internal => password_hash::Error::Internal,
+            Error::Params => password_hash::Error::ParamsInvalid,
+        }
+    }
+}

yescrypt/src/error.rs

@@ -28,15 +28,16 @@
 //! NOTE: the `simple` crate feature must be enabled (on-by-default)
 #![cfg_attr(feature = "simple", doc = "```")]
 #![cfg_attr(not(feature = "simple"), doc = "```ignore")]
-//! # fn main() -> yescrypt::Result<()> {
+//! # fn main() -> yescrypt::password_hash::Result<()> {
+//! 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 params = yescrypt::Params::default(); // use recommended settings
-//! let password_hash = yescrypt::yescrypt(password, salt, &params)?;
-//! assert!(password_hash.starts_with("$y$"));
+//! let password_hash = Yescrypt.hash_password(password, salt)?;
+//! assert!(password_hash.as_str().starts_with("$y$"));
 //!
 //! // verify password is correct for the given hash
-//! yescrypt::yescrypt_verify(password, &password_hash)?;
+//! Yescrypt.verify_password(password, &password_hash)?;
 //! # Ok(())
 //! # }
 //! ```
@@ -67,6 +68,8 @@ mod mode;
 mod params;
 mod pwxform;
 mod salsa20;
+#[cfg(feature = "simple")]
+mod simple;
 mod smix;
 mod util;
 
@@ -76,96 +79,15 @@ pub use crate::{
     params::Params,
 };
 
-use alloc::vec;
-use sha2::{Digest, Sha256};
-
-#[cfg(feature = "simple")]
-use {alloc::string::String, mcf::Base64};
-
-/// Identifier for yescrypt when encoding to the Modular Crypt Format, i.e. `$y$`
-#[cfg(feature = "simple")]
-const YESCRYPT_MCF_ID: &str = "y";
-
-/// Base64 variant used by yescrypt.
-#[cfg(feature = "simple")]
-const YESCRYPT_BASE64: Base64 = Base64::ShaCrypt;
-
-/// yescrypt password hashing function.
-///
-/// This function produces an (s)crypt-style password hash string starting with the prefix `$y$`.
-///
-/// If using yescrypt as a key derivation, consider [`yescrypt_kdf`] instead.
-#[cfg(feature = "simple")]
-pub fn yescrypt(passwd: &[u8], salt: &[u8], params: &Params) -> Result<String> {
-    // TODO(tarcieri): tunable hash output size?
-    const HASH_SIZE: usize = 32;
-
-    let mut out = [0u8; HASH_SIZE];
-    yescrypt_kdf(passwd, salt, params, &mut out)?;
-
-    // Begin building the Modular Crypt Format hash.
-    let mut mcf_hash = mcf::PasswordHash::from_id(YESCRYPT_MCF_ID).expect("should be valid");
-
-    // Add params string to the hash
-    let mut params_buf = [0u8; Params::MAX_ENCODED_LEN];
-    let params_str = params.encode(&mut params_buf)?;
-    mcf_hash.push_str(params_str).map_err(|_| Error::Encoding)?;
-
-    // Add salt
-    mcf_hash.push_base64(salt, YESCRYPT_BASE64);
-
-    // Add yescrypt output
-    mcf_hash.push_base64(&out, YESCRYPT_BASE64);
-
-    // Convert to a normal `String` to keep `mcf` out of the public API (for now)
-    Ok(mcf_hash.into())
-}
-
-/// Verify a password matches the given yescrypt password hash.
-///
-/// Password hash should begin with `$y$` in Modular Crypt Format (MCF).
 #[cfg(feature = "simple")]
-pub fn yescrypt_verify(passwd: &[u8], hash: &str) -> Result<()> {
-    let hash = mcf::PasswordHashRef::new(hash).map_err(|_| Error::Encoding)?;
-
-    // verify id matches `$y`
-    if hash.id() != YESCRYPT_MCF_ID {
-        return Err(Error::Algorithm);
-    }
-
-    let mut fields = hash.fields();
-
-    // decode params
-    let params: Params = fields.next().ok_or(Error::Encoding)?.as_str().parse()?;
-
-    // decode salt
-    let salt = fields
-        .next()
-        .ok_or(Error::Encoding)?
-        .decode_base64(YESCRYPT_BASE64)
-        .map_err(|_| Error::Encoding)?;
-
-    // decode expected password hash
-    let expected = fields
-        .next()
-        .ok_or(Error::Encoding)?
-        .decode_base64(YESCRYPT_BASE64)
-        .map_err(|_| Error::Encoding)?;
-
-    // should be the last field
-    if fields.next().is_some() {
-        return Err(Error::Encoding);
-    }
-
-    let mut actual = vec![0u8; expected.len()];
-    yescrypt_kdf(passwd, &salt, &params, &mut actual)?;
-
-    if subtle::ConstantTimeEq::ct_ne(actual.as_slice(), &expected).into() {
-        return Err(Error::Password);
-    }
+pub use {
+    mcf::{PasswordHash, PasswordHashRef},
+    password_hash::{self, CustomizedPasswordHasher, PasswordHasher, PasswordVerifier},
+    simple::Yescrypt,
+};
 
-    Ok(())
-}
+use alloc::vec;
+use sha2::{Digest, Sha256};
 
 /// yescrypt Key Derivation Function (KDF)
 pub fn yescrypt_kdf(passwd: &[u8], salt: &[u8], params: &Params, out: &mut [u8]) -> Result<()> {

yescrypt/src/lib.rs

@@ -0,0 +1,121 @@
+//! Implementation of the `password-hash` crate API.
+
+use crate::{Params, yescrypt_kdf};
+use alloc::vec;
+use mcf::{Base64, PasswordHash, PasswordHashRef};
+use password_hash::{
+    CustomizedPasswordHasher, Error, PasswordHasher, PasswordVerifier, Result, Version,
+};
+
+/// Identifier for yescrypt when encoding to the Modular Crypt Format, i.e. `$y$`
+#[cfg(feature = "simple")]
+const YESCRYPT_MCF_ID: &str = "y";
+
+/// Base64 variant used by yescrypt.
+const YESCRYPT_BASE64: Base64 = Base64::ShaCrypt;
+
+/// yescrypt type for use with [`PasswordHasher`].
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub struct Yescrypt;
+
+impl CustomizedPasswordHasher<PasswordHash> for Yescrypt {
+    type Params = Params;
+
+    fn hash_password_customized(
+        &self,
+        password: &[u8],
+        salt: &[u8],
+        alg_id: Option<&str>,
+        version: Option<Version>,
+        params: Params,
+    ) -> Result<PasswordHash> {
+        // TODO(tarcieri): tunable hash output size?
+        const HASH_SIZE: usize = 32;
+
+        match alg_id {
+            Some(YESCRYPT_MCF_ID) | None => (),
+            _ => return Err(Error::Algorithm),
+        }
+
+        if version.is_some() {
+            return Err(Error::Version);
+        }
+
+        let mut out = [0u8; HASH_SIZE];
+        yescrypt_kdf(password, salt, &params, &mut out)?;
+
+        // Begin building the Modular Crypt Format hash.
+        let mut mcf_hash = PasswordHash::from_id(YESCRYPT_MCF_ID).expect("should be valid");
+
+        // Add params string to the hash
+        mcf_hash
+            .push_displayable(params)
+            .map_err(|_| Error::EncodingInvalid)?;
+
+        // Add salt
+        mcf_hash.push_base64(salt, YESCRYPT_BASE64);
+
+        // Add yescrypt password hashing function output
+        mcf_hash.push_base64(&out, YESCRYPT_BASE64);
+
+        Ok(mcf_hash)
+    }
+}
+
+impl PasswordHasher<PasswordHash> for Yescrypt {
+    fn hash_password(&self, password: &[u8], salt: &[u8]) -> Result<PasswordHash> {
+        self.hash_password_customized(password, salt, None, None, Params::default())
+    }
+}
+
+impl PasswordVerifier<PasswordHash> for Yescrypt {
+    fn verify_password(&self, password: &[u8], hash: &PasswordHash) -> Result<()> {
+        self.verify_password(password, hash.as_password_hash_ref())
+    }
+}
+
+impl PasswordVerifier<PasswordHashRef> for Yescrypt {
+    fn verify_password(&self, password: &[u8], hash: &PasswordHashRef) -> Result<()> {
+        // verify id matches `$y`
+        if hash.id() != YESCRYPT_MCF_ID {
+            return Err(Error::Algorithm);
+        }
+
+        let mut fields = hash.fields();
+
+        // decode params
+        let params: Params = fields
+            .next()
+            .ok_or(Error::EncodingInvalid)?
+            .as_str()
+            .parse()?;
+
+        // decode salt
+        let salt = fields
+            .next()
+            .ok_or(Error::EncodingInvalid)?
+            .decode_base64(YESCRYPT_BASE64)
+            .map_err(|_| Error::EncodingInvalid)?;
+
+        // decode expected password hash
+        let expected = fields
+            .next()
+            .ok_or(Error::EncodingInvalid)?
+            .decode_base64(YESCRYPT_BASE64)
+            .map_err(|_| Error::EncodingInvalid)?;
+
+        // should be the last field
+        if fields.next().is_some() {
+            return Err(Error::EncodingInvalid);
+        }
+
+        let mut actual = vec![0u8; expected.len()];
+        yescrypt_kdf(password, &salt, &params, &mut actual)?;
+
+        if subtle::ConstantTimeEq::ct_ne(actual.as_slice(), &expected).into() {
+            return Err(Error::PasswordInvalid);
+        }
+
+        Ok(())
+    }
+}