docs: add PBKDF2 security notes

README.md

@@ -205,6 +205,14 @@ Parameters:
 For deployments with a server-side *pepper*, use `pbkdf2_with_pepper(password, salt, pepper, iters, dkLen)`.
 The pepper is a secret key stored separately from the hashed password.
 
+### PBKDF2 Security Notes
+
+- Use a random salt of **at least 16 bytes** and never reuse it.
+- Choose an iteration count that takes roughly **200–500 ms** on your target hardware (~2025).
+- Store `{salt, iterations}` alongside 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|…}`.
+
 #### PBKDF2-HMAC-SHA256 + AES-GCM
 
 ```cpp

include/hmac_cpp/hmac_utils.hpp

@@ -54,6 +54,13 @@ 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 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