Bcrypt Class

Namespace: Meziantou.Framework.Hashing
Assembly: Meziantou.Framework.Hashing.dll
Package: Meziantou.Framework.Hashing 1.0.1
Source: Bcrypt.cs
Available in package assets: net10.0net11.0

Provides helper methods to hash and verify passwords using BCrypt.

public static class Bcrypt

Remarks

BCrypt hashes are encoded as modular crypt strings such as $2b$12$... where the revision is one of 2, 2a, 2b, 2x, or 2y, and the work factor (cost) is in the range 4 to 31.

Per the BCrypt specification, input is processed as UTF-8 and only the first 72 bytes are used.

Methods

Name	Description
GenerateSalt(int, BcryptVersion)	Generates a BCrypt salt for the specified work factor and revision.
HashPassword(ReadOnlySpan<char>, int, BcryptVersion)	Hashes a password using BCrypt and a generated salt.
HashPassword(ReadOnlySpan<char>, ReadOnlySpan<char>)	Hashes a password using a specific BCrypt salt.
HashPassword(string, int, BcryptVersion)	Hashes a password using BCrypt and a generated salt.
HashPassword(string, string)	Hashes a password using a specific BCrypt salt.
NeedsRehash(ReadOnlySpan<char>, int, BcryptVersion)	Determines whether an existing hash should be rehashed using new settings.
NeedsRehash(string, int, BcryptVersion)	Determines whether an existing hash should be rehashed using new settings.
ParseHash(ReadOnlySpan<char>)	Parses a BCrypt hash and returns its revision and work factor.
ParseHash(string)	Parses a BCrypt hash and returns its revision and work factor.
TryParseHash(ReadOnlySpan<char>, BcryptHashInfo)	Attempts to parse a BCrypt hash and extract its revision and work factor.
TryParseHash(string?, BcryptHashInfo)	Attempts to parse a BCrypt hash and extract its revision and work factor.
Verify(ReadOnlySpan<char>, ReadOnlySpan<char>)	Verifies that a password matches a BCrypt hash.
Verify(string, string)	Verifies that a password matches a BCrypt hash.

GenerateSalt(int, BcryptVersion)

Bcrypt.cs

Generates a BCrypt salt for the specified work factor and revision.

public static string GenerateSalt(int workFactor = 11, BcryptVersion version = BcryptVersion.Revision2B)

Parameters

workFactor int: The BCrypt work factor. Must be between Bcrypt.MinWorkFactor and Bcrypt.MaxWorkFactor.
version BcryptVersion: The BCrypt revision to generate.

Returns

string A BCrypt salt string.

Exceptions

ArgumentOutOfRangeException: workFactor is outside the supported range.
NotSupportedException: version is BcryptVersion.Revision2 or BcryptVersion.Revision2X, neither of which can be generated.

HashPassword overloads

HashPassword(ReadOnlySpan<char>, int, BcryptVersion)

Bcrypt.cs

Hashes a password using BCrypt and a generated salt.

public static string HashPassword(ReadOnlySpan<char> password, int workFactor = 11, BcryptVersion version = BcryptVersion.Revision2B)

Parameters

password ReadOnlySpan<char>: The password to hash.
workFactor int: The BCrypt work factor. Must be between Bcrypt.MinWorkFactor and Bcrypt.MaxWorkFactor.
version BcryptVersion: The BCrypt revision to generate.

Returns

string The BCrypt hash string.

Exceptions

ArgumentException: password cannot be encoded as UTF-8 because it contains an unpaired surrogate.

HashPassword(ReadOnlySpan<char>, ReadOnlySpan<char>)

Bcrypt.cs

Hashes a password using a specific BCrypt salt.

public static string HashPassword(ReadOnlySpan<char> password, ReadOnlySpan<char> salt)

Parameters

password ReadOnlySpan<char>: The password to hash.
salt ReadOnlySpan<char>: The BCrypt salt string.

Returns

string The BCrypt hash string.

Exceptions

ArgumentException: password cannot be encoded as UTF-8 because it contains an unpaired surrogate.
FormatException: salt is not a valid BCrypt salt: bad revision, a work factor outside Bcrypt.MinWorkFactor..Bcrypt.MaxWorkFactor, or a malformed payload.

HashPassword(string, int, BcryptVersion)

Bcrypt.cs

Hashes a password using BCrypt and a generated salt.

public static string HashPassword(string password, int workFactor = 11, BcryptVersion version = BcryptVersion.Revision2B)

Parameters

password string: The password to hash.
workFactor int: The BCrypt work factor. Must be between Bcrypt.MinWorkFactor and Bcrypt.MaxWorkFactor.
version BcryptVersion: The BCrypt revision to generate.

Returns

string The BCrypt hash string.

Exceptions

ArgumentException: password cannot be encoded as UTF-8 because it contains an unpaired surrogate.

HashPassword(string, string)

Bcrypt.cs

Hashes a password using a specific BCrypt salt.

public static string HashPassword(string password, string salt)

Parameters

password string: The password to hash.
salt string: The BCrypt salt string.

Returns

string The BCrypt hash string.

Exceptions

ArgumentException: password cannot be encoded as UTF-8 because it contains an unpaired surrogate.
FormatException: salt is not a valid BCrypt salt: bad revision, a work factor outside Bcrypt.MinWorkFactor..Bcrypt.MaxWorkFactor, or a malformed payload.

NeedsRehash overloads

NeedsRehash(ReadOnlySpan<char>, int, BcryptVersion)

Bcrypt.cs

Determines whether an existing hash should be rehashed using new settings.

public static bool NeedsRehash(ReadOnlySpan<char> hash, int workFactor = 11, BcryptVersion version = BcryptVersion.Revision2B)

Parameters

hash ReadOnlySpan<char>: The existing BCrypt hash.
workFactor int: The desired work factor.
version BcryptVersion: The desired BCrypt revision.

Returns

bool true if the hash should be replaced; otherwise, false.

Exceptions

FormatException: The hash is not a valid BCrypt hash format.

NeedsRehash(string, int, BcryptVersion)

Bcrypt.cs

Determines whether an existing hash should be rehashed using new settings.

public static bool NeedsRehash(string hash, int workFactor = 11, BcryptVersion version = BcryptVersion.Revision2B)

Parameters

hash string: The existing BCrypt hash.
workFactor int: The desired work factor.
version BcryptVersion: The desired BCrypt revision.

Returns

bool true if the hash should be replaced; otherwise, false.

Exceptions

FormatException: The hash is not a valid BCrypt hash format.

ParseHash overloads

ParseHash(ReadOnlySpan<char>)

Bcrypt.cs

Parses a BCrypt hash and returns its revision and work factor.

public static BcryptHashInfo ParseHash(ReadOnlySpan<char> hash)

Parameters

hash ReadOnlySpan<char>: The BCrypt hash string.

Returns

BcryptHashInfo The parsed hash information.

Exceptions

FormatException: The hash is not a valid BCrypt hash format.

ParseHash(string)

Bcrypt.cs

Parses a BCrypt hash and returns its revision and work factor.

public static BcryptHashInfo ParseHash(string hash)

Parameters

hash string: The BCrypt hash string.

Returns

BcryptHashInfo The parsed hash information.

Exceptions

FormatException: The hash is not a valid BCrypt hash format.

TryParseHash overloads

TryParseHash(ReadOnlySpan<char>, BcryptHashInfo)

Bcrypt.cs

Attempts to parse a BCrypt hash and extract its revision and work factor.

public static bool TryParseHash(ReadOnlySpan<char> hash, out BcryptHashInfo result)

Parameters

hash ReadOnlySpan<char>: The BCrypt hash string.
result BcryptHashInfo: When this method returns, contains parsed hash information if parsing succeeded.

Returns

bool true if parsing succeeded; otherwise, false.

TryParseHash(string?, BcryptHashInfo)

Bcrypt.cs

Attempts to parse a BCrypt hash and extract its revision and work factor.

public static bool TryParseHash(string? hash, out BcryptHashInfo result)

Parameters

hash string?: The BCrypt hash string.
result BcryptHashInfo: When this method returns, contains parsed hash information if parsing succeeded.

Returns

bool true if parsing succeeded; otherwise, false.

Verify overloads

Verify(ReadOnlySpan<char>, ReadOnlySpan<char>)

Bcrypt.cs

Verifies that a password matches a BCrypt hash.

public static bool Verify(ReadOnlySpan<char> password, ReadOnlySpan<char> hash)

Parameters

password ReadOnlySpan<char>: The plaintext password.
hash ReadOnlySpan<char>: The BCrypt hash string.

Returns

bool true if the password matches; otherwise, false.

Exceptions

NotSupportedException: hash uses the $2x$ revision, which cannot be verified correctly.

Remarks

A password that cannot be encoded as UTF-8 reports a mismatch rather than throwing.

Verify(string, string)

Bcrypt.cs

Verifies that a password matches a BCrypt hash.

public static bool Verify(string password, string hash)

Parameters

password string: The plaintext password.
hash string: The BCrypt hash string.

Returns

bool true if the password matches; otherwise, false.

Exceptions

NotSupportedException: hash uses the $2x$ revision, which cannot be verified correctly.

Remarks

A password that cannot be encoded as UTF-8 reports a mismatch rather than throwing.

Constants

Name	Description
DefaultWorkFactor	Default BCrypt work factor.
MaxPasswordLengthInBytes	Maximum number of UTF-8 bytes used by BCrypt for a password.
MaxWorkFactor	Maximum BCrypt work factor (cost).
MinWorkFactor	Minimum BCrypt work factor (cost).

DefaultWorkFactor

Default BCrypt work factor.

public const int DefaultWorkFactor = 11

MaxPasswordLengthInBytes

Maximum number of UTF-8 bytes used by BCrypt for a password.

public const int MaxPasswordLengthInBytes = 72

MaxWorkFactor

Maximum BCrypt work factor (cost).

public const int MaxWorkFactor = 31

MinWorkFactor

Minimum BCrypt work factor (cost).

public const int MinWorkFactor = 4