Rust wrapper: implement password-hash traits

Author: holtrop-wolfssl

wrapper/rust/wolfssl-wolfcrypt/Cargo.lock

@@ -17,6 +17,7 @@ aead = ["dep:aead"]
 cipher = ["dep:cipher"]
 digest = ["dep:digest"]
 signature = ["dep:signature"]
+password-hash = ["dep:password-hash", "password-hash/phc"]
 
 [dependencies]
 rand_core = { version = "0.10", optional = true, default-features = false }
@@ -25,12 +26,14 @@ cipher = { version = "0.5", optional = true, default-features = false }
 digest = { version = "0.11", optional = true, default-features = false, features = ["block-api"] }
 signature = { version = "2.2", optional = true, default-features = false }
 zeroize = { version = "1.3", default-features = false, features = ["derive"] }
+password-hash = { version = "0.6.1", optional = true, default-features = false }
 
 [dev-dependencies]
 aead = { version = "0.5", features = ["alloc", "dev"] }
 cipher = "0.5"
 digest = { version = "0.11", features = ["dev"] }
 signature = "2.2"
+password-hash = { version = "0.6.1", features = ["phc"] }
 
 [build-dependencies]
 bindgen = "0.72.1"

wrapper/rust/wolfssl-wolfcrypt/Cargo.toml

@@ -1,4 +1,4 @@
-FEATURES := rand_core,aead,cipher,digest,signature
+FEATURES := rand_core,aead,cipher,digest,signature,password-hash
 CARGO_FEATURE_FLAGS := --features $(FEATURES)
 
 .PHONY: all

wrapper/rust/wolfssl-wolfcrypt/Makefile

@@ -64,6 +64,8 @@ pub mod rsa;
 #[cfg(feature = "signature")]
 pub mod rsa_pkcs1v15;
 pub mod sha;
+#[cfg(feature = "password-hash")]
+pub mod pbkdf2_password_hash;
 #[cfg(feature = "digest")]
 pub mod sha_digest;
 

wrapper/rust/wolfssl-wolfcrypt/src/lib.rs

@@ -0,0 +1,245 @@
+/*
+ * Copyright (C) 2006-2026 wolfSSL Inc.
+ *
+ * This file is part of wolfSSL.
+ *
+ * wolfSSL is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * wolfSSL is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
+ */
+
+/*!
+RustCrypto `password-hash` trait implementations for wolfCrypt PBKDF2.
+
+This module provides [`Pbkdf2`], a type that implements the
+[`PasswordHasher`] and [`CustomizedPasswordHasher`] traits from the
+`password-hash` crate, backed by the wolfCrypt PBKDF2 implementation.
+The blanket [`PasswordVerifier`] implementation is also available,
+allowing verification of existing password hashes.
+
+Password hashes are represented in the
+[PHC string format](https://github.com/P-H-C/phc-string-format/blob/master/phc-sf-spec.md):
+
+```text
+$pbkdf2-sha256$i=600000$<salt>$<hash>
+```
+
+# Supported algorithms
+
+| Algorithm ID    | Hash function |
+|-----------------|---------------|
+| `pbkdf2-sha256` | HMAC-SHA-256  |
+| `pbkdf2-sha384` | HMAC-SHA-384  |
+| `pbkdf2-sha512` | HMAC-SHA-512  |
+
+[`PasswordHasher`]: password_hash::PasswordHasher
+[`CustomizedPasswordHasher`]: password_hash::CustomizedPasswordHasher
+[`PasswordVerifier`]: password_hash::PasswordVerifier
+*/
+
+#![cfg(all(feature = "password-hash", hmac, kdf_pbkdf2))]
+
+use password_hash::phc::{Ident, Output, ParamsString, PasswordHash, Salt};
+use password_hash::{CustomizedPasswordHasher, Error, Result, Version};
+
+use crate::hmac::HMAC;
+use crate::kdf;
+
+const PBKDF2_SHA256_IDENT: Ident = Ident::new_unwrap("pbkdf2-sha256");
+const PBKDF2_SHA384_IDENT: Ident = Ident::new_unwrap("pbkdf2-sha384");
+const PBKDF2_SHA512_IDENT: Ident = Ident::new_unwrap("pbkdf2-sha512");
+
+/// Minimum number of PBKDF2 rounds.
+pub const MIN_ROUNDS: u32 = 1_000;
+
+/// Default number of PBKDF2 rounds (OWASP recommendation for SHA-256).
+pub const DEFAULT_ROUNDS: u32 = 600_000;
+
+/// Default output length in bytes.
+pub const DEFAULT_OUTPUT_LEN: usize = 32;
+
+/// PBKDF2 algorithm variant.
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
+pub enum Algorithm {
+    /// PBKDF2 with HMAC-SHA-256.
+    #[default]
+    Pbkdf2Sha256,
+    /// PBKDF2 with HMAC-SHA-384.
+    Pbkdf2Sha384,
+    /// PBKDF2 with HMAC-SHA-512.
+    Pbkdf2Sha512,
+}
+
+impl Algorithm {
+    /// Get the PHC string format identifier for this algorithm.
+    pub fn ident(self) -> Ident {
+        match self {
+            Algorithm::Pbkdf2Sha256 => PBKDF2_SHA256_IDENT,
+            Algorithm::Pbkdf2Sha384 => PBKDF2_SHA384_IDENT,
+            Algorithm::Pbkdf2Sha512 => PBKDF2_SHA512_IDENT,
+        }
+    }
+
+    fn hmac_type(self) -> i32 {
+        match self {
+            Algorithm::Pbkdf2Sha256 => HMAC::TYPE_SHA256,
+            Algorithm::Pbkdf2Sha384 => HMAC::TYPE_SHA384,
+            Algorithm::Pbkdf2Sha512 => HMAC::TYPE_SHA512,
+        }
+    }
+}
+
+impl TryFrom<Ident> for Algorithm {
+    type Error = Error;
+
+    fn try_from(ident: Ident) -> Result<Self> {
+        if ident == PBKDF2_SHA256_IDENT {
+            Ok(Algorithm::Pbkdf2Sha256)
+        } else if ident == PBKDF2_SHA384_IDENT {
+            Ok(Algorithm::Pbkdf2Sha384)
+        } else if ident == PBKDF2_SHA512_IDENT {
+            Ok(Algorithm::Pbkdf2Sha512)
+        } else {
+            Err(Error::Algorithm)
+        }
+    }
+}
+
+/// PBKDF2 parameters.
+#[derive(Clone, Debug)]
+pub struct Params {
+    /// Number of iterations (rounds).
+    pub rounds: u32,
+    /// Desired output hash length in bytes.
+    pub output_len: usize,
+}
+
+impl Default for Params {
+    fn default() -> Self {
+        Params {
+            rounds: DEFAULT_ROUNDS,
+            output_len: DEFAULT_OUTPUT_LEN,
+        }
+    }
+}
+
+impl TryFrom<&PasswordHash> for Params {
+    type Error = Error;
+
+    fn try_from(hash: &PasswordHash) -> Result<Self> {
+        let rounds = hash
+            .params
+            .get_decimal("i")
+            .ok_or(Error::ParamInvalid { name: "i" })?;
+
+        if rounds < MIN_ROUNDS {
+            return Err(Error::ParamInvalid { name: "i" });
+        }
+
+        let output_len = if let Some(ref h) = hash.hash {
+            h.len()
+        } else if let Some(l) = hash.params.get_decimal("l") {
+            l as usize
+        } else {
+            return Err(Error::ParamInvalid { name: "l" });
+        };
+
+        Ok(Params { rounds, output_len })
+    }
+}
+
+/// PBKDF2 password hasher backed by wolfCrypt.
+///
+/// Implements the [`PasswordHasher`](password_hash::PasswordHasher) and
+/// [`CustomizedPasswordHasher`] traits. A blanket
+/// [`PasswordVerifier`](password_hash::PasswordVerifier) implementation is
+/// provided by the `password-hash` crate.
+///
+/// # Example
+///
+/// ```rust
+/// #[cfg(all(hmac, kdf_pbkdf2))]
+/// {
+/// use password_hash::PasswordHasher;
+/// use wolfssl_wolfcrypt::pbkdf2_password_hash::Pbkdf2;
+///
+/// let hasher = Pbkdf2::default();
+/// let salt = b"0123456789abcdef"; // 16 bytes
+/// let hash = hasher.hash_password_with_salt(b"password", salt)
+///     .expect("hashing failed");
+/// }
+/// ```
+#[derive(Clone, Debug, Default)]
+pub struct Pbkdf2 {
+    /// Algorithm to use for hashing.
+    pub algorithm: Algorithm,
+    /// Default parameters.
+    pub params: Params,
+}
+
+impl password_hash::PasswordHasher<PasswordHash> for Pbkdf2 {
+    fn hash_password_with_salt(&self, password: &[u8], salt: &[u8]) -> Result<PasswordHash> {
+        self.hash_password_customized(password, salt, None, None, self.params.clone())
+    }
+}
+
+impl password_hash::CustomizedPasswordHasher<PasswordHash> for Pbkdf2 {
+    type Params = Params;
+
+    fn hash_password_customized(
+        &self,
+        password: &[u8],
+        salt: &[u8],
+        algorithm: Option<&str>,
+        version: Option<Version>,
+        params: Params,
+    ) -> Result<PasswordHash> {
+        if version.is_some() {
+            return Err(Error::Version);
+        }
+
+        let algorithm = match algorithm {
+            Some(s) => {
+                let ident = Ident::new(s).map_err(|_| Error::Algorithm)?;
+                Algorithm::try_from(ident)?
+            }
+            None => self.algorithm,
+        };
+
+        if params.rounds < MIN_ROUNDS {
+            return Err(Error::ParamInvalid { name: "i" });
+        }
+
+        let iterations = i32::try_from(params.rounds)
+            .map_err(|_| Error::ParamInvalid { name: "i" })?;
+
+        let salt = Salt::new(salt)?;
+
+        let mut out_buf = [0u8; Output::MAX_LENGTH];
+        let out_slice = &mut out_buf[..params.output_len];
+        kdf::pbkdf2(password, salt.as_ref(), iterations, algorithm.hmac_type(), out_slice)
+            .map_err(|_| Error::Crypto)?;
+        let output = Output::new(out_slice)?;
+
+        let mut phc_params = ParamsString::new();
+        phc_params.add_decimal("i", params.rounds)?;
+
+        Ok(PasswordHash {
+            algorithm: algorithm.ident(),
+            version: None,
+            params: phc_params,
+            salt: Some(salt),
+            hash: Some(output),
+        })
+    }
+}