Class Argon2idPasswordHasher

Namespace

Argon2id.PasswordHasher

Assembly

Argon2id.PasswordHasher.dll

An opinionated, secure-by-default Argon2id password hasher.

public sealed class Argon2idPasswordHasher

Inheritance

object

Argon2idPasswordHasher

Remarks

Construct once with the recommended defaults and reuse the instance — it is stateless and thread-safe. Each call to HashPassword(string) generates a fresh cryptographically random salt and returns a self-describing PHC string that already contains every parameter needed to verify it later.

Overloads accepting System.ReadOnlySpan<T> of char or byte let callers avoid materializing the password as a string; the hasher zeroes every password-derived buffer it owns.

var hasher = new Argon2idPasswordHasher();
string stored = hasher.HashPassword("correct horse battery staple");
bool ok = hasher.VerifyPassword("correct horse battery staple", stored); // true

Constructors

Argon2idPasswordHasher()

Creates a hasher using the library's recommended defaults (Recommended) and no pepper.

public Argon2idPasswordHasher()

Argon2idPasswordHasher(Argon2idOptions)

Creates a hasher with custom work-factor parameters and no pepper.

public Argon2idPasswordHasher(Argon2idOptions options)

Parameters

options Argon2idOptions

The Argon2id parameters to use for new hashes.

Exceptions

ArgumentNullException

options is null.

ArgumentOutOfRangeException

Any parameter is outside the safe range.

Argon2idPasswordHasher(Argon2idOptions, PepperRing?)

Creates a hasher with custom work-factor parameters and an optional pepper ring.

public Argon2idPasswordHasher(Argon2idOptions options, PepperRing? pepper)

Parameters

options Argon2idOptions

The Argon2id parameters to use for new hashes.

pepper PepperRing

An optional PepperRing. When supplied, new hashes are produced with the ring's active pepper and tagged with its id; verification selects the pepper recorded in each hash. When null, hashing and verification use no pepper.

Exceptions

ArgumentNullException

options is null.

ArgumentOutOfRangeException

Any parameter is outside the safe range.

Fields

PhcPrefix

The PHC algorithm prefix every Argon2id hash begins with.

public const string PhcPrefix = "$argon2id$"

Field Value

string

Remarks

Exposed so callers writing their own routing logic over a heterogeneous password column don't have to hard-code the literal. Combine with IsArgon2idHash(string?) for a one-line sniff test.

Properties

Options

The parameters this hasher uses when producing new hashes.

public Argon2idOptions Options { get; }

Property Value

Argon2idOptions

Methods

HashPassword(ReadOnlySpan<byte>)

Hashes a password supplied as raw bytes (for example a pre-encoded credential). The caller retains ownership of password and is responsible for clearing it; the hasher only zeroes its own internal copy.

public string HashPassword(ReadOnlySpan<byte> password)

Parameters

password ReadOnlySpan<byte>

The plaintext password bytes. Must not be empty.

Returns

string

A PHC string suitable for storage.

Exceptions

ArgumentException

password is empty.

HashPassword(ReadOnlySpan<char>)

Hashes a password supplied as a span of characters, avoiding an intermediate string.

public string HashPassword(ReadOnlySpan<char> password)

Parameters

password ReadOnlySpan<char>

The plaintext password. Must not be empty.

Returns

string

A PHC string suitable for storage.

Exceptions

ArgumentException

password is empty.

HashPassword(string)

Hashes a password with a fresh random salt and returns a PHC-formatted string suitable for storage (for example, in an AspNetUsers.PasswordHash column).

public string HashPassword(string password)

Parameters

password string

The plaintext password. Must not be null or empty.

Returns

string

A PHC string, e.g. $argon2id$v=19$m=65536,t=3,p=1$<salt>$<hash>.

Exceptions

ArgumentException

password is null or empty.

IsArgon2idHash(string?)

Quick, allocation-free sniff test: returns true when the stored value looks like an Argon2id PHC string (begins with \(argon2id\)).

public static bool IsArgon2idHash(string? encodedHash)

Parameters

encodedHash string

The candidate stored value.

Returns

bool

true if encodedHash begins with the Argon2id PHC prefix; false for null, empty, or any other prefix.

Remarks

This does NOT validate the parameters, the salt, or the tag — only that the algorithm prefix matches. Use it for routing decisions (Argon2id vs legacy hasher) before calling VerifyPassword(string, string); verify itself will reject malformed structure and return false.

NeedsRehash(string)

Indicates whether a stored hash should be re-hashed on the next successful login, either because it was produced with weaker parameters than this hasher's current settings, or because it does not use the active pepper.

public bool NeedsRehash(string encodedHash)

Parameters

encodedHash string

The stored PHC string.

Returns

bool

true if the hash is unparseable, any stored parameter is below the current configuration, or (when a pepper ring is configured) the hash's pepper differs from the active pepper; otherwise false.

Remarks

Prefer Verify(string, string) when you also need to verify the password — it parses the PHC string only once.

Verify(ReadOnlySpan<byte>, string)

Verifies a password and, in one call, reports whether the stored hash should be replaced with a fresh one. Parses the PHC string once; preferred over calling VerifyPassword(string, string) and NeedsRehash(string) separately.

public VerifyResult Verify(ReadOnlySpan<byte> password, string encodedHash)

Parameters

password ReadOnlySpan<byte>

The plaintext password to check.

encodedHash string

The stored PHC string.

Returns

VerifyResult

A VerifyResult whose Success indicates match and whose NeedsRehash is true only when the password matched and the stored parameters / pepper are weaker than the hasher's current configuration.

Verify(ReadOnlySpan<char>, string)

Verifies a password and, in one call, reports whether the stored hash should be replaced with a fresh one. Parses the PHC string once; preferred over calling VerifyPassword(string, string) and NeedsRehash(string) separately.

public VerifyResult Verify(ReadOnlySpan<char> password, string encodedHash)

Parameters

password ReadOnlySpan<char>

The plaintext password to check.

encodedHash string

The stored PHC string.

Returns

VerifyResult

A VerifyResult whose Success indicates match and whose NeedsRehash is true only when the password matched and the stored parameters / pepper are weaker than the hasher's current configuration.

Verify(string, string)

Verifies a password and, in one call, reports whether the stored hash should be replaced with a fresh one. Parses the PHC string once; preferred over calling VerifyPassword(string, string) and NeedsRehash(string) separately.

public VerifyResult Verify(string password, string encodedHash)

Parameters

password string

The plaintext password to check.

encodedHash string

The stored PHC string.

Returns

VerifyResult

A VerifyResult whose Success indicates match and whose NeedsRehash is true only when the password matched and the stored parameters / pepper are weaker than the hasher's current configuration.

VerifyPassword(ReadOnlySpan<byte>, string)

Verifies a password supplied as raw bytes against a stored PHC hash. The caller retains ownership of password; the hasher zeroes only its own copy.

public bool VerifyPassword(ReadOnlySpan<byte> password, string encodedHash)

Parameters

password ReadOnlySpan<byte>

The plaintext password bytes to check.

encodedHash string

The stored PHC string.

Returns

bool

true if the password matches; otherwise false.

VerifyPassword(ReadOnlySpan<char>, string)

Verifies a password supplied as a span of characters against a stored PHC hash.

public bool VerifyPassword(ReadOnlySpan<char> password, string encodedHash)

Parameters

password ReadOnlySpan<char>

The plaintext password to check.

encodedHash string

The stored PHC string.

Returns

bool

true if the password matches; otherwise false.

VerifyPassword(string, string)

Verifies a password against a previously stored PHC hash in constant time.

public bool VerifyPassword(string password, string encodedHash)

Parameters

password string

The plaintext password to check.

encodedHash string

The stored PHC string produced by HashPassword(string).

Returns

bool

true if the password matches; otherwise false. Malformed, unsupported, or empty stored values — and hashes whose pepper is not available — return false rather than throwing.