Add unit tests for Pbkdf2PasswordHashService

Vadim Belov · Vadim Belov · commit c6eed0bb5e0c · 2025-09-10T11:20:37.000-07:00
Introduce `CryptographyTests` to validate password hashing functionality, covering performance, correctness, and error handling. Update `Pbkdf2PasswordHashService` to enforce input validation, set default iterations to 210,000, and improve documentation on security practices.
diff --git a/Sources/EasyExtensions.Tests/CryptographyTests.cs b/Sources/EasyExtensions.Tests/CryptographyTests.cs
@@ -0,0 +1,225 @@
+﻿using System;
+using System.Text;
+using EasyExtensions.Services;
+using System.Security.Cryptography;
+using System.Diagnostics;
+using NUnit.Framework.Internal;
+
+namespace EasyExtensions.Tests
+{
+    [TestFixture]
+    internal class CryptographyTests
+    {
+        private const string ValidPepper = "this-is-a-valid-test-pepper-12345"; // >16 bytes
+
+        [Test]
+        public void HashIterationDuration_IsAtLeast200ms()
+        {
+            const int expectedMinDurationMs = 200; // 100 ms
+            Stopwatch stopwatch = Stopwatch.StartNew();
+            var svc = new Pbkdf2PasswordHashService(ValidPepper);
+            var password = "SomePassword!";
+            svc.Hash(password);
+            Assert.That(stopwatch.ElapsedMilliseconds, Is.GreaterThanOrEqualTo(expectedMinDurationMs), 
+                $"Hashing should take at least {expectedMinDurationMs} ms to be secure enough. " +
+                $"If your hardware is very fast, consider increasing the default iteration count in the Pbkdf2PasswordHashService constructor.");
+        }
+
+        [Test]
+        public void Hash_And_Verify_Success()
+        {
+            var svc = new Pbkdf2PasswordHashService(ValidPepper, version: 1, iterations: 5_000);
+            var password = "SuperSecret!";
+
+            var phc = svc.Hash(password);
+            var ok = svc.Verify(password, phc, out var needsRehash);
+
+            using (Assert.EnterMultipleScope())
+            {
+                Assert.That(ok, Is.True);
+                Assert.That(needsRehash, Is.False);
+            }
+        }
+
+        [Test]
+        public void Verify_WrongPassword_Fails()
+        {
+            var svc = new Pbkdf2PasswordHashService(ValidPepper, iterations: 3_000);
+            var phc = svc.Hash("CorrectHorseBatteryStaple");
+
+            var ok = svc.Verify("wrong-password", phc, out var needsRehash);
+
+            using (Assert.EnterMultipleScope())
+            {
+                Assert.That(ok, Is.False);
+                Assert.That(needsRehash, Is.False);
+            }
+        }
+
+        [Test]
+        public void Verify_WrongPepper_Fails()
+        {
+            var svc1 = new Pbkdf2PasswordHashService(ValidPepper, iterations: 2_000);
+            var svc2 = new Pbkdf2PasswordHashService(ValidPepper + "-different", iterations: 2_000);
+            var password = "Pa$$w0rd";
+
+            var phc = svc1.Hash(password);
+            var ok = svc2.Verify(password, phc, out var needsRehash);
+
+            using (Assert.EnterMultipleScope())
+            {
+                Assert.That(ok, Is.False);
+                Assert.That(needsRehash, Is.False);
+            }
+        }
+
+        [Test]
+        public void Hash_ProducesDifferentHashes_DueToRandomSalt()
+        {
+            var svc = new Pbkdf2PasswordHashService(ValidPepper, iterations: 2_000);
+            var password = "same-password";
+
+            var phc1 = svc.Hash(password);
+            var phc2 = svc.Hash(password);
+
+            Assert.That(phc1, Is.Not.EqualTo(phc2));
+        }
+
+        [Test]
+        public void Hash_Format_IsValidPHC()
+        {
+            var iterations = 1_500;
+            var svc = new Pbkdf2PasswordHashService(ValidPepper, version: 1, iterations: iterations);
+            var phc = svc.Hash("abc");
+
+            // $pbkdf2-sha256$v=1$i=ITER$SALT$HASH
+            Assert.That(phc, Does.StartWith("$pbkdf2-sha256$v=1$i=" + iterations + "$"));
+
+            var parts = phc.Split('$', StringSplitOptions.RemoveEmptyEntries);
+            Assert.That(parts, Has.Length.EqualTo(5));
+            using (Assert.EnterMultipleScope())
+            {
+                Assert.That(parts[0], Is.EqualTo("pbkdf2-sha256"));
+                Assert.That(parts[1], Does.StartWith("v="));
+                Assert.That(parts[2], Does.StartWith("i="));
+                // Salt and hash should be valid base64
+                Assert.That(() => Convert.FromBase64String(parts[3]), Throws.Nothing);
+                Assert.That(() => Convert.FromBase64String(parts[4]), Throws.Nothing);
+            }
+        }
+
+        [Test]
+        public void Verify_NeedsRehash_WhenVersionIncreased()
+        {
+            var svcV1 = new Pbkdf2PasswordHashService(ValidPepper, version: 1, iterations: 2_000);
+            var phc = svcV1.Hash("pwd");
+
+            var svcV2 = new Pbkdf2PasswordHashService(ValidPepper, version: 2, iterations: 2_000);
+            var ok = svcV2.Verify("pwd", phc, out var needsRehash);
+
+            using (Assert.EnterMultipleScope())
+            {
+                Assert.That(ok, Is.True);
+                Assert.That(needsRehash, Is.True);
+            }
+        }
+
+        [Test]
+        public void Verify_NeedsRehash_WhenIterationsIncreased()
+        {
+            var svcLow = new Pbkdf2PasswordHashService(ValidPepper, version: 1, iterations: 1_000);
+            var phc = svcLow.Hash("pwd");
+
+            var svcHigh = new Pbkdf2PasswordHashService(ValidPepper, version: 1, iterations: 2_000);
+            var ok = svcHigh.Verify("pwd", phc, out var needsRehash);
+
+            using (Assert.EnterMultipleScope())
+            {
+                Assert.That(ok, Is.True);
+                Assert.That(needsRehash, Is.True);
+            }
+        }
+
+        [Test]
+        public void Verify_NeedsRehash_WhenHashSizeDifferent()
+        {
+            // Arrange
+            var password = "pwd";
+            var iterations = 1_000;
+            var svc = new Pbkdf2PasswordHashService(ValidPepper, version: 1, iterations: iterations);
+            var phc = svc.Hash(password);
+
+            var parts = phc.Split('$', StringSplitOptions.RemoveEmptyEntries);
+            var salt = Convert.FromBase64String(parts[3]);
+
+            // Re-derive the input the same way as service does
+            var key = Encoding.UTF8.GetBytes(ValidPepper);
+            var pwdBytes = Encoding.UTF8.GetBytes(password);
+            using var h = new HMACSHA256(key);
+            var input = h.ComputeHash(pwdBytes);
+
+            using var pbkdf2 = new Rfc2898DeriveBytes(input, salt, iterations, HashAlgorithmName.SHA256);
+            var shortHash = pbkdf2.GetBytes(16); // smaller than default 32
+            var phcShort = "$pbkdf2-sha256$" + parts[1] + "$" + parts[2] + "$" + parts[3] + "$" + Convert.ToBase64String(shortHash);
+
+            // Act
+            var ok = svc.Verify(password, phcShort, out var needsRehash);
+
+            using (Assert.EnterMultipleScope())
+            {
+                // Assert
+                Assert.That(ok, Is.True);
+                Assert.That(needsRehash, Is.True);
+            }
+        }
+
+        [Test]
+        public void Constructor_InvalidPepper_Throws()
+        {
+            Assert.Throws<ArgumentException>(() => new Pbkdf2PasswordHashService("   "));
+            Assert.Throws<ArgumentException>(() => new Pbkdf2PasswordHashService("short-pepper")); // < 16 bytes
+        }
+
+        [Test]
+        public void Constructor_InvalidParameters_Throw()
+        {
+            Assert.Throws<ArgumentOutOfRangeException>(() => new Pbkdf2PasswordHashService(ValidPepper, version: 0));
+            Assert.Throws<ArgumentOutOfRangeException>(() => new Pbkdf2PasswordHashService(ValidPepper, iterations: 0));
+        }
+
+        [Test]
+        public void Hash_NullOrWhitespacePassword_Throws()
+        {
+            var svc = new Pbkdf2PasswordHashService(ValidPepper);
+            Assert.Throws<ArgumentNullException>(() => svc.Hash(null!));
+            Assert.Throws<ArgumentNullException>(() => svc.Hash("   "));
+        }
+
+        [Test]
+        public void Verify_NullOrWhitespacePassword_Throws()
+        {
+            var svc = new Pbkdf2PasswordHashService(ValidPepper, iterations: 1_000);
+            var phc = svc.Hash("pwd");
+
+            Assert.Throws<ArgumentNullException>(() => svc.Verify(null!, phc, out _));
+            Assert.Throws<ArgumentNullException>(() => svc.Verify("   ", phc, out _));
+        }
+
+        [Test]
+        public void Verify_InvalidPhc_ReturnsFalse()
+        {
+            var svc = new Pbkdf2PasswordHashService(ValidPepper, iterations: 1_000);
+
+            using (Assert.EnterMultipleScope())
+            {
+                Assert.That(svc.Verify("pwd", null!, out _), Is.False);
+                Assert.That(svc.Verify("pwd", "", out _), Is.False);
+                Assert.That(svc.Verify("pwd", "$wrongprefix$v=1$i=1$AAAA$BBBB", out _), Is.False);
+                Assert.That(svc.Verify("pwd", "$pbkdf2-sha256$v=x$i=1$AAAA$BBBB", out _), Is.False);
+                Assert.That(svc.Verify("pwd", "$pbkdf2-sha256$v=1$i=x$AAAA$BBBB", out _), Is.False);
+                Assert.That(svc.Verify("pwd", "$pbkdf2-sha256$v=1$i=1$not-base64$still-not", out _), Is.False);
+                Assert.That(svc.Verify("pwd", "$pbkdf2-sha256$v=1$i=1$AAAA", out _), Is.False); // not enough parts
+            }
+        }
+    }
+}
diff --git a/Sources/EasyExtensions/Services/Pbkdf2PasswordHashService.cs b/Sources/EasyExtensions/Services/Pbkdf2PasswordHashService.cs
@@ -0,0 +1,154 @@
+﻿using System;
+using System.Text;
+using System.Security.Cryptography;
+
+namespace EasyExtensions.Services
+{
+    /// <summary>
+    /// PBKDF2 password hashing service using HMAC-SHA256.
+    /// </summary>
+    public class Pbkdf2PasswordHashService
+    {
+        private readonly int _version;
+        private readonly string _pepper;
+        private readonly int _iterations;
+
+        private const int SaltSize = 16;
+        private const int HashSize = 32;
+        private const string Prefix = "pbkdf2-sha256";
+        private readonly HashAlgorithmName _hashAlgorithm = HashAlgorithmName.SHA256;
+
+        /// <summary>
+        /// Creates a new instance of the Pbkdf2PasswordHashService.
+        /// </summary>
+        /// <param name="pepper">A secret value that is used in addition to the password. Must be at least 16 bytes (UTF-8).</param>
+        /// <param name="version">The version of the hashing algorithm. Must be greater than 0. Default is 1.</param>
+        /// <param name="iterations">The number of iterations for the PBKDF2 algorithm. Must be greater than 0. Default is 210,000.</param>
+        /// <exception cref="ArgumentException">Thrown when the pepper is null, whitespace, or less than 16 bytes (UTF-8).</exception>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown when the version or iterations are less than 1.</exception>
+        /// <remarks>
+        /// The pepper should be a long, random string that is kept secret and not stored in the database.
+        /// It is recommended to use a unique pepper for each application.
+        /// The default number of iterations is set to 210,000 as of 2025, which is a good balance between security and performance.
+        /// Consider increasing this value as hardware capabilities improve over time.
+        /// </remarks>
+        public Pbkdf2PasswordHashService(string pepper, int version = 1, int iterations = 210_000)
+        {
+            if (string.IsNullOrWhiteSpace(pepper))
+            {
+                throw new ArgumentException("Pepper cannot be null or whitespace.", nameof(pepper));
+            }
+
+            if (Encoding.UTF8.GetByteCount(pepper) < 16)
+            {
+                throw new ArgumentException("Pepper must be at least 16 bytes (UTF-8).", nameof(pepper));
+            }
+
+            if (version < 1)
+            {
+                throw new ArgumentOutOfRangeException(nameof(version), "Version must be greater than 0.");
+            }
+
+            if (iterations < 1)
+            {
+                throw new ArgumentOutOfRangeException(nameof(iterations), "Iterations must be greater than 0.");
+            }
+
+            _pepper = pepper;
+            _version = version;
+            _iterations = iterations;
+        }
+
+        /// <summary>
+        /// Creates a password hash in PHC format like:
+        /// $pbkdf2-sha256$v=1$i=210000$[saltB64]$[hashB64]
+        /// </summary>
+        public string Hash(string password)
+        {
+            if (string.IsNullOrWhiteSpace(password))
+            {
+                throw new ArgumentNullException(nameof(password));
+            }
+
+            byte[] saltBytes = new byte[SaltSize];
+            RandomNumberGenerator.Create().GetBytes(saltBytes);
+            var input = DeriveInput(password, _pepper);
+            using var pbkdf2 = new Rfc2898DeriveBytes(input, saltBytes, _iterations, _hashAlgorithm);
+            var hash = pbkdf2.GetBytes(HashSize);
+            string hashB64 = Convert.ToBase64String(hash);
+            string saltB64 = Convert.ToBase64String(saltBytes);
+            return $"${Prefix}$v={_version}$i={_iterations}${saltB64}${hashB64}";
+        }
+
+        /// <summary>
+        /// Checks the password against the given PHC hash.
+        /// </summary>
+        public bool Verify(string password, string phc, out bool needsRehash)
+        {
+            needsRehash = false;
+
+            if (string.IsNullOrWhiteSpace(phc))
+            {
+                return false;
+            }
+            if (string.IsNullOrWhiteSpace(password))
+            {
+                throw new ArgumentNullException(nameof(password));
+            }
+
+            var parts = phc.Split('$', StringSplitOptions.RemoveEmptyEntries);
+            if (parts.Length != 5 || parts[0] != Prefix)
+            {
+                return false;
+            }
+
+            // v=...
+            if (!parts[1].StartsWith("v=") || !int.TryParse(parts[1].AsSpan(2), out var ver))
+            {
+                return false;
+            }
+
+            // i=...
+            if (!parts[2].StartsWith("i=") || !int.TryParse(parts[2].AsSpan(2), out var iter))
+            {
+                return false;
+            }
+
+            byte[] salt, expected;
+            try
+            {
+                salt = Convert.FromBase64String(parts[3]);
+                expected = Convert.FromBase64String(parts[4]);
+            }
+            catch
+            {
+                return false;
+            }
+
+            var input = DeriveInput(password, _pepper);
+            using var pbkdf2 = new Rfc2898DeriveBytes(input, salt, iter, _hashAlgorithm);
+            var actual = pbkdf2.GetBytes(expected.Length);
+
+            var ok = CryptographicOperations.FixedTimeEquals(actual, expected);
+
+            if (ok)
+            {
+                // Check if we need to rehash (parameters changed or hash size changed)
+                if (ver < _version || iter < _iterations || expected.Length != HashSize)
+                {
+                    needsRehash = true;
+                }
+            }
+
+            return ok;
+        }
+
+        private static byte[] DeriveInput(string password, string pepper)
+        {
+            var pwdBytes = Encoding.UTF8.GetBytes(password);
+            var pepperBytes = Encoding.UTF8.GetBytes(pepper);
+            using var h = new HMACSHA256(pepperBytes);
+            return h.ComputeHash(pwdBytes);
+        }
+    }
+}
