Add BcryptAuthenticationException to allow clean handling of exceptio…

…ns on rehash impl.

licence.txt

@@ -1,7 +1,7 @@
 The MIT License (MIT)
 Copyright (c) 2006 Damien Miller [email protected] (jBCrypt)
 Copyright (c) 2013 Ryan D. Emerle (.Net port)
-Copyright (c) 2016 Chris McKee (.Net-core port / patches)
+Copyright (c) 2016/2017 Chris McKee (.Net-core port / patches)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files 
 (the �Software�), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, 

readme.md

@@ -200,14 +200,17 @@ A future release of Solar's bcrypt code should also support 'b'.
 
 https://github.com/BcryptNet/bcrypt.net/releases
 
-*v2.0.2 -*
+*v2.1.0 -*
 
 * Adds enhanced mode; enhanced hashing allows you to opt-in to ensuring optimal entropy on your users passwords by first making use of the fast SHA384 algorithm before BCrypt hashes the password.
-* VS2017 RTW changes
-* Cleaned up xml-doc for intellisense
-* Increased compatibility by allowing BCrypt revisions from other frameworks/languages to be validated and generated whilst maintaining compatibility.
 * Added Hash interrogation to allow a hash to be passed in and its component parts be returned.
  * Added timeouts to regex and set compiler flags for msbuild so < .net 4.5 (where timeouts were added to regex) we use old regex method.
+* Alter safe equals from ceq/and to xor/and/ceq moving the check outside of the loop to mitigate against branch prediction causing a timing leak
+* Add new method `PasswordNeedsReshash(string hash, int newMinimumWorkLoad)` as a helper method for developers to use when logging a user in to increase legacy workloads
+* Add `ValidateAndReplacePassword` method to allow inline password validation and replacement. Throws `BcryptAuthenticationException` in the event of authentication failure.
+* Cleaned up xml-doc for intellisense
+* Increased compatibility by allowing BCrypt revisions from other frameworks/languages to be validated and generated whilst maintaining compatibility.
+* VS2017 RTW changes
 
 *v2.0.1 -*
 

src/BCrypt.Net/BCrypt.cs

@@ -43,7 +43,7 @@ namespace BCrypt.Net
     ///  </para>
     ///  <code>string pw_hash = BCrypt.HashPassword(plain_password);</code>
     ///  <para>
-    ///         To hash a password using SHA384 pre-hashing for increased entropy call <see cref="BCrypt.EnhancedHashPassword(string)"/> 
+    ///         To hash a password using SHA384 pre-hashing for increased entropy call <see cref="BCrypt.EnhancedHashPassword(string)"/>
     ///         (which will generate a random salt and hash at default cost), like this:
     ///  </para>
     ///  <code>string pw_hash = Bcrypt.EnhancedHashPassword(plain_password);</code>
@@ -406,7 +406,7 @@ public sealed class BCrypt
         private uint[] _s;
 
         /// <summary>
-        /// Validate existing hash and password, 
+        /// Validate existing hash and password,
         /// </summary>
         /// <param name="currentKey">Current password / string</param>
         /// <param name="currentHash">Current hash to validate password against</param>
@@ -415,8 +415,12 @@ public sealed class BCrypt
         ///                          factor therefore increases as 2^workFactor. Default is 10</param>
         /// <param name="enhancedEntropy">Set to true,the string will undergo SHA384 hashing to make
         /// use of available entropy prior to bcrypt hashing</param>
-        /// <param name="forceWorkFactor">By default this method will not accept a work factor lower 
+        /// <param name="forceWorkFactor">By default this method will not accept a work factor lower
         /// than the one set in the current hash and will set the new workfactot to match.</param>
+        /// <exception cref="BcryptAuthenticationException">returned if the users hash and current pass doesn't validate</exception>
+        /// <exception cref="SaltParseException">returned if the salt is invalid in any way</exception>
+        /// <exception cref="ArgumentException">returned if thehash is invalid</exception>
+        /// <exception cref="ArgumentNullException">returned if the user hash is null</exception>
         /// <returns>New hash of new password</returns>
         public static string ValidateAndReplacePassword(string currentKey, string currentHash, string newKey, int workFactor = DefaultRounds, bool enhancedEntropy = false, bool forceWorkFactor = false)
         {
@@ -476,7 +480,7 @@ public static string ValidateAndReplacePassword(string currentKey, string curren
 
                 return HashPassword(newKey, GenerateSalt(workFactor), enhancedEntropy);
             }
-            throw new Exception("Current credentials could not be authenticated");
+            throw new BcryptAuthenticationException("Current credentials could not be authenticated");
         }
 
         /// <summary>
@@ -535,6 +539,7 @@ public static string ValidateAndReplacePassword(string currentKey, string curren
         /// <param name="salt">    the salt to hash with (best generated using BCrypt.gensalt).</param>
         /// <param name="enhancedEntropy">Set to true,the string will undergo SHA384 hashing to make use of available entropy prior to bcrypt hashing</param>
         /// <returns>The hashed password</returns>
+        /// <exception cref="ArgumentNullException">Thrown when the <paramref name="inputKey"/> is null.</exception>
         /// <exception cref="SaltParseException">Thrown when the <paramref name="salt"/> could not pe parsed.</exception>
         public static string HashPassword(string inputKey, string salt, bool enhancedEntropy)
         {
@@ -647,6 +652,7 @@ public static string GenerateSalt(int workFactor, char bcryptMinorRevision = Def
         /// <param name="hash">full bcrypt hash</param>
         /// <param name="newMinimumWorkLoad">target workload</param>
         /// <returns>true if new work factor is higher than the one in the hash</returns>
+        /// <exception cref="ArgumentException">throws if the current hash workload (logrounds) can not be parsed</exception>
         public static bool PasswordNeedsReshash(string hash, int newMinimumWorkLoad)
         {
             var hashInfo = InterrogateHash(hash);

src/BCrypt.Net/BcryptAuthenticationException.cs

@@ -0,0 +1,28 @@
+using System;
+
+namespace BCrypt.Net
+{
+    /// <summary>Exception for signalling hash validation errors. </summary>
+    public class BcryptAuthenticationException : Exception
+    {
+        /// <summary>Default constructor. </summary>
+        public BcryptAuthenticationException()
+        {
+        }
+
+        /// <summary>Initializes a new instance of <see cref="BcryptAuthenticationException" />.</summary>
+        /// <param name="message">The message.</param>
+        public BcryptAuthenticationException(string message)
+            : base(message)
+        {
+        }
+
+        /// <summary>Initializes a new instance of <see cref="BcryptAuthenticationException" />.</summary>
+        /// <param name="message">       The message.</param>
+        /// <param name="innerException">The inner exception.</param>
+        public BcryptAuthenticationException(string message, Exception innerException)
+            : base(message, innerException)
+        {
+        }
+    }
+}