feat(pbkdf2): add result struct overload

Author: LimiNode

README.md

@@ -190,6 +190,9 @@ Returns: Binary digest as `std::vector<uint8_t>`
 std::string password = "password";
 std::vector<uint8_t> salt(16, 0x01); // at least 16 bytes
 std::vector<uint8_t> dk = hmac::pbkdf2(password, salt, 1000, 32);
+hmac::Pbkdf2Result stored{salt, 1000, dk};
+auto verify = hmac::pbkdf2(password, stored);
+bool ok = hmac::constant_time_equals(verify.key, stored.key);
 ```
 
 Parameters:

include/hmac_cpp/hmac_utils.hpp

@@ -53,14 +53,21 @@ namespace hmac_cpp {
 
     /// \brief Hash choices for PBKDF2
     enum class Pbkdf2Hash { Sha1, Sha256, Sha512 };
-
+  
     /// PBKDF2 Security Notes:
     /// - Use a random salt of at least 16 bytes and never reuse it.
     /// - Choose iterations so the derivation takes about 200–500 ms on 2025 hardware.
     /// - Store {salt, iterations} with the ciphertext or hash; these values are public.
     /// - Salts and iteration counts must be unique per password.
     /// - Example serialization: {magic|ver|prf|salt|iters|dkLen|…}.
 
+    /// \brief
+  struct Pbkdf2Result {
+        std::vector<uint8_t> salt;
+        uint32_t iters;
+        std::vector<uint8_t> key;
+    };
+
     /// \brief Derives a key from a password using PBKDF2 (RFC 8018)
     /// \param password_ptr Pointer to the password buffer
     /// \param password_len Length of the password in bytes
@@ -113,6 +120,39 @@ namespace hmac_cpp {
                       iterations, dk_len, prf);
     }
 
+    template<typename T>
+    inline Pbkdf2Result pbkdf2(
+            const std::vector<T>& password,
+            const Pbkdf2Result& params,
+            Pbkdf2Hash prf = Pbkdf2Hash::Sha256) {
+        static_assert(std::is_same<T, char>::value || std::is_same<T, uint8_t>::value,
+                      "pbkdf2(vector<T>) supports only char or uint8_t");
+        auto key = pbkdf2(password.data(), password.size(),
+                          params.salt.data(), params.salt.size(),
+                          params.iters, params.key.size(), prf);
+        return {params.salt, params.iters, std::move(key)};
+    }
+
+    inline Pbkdf2Result pbkdf2(
+            const std::string& password,
+            const Pbkdf2Result& params,
+            Pbkdf2Hash prf = Pbkdf2Hash::Sha256) {
+        auto key = pbkdf2(password.data(), password.size(),
+                          params.salt.data(), params.salt.size(),
+                          params.iters, params.key.size(), prf);
+        return {params.salt, params.iters, std::move(key)};
+    }
+
+    inline Pbkdf2Result pbkdf2(
+            const secure_buffer<uint8_t>& password,
+            const Pbkdf2Result& params,
+            Pbkdf2Hash prf = Pbkdf2Hash::Sha256) {
+        auto key = pbkdf2(password.data(), password.size(),
+                          params.salt.data(), params.salt.size(),
+                          params.iters, params.key.size(), prf);
+        return {params.salt, params.iters, std::move(key)};
+    }
+
     /// \brief Derives PBKDF2 into caller-provided buffer using selected hash.
     /// \param prf Hash function to use (SHA1, SHA256, SHA512)
     /// \param password_ptr Pointer to the password buffer

test_all.cpp

@@ -361,6 +361,15 @@ TEST(PBKDF2Test, SHA256WithValidSalt) {
     EXPECT_TRUE(hmac::constant_time_equals(dk, ref));
 }
 
+TEST(PBKDF2ResultTest, ComputesFromStoredParams) {
+    auto salt = from_hex("000102030405060708090a0b0c0d0e0f");
+    std::string salt_str(salt.begin(), salt.end());
+    auto dk = hmac::pbkdf2(std::string("password"), salt_str, 2, 32, hmac::Pbkdf2Hash::Sha256);
+    hmac::Pbkdf2Result stored{salt, 2, dk};
+    auto out = hmac::pbkdf2(std::string("password"), stored);
+    EXPECT_TRUE(hmac::constant_time_equals(out.key, stored.key));
+}
+
 TEST(PBKDF2BufferApiTest, SHA256ArrayOutput) {
     auto salt = from_hex("000102030405060708090a0b0c0d0e0f");
     std::string salt_str(salt.begin(), salt.end());