Table of Contents

Class MigratingPasswordHasher<TUser>

Namespace
Argon2id.PasswordHasher.AspNetCore
Assembly
Argon2id.PasswordHasher.AspNetCore.dll

An IPasswordHasher<TUser> that routes verification to a legacy hasher (typically PasswordHasher<TUser>'s default PBKDF2 implementation) when the stored hash isn't an Argon2id PHC string, then transparently rehashes successful logins to Argon2id on the way out.

public sealed class MigratingPasswordHasher<TUser> : IPasswordHasher<TUser> where TUser : class

Type Parameters

TUser

The Identity user type.

Inheritance
object
MigratingPasswordHasher<TUser>
Implements

Remarks

Use this when you're migrating an existing user store — the stored hashes are a mix of Argon2id (recent registrations) and whatever you used before (PBKDF2, bcrypt-via-an-adapter, etc.). New hashes always come out as Argon2id; old hashes verify against the legacy hasher and are flagged as SuccessRehashNeeded so ASP.NET Core Identity rewrites them with HashPassword(TUser, string).

Routing is purely format-based and uses no allocations: any stored value starting with $argon2id$ goes to the Argon2id path. Everything else — including null, empty, and garbage strings — is handed to the legacy hasher, which is expected to fail safely. 

// Register the migrating hasher with the default PBKDF2 Identity
// hasher as the legacy fallback:
builder.Services
    .AddIdentityCore<IdentityUser>()
    .AddArgon2idPasswordHasherWithMigration<IdentityUser>();

Constructors

MigratingPasswordHasher(Argon2idPasswordHasher<TUser>, IPasswordHasher<TUser>)

Creates the migrating hasher.

public MigratingPasswordHasher(Argon2idPasswordHasher<TUser> argon2id, IPasswordHasher<TUser> legacy)

Parameters

argon2id Argon2idPasswordHasher<TUser>

The Argon2id hasher used for new hashes and for verifying any stored PHC strings that begin with \(argon2id\).

legacy IPasswordHasher<TUser>

The hasher used to verify any stored value that is not an Argon2id PHC string. When this hasher reports Success or SuccessRehashNeeded, the migrating hasher returns SuccessRehashNeeded so Identity stores a fresh Argon2id hash.

Exceptions

ArgumentNullException

argon2id or legacy is null.

Methods

HashPassword(TUser, string)

Returns a hashed representation of the supplied password for the specified user.

public string HashPassword(TUser user, string password)

Parameters

user TUser

The user whose password is to be hashed.

password string

The password to hash.

Returns

string

A hashed representation of the supplied password for the specified user.

VerifyHashedPassword(TUser, string, string)

Returns a PasswordVerificationResult indicating the result of a password hash comparison.

public PasswordVerificationResult VerifyHashedPassword(TUser user, string hashedPassword, string providedPassword)

Parameters

user TUser

The user whose password should be verified.

hashedPassword string

The hash value for a user's stored password.

providedPassword string

The password supplied for comparison.

Returns

PasswordVerificationResult

A PasswordVerificationResult indicating the result of a password hash comparison.

Remarks

Implementations of this method should be time consistent.

Edit this page