Custom PasswordHasher in ASP.NET Core Identity

December 16, 2019 3 min read BEN ABT

In the ASP.NET Core Identity environment, the PasswordHasher is responsible for securely storing the password and performing password entry checks.

In this respect, the PasswordHasher is also responsible for choosing the correct hash method, whereby several hash methods can be used.

First Byte

In the world of ASP.NET Core Identity, the first byte of the password has a special meaning: it indicates how the password was hashed.

0x00 - Version 2: PBKDF2 with HMAC-SHA1, 128-bit salt, 256-bit subkey, 1000 iterations.
0x01 - Version 3: PBKDF2 with HMAC-SHA256, 128-bit salt, 256-bit subkey, 10000 iterations.

See more details here: PasswordHasher.cs Source

The peculiarity of the first byte can now be used to store own implementations for hashing. This is especially useful for migrating passwords.
However, care must be taken that no reserved byte representations are used for own implementations.

Password Migrations

ASP.NET Core Identity has a built-in mechanism for migrating (e.g. re-hashing) passwords.

The idea is that users enter their password and the verification process determines if the password hash system is out of date. If it is outdated, the password is automatically re-hashed and saved with the currently defined mechanism.

As a result, users do not notice the hash system update and do not need to be prompted for a reset.

At this moment the system is informed that the password has been successfully verified, but that a re-hash is necessary. The identity system takes care of the rest completely automatically.

Rehash mechanism

The re-hash mechanism works as follows:

The password check determines whether the password is “valid”, “invalid” or “valid, with obsolete mechanism”.
The latter is represented by the enum SuccessRehashNeeded.

The result arrives at the “UserManager” of the identity implementation, which automatically updates the password in the event of a necessary rehash.

C#
 1public class PortalUserManager : UserManager<PortalUser>
 2{
  private readonly IUserPasswordStore<PortalUser> _passwordStore;
 4
  public PortalUserManager(
      IUserStore<PortalUser> store,
      IOptions<IdentityOptions> optionsAccessor,
      IPasswordHasher<PortalUser> passwordHasher,
      IEnumerable<IUserValidator<PortalUser>> userValidators,
      IEnumerable<IPasswordValidator<PortalUser>> passwordValidators,
      ILookupNormalizer keyNormalizer, IdentityErrorDescriber errors,
      IServiceProvider services, ILogger<UserManager<PortalUser>> logger) : base(store, optionsAccessor, passwordHasher, userValidators, passwordValidators, keyNormalizer, errors, services, logger)
  {
      _passwordStore = Store as IUserPasswordStore<PortalUser>;
  }
16
  public override async Task<bool> CheckPasswordAsync(PortalUser user, string password)
  {
      if (user is null) { return false; }
20
      // Verify users password
      PasswordVerificationResult result = await VerifyPasswordAsync(_passwordStore, user, password);
23
      // if reshash is required, automatically rehash the password
      if (result == PasswordVerificationResult.SuccessRehashNeeded)
      {
          await UpdatePasswordHash(user, password, validatePassword: false);
          await UpdateUserAsync(user);
      }
30
      bool success = result != PasswordVerificationResult.Failed;
      if (!success)
      {
              Logger.LogWarning(0, $"Invalid password for user {user.Id}.");
      }
      return success;
  }
38}

Sample

C#
 1public class PortalUserPasswordHasher : PasswordHasher<PortalUser>, IPasswordHasher<PortalUser>
 2{
  public PortalUserPasswordHasher(
      IOptions<PasswordHasherOptions> optionsAccessor = null) 
      : base(optionsAccessor) { }
 6
  /// </summary>
  public override PasswordVerificationResult VerifyHashedPassword(
      PortalUser user, string hashedPassword, string providedPassword)
  {
      // pass as bytes
      byte[] decodedHashedPassword = Convert.FromBase64String(hashedPassword);
13
      // we check the first byte
      //    this byte indicates which hash algorithm is used
      switch (decodedHashedPassword[0])
      {
          // if it's old (old PHP platform), request rehash on success
          case PortalUserHashHelper.PhpBBFormatMarker:
              if (LegacyPhpBBPasswordProvider.VerifyHashedPassword(
                                  decodedHashedPassword, providedPassword))
              {
                  return PasswordVerificationResult.SuccessRehashNeeded;
              }
              else
              {
                  return PasswordVerificationResult.Failed;
              }
29
          // otherwise we use the default ASP.NET Core Identity behavior
          default:
              return base.VerifyHashedPassword(user, hashedPassword, providedPassword);
      }
  }
35}