Added support for SuccessRehashNeeded. Updated default work factor to 11

scottbrady91 · scottbrady91 · commit ba25eb168973 · 2021-03-07T16:16:38.000Z
diff --git a/README.md b/README.md
@@ -1,26 +1,27 @@
-# BCrypt Password Hasher for ASP.NET Core Identity (ASP.NET Identity 3)
+# BCrypt Password Hasher for ASP.NET Core Identity
 
 [![NuGet](https://img.shields.io/nuget/v/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher.svg)](https://www.nuget.org/packages/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher/)
 
-An implementation of IPasswordHasher<TUser> using [BCrypt.NET - next](https://github.com/BcryptNet/bcrypt.net).
+An implementation of `IPasswordHasher<TUser>` using [BCrypt.NET - next](https://github.com/BcryptNet/bcrypt.net).
 
 ## Installation
 
-```
+```csharp
 services.AddIdentity<TUser, TRole>();
 services.AddScoped<IPasswordHasher<TUser>, BCryptPasswordHasher<TUser>>();
 ```
 
 ### Options
 
- - **WorkFactor**: int
- - **EnhancedEntropy**: bool
+- **WorkFactor**: int
+- **EnhancedEntropy**: bool
 
 Register with:
-```
+
+```csharp
 services.Configure<BCryptPasswordHasherOptions>(options => {
-	options.WorkFactor = 10;
-	options.EnhancedEntropy = false;
+    options.WorkFactor = 11;
+    options.EnhancedEntropy = false;
 });
 ```
 
diff --git a/src/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher/BCryptPasswordHasher.cs b/src/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher/BCryptPasswordHasher.cs
@@ -15,18 +15,23 @@ public BCryptPasswordHasher(IOptions<BCryptPasswordHasherOptions> optionsAccesso
 
         public virtual string HashPassword(TUser user, string password)
         {
-            if (password == null) throw new ArgumentNullException(nameof(password));
+            if (string.IsNullOrWhiteSpace(password)) throw new ArgumentNullException(nameof(password));
 
             return BCrypt.Net.BCrypt.HashPassword(password, options.WorkFactor, options.EnhancedEntropy);
         }
 
         public virtual PasswordVerificationResult VerifyHashedPassword(TUser user, string hashedPassword, string providedPassword)
         {
-            if (hashedPassword == null) throw new ArgumentNullException(nameof(hashedPassword));
-            if (providedPassword == null) throw new ArgumentNullException(nameof(providedPassword));
+            if (string.IsNullOrWhiteSpace(hashedPassword)) throw new ArgumentNullException(nameof(hashedPassword));
+            if (string.IsNullOrWhiteSpace(providedPassword)) throw new ArgumentNullException(nameof(providedPassword));
 
             var isValid = BCrypt.Net.BCrypt.Verify(providedPassword, hashedPassword, options.EnhancedEntropy);
 
+            if (isValid && BCrypt.Net.BCrypt.PasswordNeedsRehash(hashedPassword, options.WorkFactor))
+            {
+                return PasswordVerificationResult.SuccessRehashNeeded;
+            }
+
             return isValid ? PasswordVerificationResult.Success : PasswordVerificationResult.Failed;
         }
     }
diff --git a/src/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher/BCryptPasswordHasherOptions.cs b/src/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher/BCryptPasswordHasherOptions.cs
@@ -2,7 +2,14 @@
 {
     public class BCryptPasswordHasherOptions
     {
-        public int WorkFactor { get; set; } = 10;
+        /// <summary>
+        /// The log2 of the number of rounds of hashing to apply. Defaults to 11
+        /// </summary>
+        public int WorkFactor { get; set; } = 11;
+        
+        /// <summary>
+        /// Enables the use of SHA384 hashing prior to bcrypt hashing. Defaults to false
+        /// </summary>
         public bool EnhancedEntropy { get; set; } = false;
     }
 }
diff --git a/src/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher.csproj b/src/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher.csproj
@@ -4,15 +4,17 @@
     <TargetFramework>netstandard2.0</TargetFramework>
     <AssemblyName>ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher</AssemblyName>
     <PackageId>ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher</PackageId>
-    <PackageVersion>1.2.0</PackageVersion>
     <Authors>Scott Brady</Authors>
     <Description>ASP.NET Core Identity IPasswordHasher implementation using BCrypt.Net - next</Description>
     <Copyright>Copyright (c) 2017 Scott Brady</Copyright>
     <PackageTags>aspnetcore;identity;bcrypt;password;hashing;hash;security;blowfish</PackageTags>
     <PackageIconUrl>https://www.scottbrady91.com/img/logos/scottbrady91.png</PackageIconUrl>
     <PackageProjectUrl>https://github.com/scottbrady91/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher</PackageProjectUrl>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
-    <PackageReleaseNotes>Updated bcrypt and ASP.NET Identity dependencies. Made methods virtual.</PackageReleaseNotes>
+    <IncludeSymbols>true</IncludeSymbols>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <Version>1.2.0</Version>
+    <PackageReleaseNotes>Updated default work factor to 11. Added support for SuccessRehashNeeded. Updated bcrypt and ASP.NET Identity dependencies.</PackageReleaseNotes>
   </PropertyGroup>
 
   <ItemGroup>
diff --git a/test/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher.Tests/BCryptPasswordHasherTests.cs b/test/ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher.Tests/BCryptPasswordHasherTests.cs
@@ -8,13 +8,29 @@ namespace ScottBrady91.AspNetCore.Identity.BCryptPasswordHasher.Tests
 {
     public class BCryptPasswordHasherTests
     {
+        private BCryptPasswordHasherOptions options = new BCryptPasswordHasherOptions();
+        
+        private BCryptPasswordHasher<string> CreateSut() =>
+            new BCryptPasswordHasher<string>(
+                options != null ? new OptionsWrapper<BCryptPasswordHasherOptions>(options) : null);
+
+        [Theory]
+        [InlineData(null)]
+        [InlineData("")]
+        [InlineData(" ")]
+        public void HashPassword_WhenPasswordIsNullOrWhitespace_ExpectArgumentNullException(string password)
+        {
+            var sut = CreateSut();
+            Assert.Throws<ArgumentNullException>(() => sut.HashPassword(null, password));
+        }
+        
         [Fact]
         public void HashPassword_WithDefaultSettings_ExpectVerifiableHash()
         {
             var password = Guid.NewGuid().ToString();
 
-            var hasher = new BCryptPasswordHasher<string>();
-            var hashedPassword = hasher.HashPassword("", password);
+            var sut = CreateSut();
+            var hashedPassword = sut.HashPassword("", password);
 
             BCrypt.Net.BCrypt.Verify(password, hashedPassword).Should().BeTrue();
         }
@@ -24,9 +40,9 @@ public void HashPassword_WhenCalledMultipleTimesWithSamePlaintext_ExpectDifferen
         {
             var password = Guid.NewGuid().ToString();
 
-            var hasher = new BCryptPasswordHasher<string>();
-            var hashedPassword1 = hasher.HashPassword("", password);
-            var hashedPassword2 = hasher.HashPassword("", password);
+            var sut = CreateSut();
+            var hashedPassword1 = sut.HashPassword("", password);
+            var hashedPassword2 = sut.HashPassword("", password);
 
             hashedPassword1.Should().NotBe(hashedPassword2);
         }
@@ -37,10 +53,10 @@ public void HashPassword_WithCustomWorkFactor_ExpectVerifiableHash()
             var random = new Random();
             var password = Guid.NewGuid().ToString();
 
-            var hasher = new BCryptPasswordHasher<string>(
-                new OptionsWrapper<BCryptPasswordHasherOptions>(
-                    new BCryptPasswordHasherOptions {WorkFactor = random.Next(8, 18)}));
-            var hashedPassword = hasher.HashPassword("", password);
+            options.WorkFactor = options.WorkFactor - 1;
+            var sut = CreateSut();
+
+            var hashedPassword = sut.HashPassword("", password);
 
             BCrypt.Net.BCrypt.Verify(password, hashedPassword).Should().BeTrue();
         }
@@ -50,11 +66,10 @@ public void HashPassword_WithEnhancedEntropy_ExpectHashNotToVerify()
         {
             var password = Guid.NewGuid().ToString();
 
-            var hasher = new BCryptPasswordHasher<string>(
-                new OptionsWrapper<BCryptPasswordHasherOptions>(
-                    new BCryptPasswordHasherOptions {EnhancedEntropy = true}));
+            options.EnhancedEntropy = true;
+            var sut = CreateSut();
             
-            var hashedPassword = hasher.HashPassword("", password);
+            var hashedPassword = sut.HashPassword("", password);
 
             BCrypt.Net.BCrypt.Verify(password, hashedPassword, true).Should().BeTrue();
             BCrypt.Net.BCrypt.EnhancedVerify(password, hashedPassword).Should().BeTrue();
@@ -65,49 +80,68 @@ public void HashPassword_WithPasswordCreatedWithoutEnhancedEntropyButVerifiedWit
         {
             var password = Guid.NewGuid().ToString();
 
-            var hasher = new BCryptPasswordHasher<string>(
-                new OptionsWrapper<BCryptPasswordHasherOptions>(
-                    new BCryptPasswordHasherOptions { EnhancedEntropy = false }));
+            options.EnhancedEntropy = false;
+            var sut = CreateSut();
 
-            var hashedPassword = hasher.HashPassword("", password);
+            var hashedPassword = sut.HashPassword("", password);
 
             BCrypt.Net.BCrypt.Verify(password, hashedPassword, true).Should().BeFalse();
             BCrypt.Net.BCrypt.EnhancedVerify(password, hashedPassword).Should().BeFalse();
         }
+        
+        [Theory]
+        [InlineData(null)]
+        [InlineData("")]
+        [InlineData(" ")]
+        public void VerifyHashedPassword_WhenHashedPasswordIsNullOrWhitespace_ExpectArgumentNullException(string hashedPassword)
+        {
+            var sut = CreateSut();
+            Assert.Throws<ArgumentNullException>(() => sut.VerifyHashedPassword(null, hashedPassword, Guid.NewGuid().ToString()));
+        }
+
+        [Theory]
+        [InlineData(null)]
+        [InlineData("")]
+        [InlineData(" ")]
+        public void VerifyHashedPassword_WhenPasswordIsNullOrWhitespace_ExpectArgumentNullException(string password)
+        {
+            var sut = CreateSut();
+            Assert.Throws<ArgumentNullException>(() => sut.VerifyHashedPassword(null, Guid.NewGuid().ToString(), password));
+        }
 
         [Fact]
         public void VerifyHashedPassword_WithDefaultSettings_ExpectSuccess()
         {
             var password = Guid.NewGuid().ToString();
             var hashedPassword = BCrypt.Net.BCrypt.HashPassword(password);
 
-            var hasher = new BCryptPasswordHasher<string>();
+            var sut = CreateSut();
 
-            hasher.VerifyHashedPassword("", hashedPassword, password).Should().Be(PasswordVerificationResult.Success);
+            sut.VerifyHashedPassword("", hashedPassword, password).Should().Be(PasswordVerificationResult.Success);
         }
 
         [Fact]
         public void VerifyHashedPassword_WithEnhancedEntropy_ExpectSuccess()
         {
-            var options = new BCryptPasswordHasherOptions {EnhancedEntropy = true};
             var password = Guid.NewGuid().ToString();
             var hashedPassword = BCrypt.Net.BCrypt.HashPassword(password, options.WorkFactor, true);
 
-            var hasher = new BCryptPasswordHasher<string>(new OptionsWrapper<BCryptPasswordHasherOptions>(options));
+            options.EnhancedEntropy = true;
+            var sut = CreateSut();
 
-            hasher.VerifyHashedPassword("", hashedPassword, password).Should().Be(PasswordVerificationResult.Success);
+            sut.VerifyHashedPassword("", hashedPassword, password).Should().Be(PasswordVerificationResult.Success);
         }
 
         [Fact]
         public void VerifyHashedPassword_WhenPasswordCreatedWithEnhancedEntropyButVerifiedWithout_ExpectFailure()
         {
-            var options = new BCryptPasswordHasherOptions { EnhancedEntropy = true };
             var password = Guid.NewGuid().ToString();
-            var hashedPassword = BCrypt.Net.BCrypt.HashPassword(password, options.WorkFactor);
+            var hashedPassword = BCrypt.Net.BCrypt.HashPassword(password, options.WorkFactor, false);
 
-            var hasher = new BCryptPasswordHasher<string>(new OptionsWrapper<BCryptPasswordHasherOptions>(options));
+            options.EnhancedEntropy = true;
+            var sut = CreateSut();
 
-            hasher.VerifyHashedPassword("", hashedPassword, password).Should().Be(PasswordVerificationResult.Failed);
+            sut.VerifyHashedPassword("", hashedPassword, password).Should().Be(PasswordVerificationResult.Failed);
         }
         
         [Fact]
@@ -116,20 +150,32 @@ public void VerifyHashedPassword_WhenSuppliedPasswordDoesNotMatch_ExpectFailure(
             var password = Guid.NewGuid().ToString();
             var hashedPassword = BCrypt.Net.BCrypt.HashPassword(Guid.NewGuid().ToString());
 
-            var hasher = new BCryptPasswordHasher<string>();
+            var sut = CreateSut();
 
-            hasher.VerifyHashedPassword("", hashedPassword, password).Should().Be(PasswordVerificationResult.Failed);
+            sut.VerifyHashedPassword("", hashedPassword, password).Should().Be(PasswordVerificationResult.Failed);
         }
 
         [Fact]
-        public void VerifyHashedPassword_WhenCorrectV10Password_ExpectSuccess()
+        public void VerifyHashedPassword_WhenCorrectV10Password_ExpectSuccessRehashNeeded()
         {
             const string password = "6@JM}T-3DeZo&2i=U73A^nEY7tXe_3UC%RR";
             const string hashedPassword = "$2a$10$SpIhzEv3ATLa0CmTz4L7ouAn/w5NyedFic5X3fKaI9eu0xhW97OUC";
 
-            var hasher = new BCryptPasswordHasher<string>();
+            var sut = CreateSut();
+
+            sut.VerifyHashedPassword("", hashedPassword, password).Should().Be(PasswordVerificationResult.SuccessRehashNeeded);
+        }
+
+        [Fact]
+        public void VerifyHashedPassword_WhenPasswordHashedWithLowerEntropy_ExpectSuccessRehashNeeded()
+        {
+            var password = Guid.NewGuid().ToString();
+            var hashedPassword = BCrypt.Net.BCrypt.HashPassword(password, 10);
+
+            options.WorkFactor = 11;
+            var sut = CreateSut();
 
-            hasher.VerifyHashedPassword("", hashedPassword, password).Should().Be(PasswordVerificationResult.Success);
+            sut.VerifyHashedPassword("", hashedPassword, password).Should().Be(PasswordVerificationResult.SuccessRehashNeeded);
         }
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -15,18 +15,23 @@ public BCryptPasswordHasher(IOptions<BCryptPasswordHasherOptions> optionsAccesso`
`15`	`15`
`16`	`16`	`public virtual string HashPassword(TUser user, string password)`
`17`	`17`	`{`
`18`		`- if (password == null) throw new ArgumentNullException(nameof(password));`
	`18`	`+ if (string.IsNullOrWhiteSpace(password)) throw new ArgumentNullException(nameof(password));`
`19`	`19`
`20`	`20`	`return BCrypt.Net.BCrypt.HashPassword(password, options.WorkFactor, options.EnhancedEntropy);`
`21`	`21`	`}`
`22`	`22`
`23`	`23`	`public virtual PasswordVerificationResult VerifyHashedPassword(TUser user, string hashedPassword, string providedPassword)`
`24`	`24`	`{`
`25`		`- if (hashedPassword == null) throw new ArgumentNullException(nameof(hashedPassword));`
`26`		`- if (providedPassword == null) throw new ArgumentNullException(nameof(providedPassword));`
	`25`	`+ if (string.IsNullOrWhiteSpace(hashedPassword)) throw new ArgumentNullException(nameof(hashedPassword));`
	`26`	`+ if (string.IsNullOrWhiteSpace(providedPassword)) throw new ArgumentNullException(nameof(providedPassword));`
`27`	`27`
`28`	`28`	`var isValid = BCrypt.Net.BCrypt.Verify(providedPassword, hashedPassword, options.EnhancedEntropy);`
`29`	`29`
	`30`	`+ if (isValid && BCrypt.Net.BCrypt.PasswordNeedsRehash(hashedPassword, options.WorkFactor))`
	`31`	`+ {`
	`32`	`+ return PasswordVerificationResult.SuccessRehashNeeded;`
	`33`	`+ }`
	`34`	`+`
`30`	`35`	`return isValid ? PasswordVerificationResult.Success : PasswordVerificationResult.Failed;`
`31`	`36`	`}`
`32`	`37`	`}`
Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,14 @@`
`2`	`2`	`{`
`3`	`3`	`public class BCryptPasswordHasherOptions`
`4`	`4`	`{`
`5`		`- public int WorkFactor { get; set; } = 10;`
	`5`	`+ /// <summary>`
	`6`	`+ /// The log2 of the number of rounds of hashing to apply. Defaults to 11`
	`7`	`+ /// </summary>`
	`8`	`+ public int WorkFactor { get; set; } = 11;`
	`9`	`+`
	`10`	`+ /// <summary>`
	`11`	`+ /// Enables the use of SHA384 hashing prior to bcrypt hashing. Defaults to false`
	`12`	`+ /// </summary>`
`6`	`13`	`public bool EnhancedEntropy { get; set; } = false;`
`7`	`14`	`}`
`8`	`15`	`}`