C# Class Liphsoft.Crypto.Argon2.PasswordHasher

PasswordHasher is a class for creating Argon2 hashes and verifying them. This is a wrapper around Daniel Dinu and Dmitry Khovratovich's Argon2 library.
Inheritance: IPasswordHasher
Show file Open project: alipha/csharp-argon2 Class Usage Examples

Public Methods

Method Description
ExtractMetadata ( string formattedHash ) : HashMetadata

Extracts the memory cost, time cost, etc. used to generate the Argon2 hash. An encoded Argon2 hash created by the Hash method The hash metadata or null if the formattedHash was not a valid encoded Argon2 hash
GenerateSalt ( uint byteLength = 16 ) : byte[]

Generate salt using a Cryptographically-Secure Pseudo-Random Number Generator The number of bytes of salt to generate (default: 16) A array of randomly-generated bytes
Hash ( byte password ) : string

Hash the raw password bytes using Argon2 with a cryptographically-secure, random, 16-byte salt. Do not compare two Argon2 hashes directly. Instead, use the Verify or VerifyAndUpdate methods. The raw bytes of the password to be hashed A formatted string representing the hashed password, encoded with the parameters used to perform the hash
Hash ( byte password, byte salt ) : string

Hash the raw password bytes using Argon2 with the specified salt bytes. Unless you need to specify your own salt for interoperability purposes, prefer the Hash(byte[] password) overload instead. Do not compare two Argon2 hashes directly. Instead, use the Verify or VerifyAndUpdate methods. The raw bytes of the password to be hashed The raw salt bytes to be used for the hash. The salt must be at least 8 bytes. A formatted string representing the hashed password, encoded with the parameters used to perform the hash
Hash ( string password ) : string

Hash the password using Argon2 with a cryptographically-secure, random, 16-byte salt. This is the only overload of the Hash method that the typical user will need to use for password storage. The other overloads are provided for interoperability purposes. Do not compare two Argon2 hashes directly. Instead, use the Verify or VerifyAndUpdate methods. A string representing the password to be hashed. The password is first decoded into bytes using StringEncoding (default: Encoding.UTF8) A formatted string representing the hashed password, encoded with the parameters used to perform the hash
Hash ( string password, string salt ) : string

Hash the password using Argon2 with the specified salt. Unless you need to specify your own salt for interoperability purposes, prefer the Hash(string password) overload instead. Do not compare two Argon2 hashes directly. Instead, use the Verify or VerifyAndUpdate methods. A string representing the password to be hashed. The password is first decoded into bytes using StringEncoding (default: Encoding.UTF8) A string representing the salt to be used for the hash. The salt must be at least 8 bytes. The salt is first decoded into bytes using StringEncoding (default: Encoding.UTF8) A formatted string representing the hashed password, encoded with the parameters used to perform the hash
HashRaw ( byte password, byte salt ) : byte[]

Hash the password using Argon2 with the specified salt. The HashRaw methods may be used for password-based key derivation. Unless you're using HashRaw for key deriviation or for interoperability purposes, the Hash methods should be used in favor of the HashRaw methods. The raw bytes of the password to be hashed The raw salt bytes to be used for the hash. The salt must be at least 8 bytes. A byte array containing only the resulting hash
HashRaw ( string password, string salt ) : byte[]

Hash the password using Argon2 with the specified salt. The HashRaw methods may be used for password-based key derivation. Unless you're using HashRaw for key deriviation or for interoperability purposes, the Hash methods should be used in favor of the HashRaw methods. A string representing the password to be hashed. The password is first decoded into bytes using StringEncoding (default: Encoding.UTF8) A string representing the salt to be used for the hash. The salt must be at least 8 bytes. The salt is first decoded into bytes using StringEncoding (default: Encoding.UTF8) A byte array containing only the resulting hash
PasswordHasher ( UsageEnvironment environment ) : System

Initialize the Argon2 PasswordHasher with default performance and algorithm settings based upon the environment the hashing will be used in. You should perform your own profiling to determine what the parameters should be for your specific usage; however, this attempts to provide some reasonable defaults. Whether the PasswordHasher will be used in a server or single-user setting
PasswordHasher ( uint timeCost = 3, uint memoryCost = 8192, uint parallelism = 1, Argon2Type argonType = Argon2Type.Argon2i, uint hashLength = 32 ) : System

Initialize the Argon2 PasswordHasher with the performance and algorithm settings to use while hashing How many iterations of the Argon2 hash to perform (default: 3, must be at least 1) How much memory to use while hashing in kibibytes (KiB) (default: 8192 KiB [8 MiB], must be at least 8 KiB) How many threads to use while hashing (default: 1, must be at least 1) The type of Argon2 hashing algorithm to use (Independent [default] or Dependent) The length of the resulting hash in bytes (default: 32)
Verify ( string expectedHash, byte password ) : bool

Hashes the raw password bytes and verifies that the password results in the specified hash. The ArgonType must of this PasswordHasher object must match what was used to generate expectedHash. The other parameters (timeCost, etc.) do not need to match and the parameters embedded in the expectedHash will be used. Hashing the password should result in this hash The raw password bytes to hash and compare its result to expectedHash Whether the password results in the expectedHash when hashed
Verify ( string expectedHash, string password ) : bool

Hashes the password and verifies that the password results in the specified hash. The ArgonType must of this PasswordHasher object must match what was used to generate expectedHash. The other parameters (timeCost, etc.) do not need to match and the parameters embedded in the expectedHash will be used. Hashing the password should result in this hash The password to hash and compare its result to expectedHash. The password is first decoded into bytes using StringEncoding (default: Encoding.UTF8) Whether the password results in the expectedHash when hashed
VerifyAndUpdate ( string expectedHash, byte password, bool &isUpdated, string &newFormattedHash ) : bool

Hashes the password and verifies that the password results in the specified hash. (See Verify method) If the password verification is successful, this method checks to see if the memory cost, time cost, and parallelism match the parameters the PasswordHasher object was constructed with. If they do not much, then the password is rehashed using the new parameters and the result is outputted via the newFormattedHash parameter. Hashing the password should result in this hash The raw password bytes to hash and compare its result to expectedHash Whether the cost parameters of expectedHash differ from the PasswordHasher object and if the password was rehashed using th new parameters. This is always false if the password was incorrect. If isUpdated is true, then newFormattedHash is the password hashed with the new cost parameters. If isUpdated is false, then newFormattedHash is expectedHash. Whether the password results in the expectedHash when hashed
VerifyAndUpdate ( string expectedHash, string password, bool &isUpdated, string &newFormattedHash ) : bool

Hashes the password and verifies that the password results in the specified hash. (See Verify method) If the password verification is successful, this method checks to see if the memory cost, time cost, and parallelism match the parameters the PasswordHasher object was constructed with. If they do not much, then the password is rehashed using the new parameters and the result is outputted via the newFormattedHash parameter. Hashing the password should result in this hash The password to hash and compare its result to expectedHash. The password is first decoded into bytes using StringEncoding (default: Encoding.UTF8) Whether the cost parameters of expectedHash differ from the PasswordHasher object and if the password was rehashed using th new parameters. This is always false if the password was incorrect. If isUpdated is true, then newFormattedHash is the password hashed with the new cost parameters. If isUpdated is false, then newFormattedHash is expectedHash. Whether the password results in the expectedHash when hashed

Private Methods

Method Description
CheckNull ( string methodName ) : void
crypto_argon2_hash ( uint t_cost, uint m_cost, uint parallelism, byte pwd, int pwdlen, byte salt, int saltlen, byte hash, int hashlen, byte encoded, int encodedlen, int type, int version ) : int
crypto_argon2_verify ( byte encoded, byte pwd, int pwdlen, int type ) : int
crypto_decode_string ( Argon2Context ctx, byte str, int type ) : int

Method Details

ExtractMetadata() public static method

Extracts the memory cost, time cost, etc. used to generate the Argon2 hash. An encoded Argon2 hash created by the Hash method The hash metadata or null if the formattedHash was not a valid encoded Argon2 hash
public static ExtractMetadata ( string formattedHash ) : HashMetadata
formattedHash string
return HashMetadata

GenerateSalt() public static method

Generate salt using a Cryptographically-Secure Pseudo-Random Number Generator The number of bytes of salt to generate (default: 16) A array of randomly-generated bytes
public static GenerateSalt ( uint byteLength = 16 ) : byte[]
byteLength uint
return byte[]

Hash() public method

Hash the raw password bytes using Argon2 with a cryptographically-secure, random, 16-byte salt. Do not compare two Argon2 hashes directly. Instead, use the Verify or VerifyAndUpdate methods. The raw bytes of the password to be hashed A formatted string representing the hashed password, encoded with the parameters used to perform the hash
public Hash ( byte password ) : string
password byte
return string

Hash() public method

Hash the raw password bytes using Argon2 with the specified salt bytes. Unless you need to specify your own salt for interoperability purposes, prefer the Hash(byte[] password) overload instead. Do not compare two Argon2 hashes directly. Instead, use the Verify or VerifyAndUpdate methods. The raw bytes of the password to be hashed The raw salt bytes to be used for the hash. The salt must be at least 8 bytes. A formatted string representing the hashed password, encoded with the parameters used to perform the hash
public Hash ( byte password, byte salt ) : string
password byte
salt byte
return string

Hash() public method

Hash the password using Argon2 with a cryptographically-secure, random, 16-byte salt. This is the only overload of the Hash method that the typical user will need to use for password storage. The other overloads are provided for interoperability purposes. Do not compare two Argon2 hashes directly. Instead, use the Verify or VerifyAndUpdate methods. A string representing the password to be hashed. The password is first decoded into bytes using StringEncoding (default: Encoding.UTF8) A formatted string representing the hashed password, encoded with the parameters used to perform the hash
public Hash ( string password ) : string
password string
return string

Hash() public method

Hash the password using Argon2 with the specified salt. Unless you need to specify your own salt for interoperability purposes, prefer the Hash(string password) overload instead. Do not compare two Argon2 hashes directly. Instead, use the Verify or VerifyAndUpdate methods. A string representing the password to be hashed. The password is first decoded into bytes using StringEncoding (default: Encoding.UTF8) A string representing the salt to be used for the hash. The salt must be at least 8 bytes. The salt is first decoded into bytes using StringEncoding (default: Encoding.UTF8) A formatted string representing the hashed password, encoded with the parameters used to perform the hash
public Hash ( string password, string salt ) : string
password string
salt string
return string

HashRaw() public method

Hash the password using Argon2 with the specified salt. The HashRaw methods may be used for password-based key derivation. Unless you're using HashRaw for key deriviation or for interoperability purposes, the Hash methods should be used in favor of the HashRaw methods. The raw bytes of the password to be hashed The raw salt bytes to be used for the hash. The salt must be at least 8 bytes. A byte array containing only the resulting hash
public HashRaw ( byte password, byte salt ) : byte[]
password byte
salt byte
return byte[]

HashRaw() public method

Hash the password using Argon2 with the specified salt. The HashRaw methods may be used for password-based key derivation. Unless you're using HashRaw for key deriviation or for interoperability purposes, the Hash methods should be used in favor of the HashRaw methods. A string representing the password to be hashed. The password is first decoded into bytes using StringEncoding (default: Encoding.UTF8) A string representing the salt to be used for the hash. The salt must be at least 8 bytes. The salt is first decoded into bytes using StringEncoding (default: Encoding.UTF8) A byte array containing only the resulting hash
public HashRaw ( string password, string salt ) : byte[]
password string
salt string
return byte[]

PasswordHasher() public method

Initialize the Argon2 PasswordHasher with default performance and algorithm settings based upon the environment the hashing will be used in. You should perform your own profiling to determine what the parameters should be for your specific usage; however, this attempts to provide some reasonable defaults. Whether the PasswordHasher will be used in a server or single-user setting
public PasswordHasher ( UsageEnvironment environment ) : System
environment UsageEnvironment
return System

PasswordHasher() public method

Initialize the Argon2 PasswordHasher with the performance and algorithm settings to use while hashing How many iterations of the Argon2 hash to perform (default: 3, must be at least 1) How much memory to use while hashing in kibibytes (KiB) (default: 8192 KiB [8 MiB], must be at least 8 KiB) How many threads to use while hashing (default: 1, must be at least 1) The type of Argon2 hashing algorithm to use (Independent [default] or Dependent) The length of the resulting hash in bytes (default: 32)
public PasswordHasher ( uint timeCost = 3, uint memoryCost = 8192, uint parallelism = 1, Argon2Type argonType = Argon2Type.Argon2i, uint hashLength = 32 ) : System
timeCost uint
memoryCost uint
parallelism uint
argonType Argon2Type
hashLength uint
return System

Verify() public method

Hashes the raw password bytes and verifies that the password results in the specified hash. The ArgonType must of this PasswordHasher object must match what was used to generate expectedHash. The other parameters (timeCost, etc.) do not need to match and the parameters embedded in the expectedHash will be used. Hashing the password should result in this hash The raw password bytes to hash and compare its result to expectedHash Whether the password results in the expectedHash when hashed
public Verify ( string expectedHash, byte password ) : bool
expectedHash string
password byte
return bool

Verify() public method

Hashes the password and verifies that the password results in the specified hash. The ArgonType must of this PasswordHasher object must match what was used to generate expectedHash. The other parameters (timeCost, etc.) do not need to match and the parameters embedded in the expectedHash will be used. Hashing the password should result in this hash The password to hash and compare its result to expectedHash. The password is first decoded into bytes using StringEncoding (default: Encoding.UTF8) Whether the password results in the expectedHash when hashed
public Verify ( string expectedHash, string password ) : bool
expectedHash string
password string
return bool

VerifyAndUpdate() public method

Hashes the password and verifies that the password results in the specified hash. (See Verify method) If the password verification is successful, this method checks to see if the memory cost, time cost, and parallelism match the parameters the PasswordHasher object was constructed with. If they do not much, then the password is rehashed using the new parameters and the result is outputted via the newFormattedHash parameter. Hashing the password should result in this hash The raw password bytes to hash and compare its result to expectedHash Whether the cost parameters of expectedHash differ from the PasswordHasher object and if the password was rehashed using th new parameters. This is always false if the password was incorrect. If isUpdated is true, then newFormattedHash is the password hashed with the new cost parameters. If isUpdated is false, then newFormattedHash is expectedHash. Whether the password results in the expectedHash when hashed
public VerifyAndUpdate ( string expectedHash, byte password, bool &isUpdated, string &newFormattedHash ) : bool
expectedHash string
password byte
isUpdated bool
newFormattedHash string
return bool

VerifyAndUpdate() public method

Hashes the password and verifies that the password results in the specified hash. (See Verify method) If the password verification is successful, this method checks to see if the memory cost, time cost, and parallelism match the parameters the PasswordHasher object was constructed with. If they do not much, then the password is rehashed using the new parameters and the result is outputted via the newFormattedHash parameter. Hashing the password should result in this hash The password to hash and compare its result to expectedHash. The password is first decoded into bytes using StringEncoding (default: Encoding.UTF8) Whether the cost parameters of expectedHash differ from the PasswordHasher object and if the password was rehashed using th new parameters. This is always false if the password was incorrect. If isUpdated is true, then newFormattedHash is the password hashed with the new cost parameters. If isUpdated is false, then newFormattedHash is expectedHash. Whether the password results in the expectedHash when hashed
public VerifyAndUpdate ( string expectedHash, string password, bool &isUpdated, string &newFormattedHash ) : bool
expectedHash string
password string
isUpdated bool
newFormattedHash string
return bool