Argon2 Class

Namespace: Rebex.Security.Cryptography

Assembly: Rebex.Security.dll (version 7.0.9147)

This class represents Argon2 memory-hard hash algorithm for password hashing and proof-of-work applications. Specified by RFC 9106. Supports all Argon2 variants: Argon2i, Argon2d, and Argon2id.

Syntax

public sealed class Argon2 : DeriveBytes, IDisposable

Inheritance

Object

DeriveBytes

Argon2

Implements

IDisposable

Inherited Members

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

Object.ToString()

DeriveBytes.Dispose()

DeriveBytes.Dispose(Boolean)

Remarks

Argon2 class inherits from .NET's DeriveBytes class and overrides the GetBytes(Int32) method. However, in scenarios where an instance of this class is not needed, the following static (shared in VB) methods are recommended:

HashData - computes a raw Argon2 hash from the specified data.
HashPassword - computes Argon2 hash from the specified password and encodes it.
VerifyPassword - verifies password by computing an Argon2 hash and matching it agains the specified hash.

Encoded hashes in HashPasswordand/VerifyPassword methods use the following format:

$argon2<argon2variant>$v=<argon2version>$m=<number>,t=<number>,p=<number>$<salt>$<hash>

Example:

$argon2d$v=19$m=4096,t=4,p=1$CIlDXZQtjjt97RIvRQ7+6A$xZpr76HnKT27Q5ZMe6eVppaANEAXEFC5YwdDjDtCWBk

Description:

argon2variant - Argon2 variant (argon2i, argon2d, or argon2id).
v=<argon2version> - Argon2 algorithm version. Only value 19 (0x13) representing Argon2 version 1.3 is currently supported.
m=<number> - amount of memory, in kilobytes (KB), used by the Argon2 algorithm. Parameter 'm' from Argon2 specification.
t=<number> - number of Argon2 iterations. Parameter 't' from Argon2 specification.
p=<number> - number of independent computation lanes. Parameter 'p' from Argon2 specification.
<salt> - Base64-encoded salt. Parameter 'S' from Argon2 specification.
<hash> - Base64-encoded hash of the password.

Examples

public string HashUserPassword(string userPassword)
{
    // Use Argon2 configuration suitable for your environment.
    // In typical 'hash user password' scenarios, the configuration does not change between
    // method calls, so it is recommended to cache the Argon2Configuration instance.
    var configuration = new Argon2Configuration(argon2Type: Argon2Type.Argon2id,
        numberOfLanes: 4, numberOfIterations: 10, memoryCost: 65536);

    // The size of the raw hash to compute. Must be at least 4 bytes long.
    // Please note that the encoded hash (in string form) will be longer than the raw hash.
    int hashLength = 32;

    // Compute the hash of the password.
    // This method generates a random (16 bytes long) salt value.
    // To provide custom salt, use another overload of the HashPassword method.
    string encodedHash = Argon2.HashPassword(userPassword, hashLength, configuration);

    // Return the computed hash. Encoded hash has the following structure:
    // $argon2id$v=19$m=65536,t=10,p=4$MTIzNDU2Nzg$GVfTf0x89BTwcW7HhQMYRcgPwOzswaw6UUBWDBXP0kc
    return encodedHash;
}

// An encodedPasswordHash value previously created using the HashUserPassword method above.
// Encoded hash has the following structure:
// $argon2id$v=19$m=65536,t=10,p=4$MTIzNDU2Nzg$GVfTf0x89BTwcW7HhQMYRcgPwOzswaw6UUBWDBXP0kc
public bool CanAuthenticateUser(string encodedPasswordHash, byte[] userPasswordFromUi)
{
    // Returns true when encodePasswordHash matches the hash of userPasswordFromUi;
    // otherwise returns false.
    return Argon2.VerifyPassword(encodedPasswordHash, userPasswordFromUi);
}

Constructors

Name	Description
Argon2(Argon2Configuration, Byte[], Byte[])	Initializes a new instance of Argon2 class.
Argon2(Argon2Configuration, Byte[], Byte[], Byte[])	Initializes a new instance of Argon2 class.
Argon2(Argon2Configuration, Byte[], Byte[], Byte[], Byte[])	Initializes a new instance of Argon2 class.

Properties

Name	Description
Configuration	Gets Argon2 configuration for this instance.

Methods

Name	Description
GetBytes(Int32)	Derives bytes (a hash) using Argon2 algorithm.
HashData(ArraySegment<Byte>, ArraySegment<Byte>, ArraySegment<Byte>, Argon2Configuration)	Computes a hash using Argon2 memory-hard hash algorithm.
HashData(ArraySegment<Byte>, ArraySegment<Byte>, ArraySegment<Byte>, ArraySegment<Byte>, ArraySegment<Byte>, Argon2Configuration)	Computes a hash using Argon2 memory-hard hash algorithm.
HashData(ArraySegment<Byte>, ArraySegment<Byte>, Int32, Argon2Configuration)	Computes a hash using Argon2 memory-hard hash algorithm.
HashData(Byte[], Byte[], Int32, Argon2Configuration)	Computes a hash using Argon2 memory-hard hash algorithm.
HashPassword(ArraySegment<Byte>, ArraySegment<Byte>, Int32, Argon2Configuration)	Computes a hash of the specified `password` and returns it in encoded form. The format of the encoded hash is described in the remarks section of Argon2 class documentation.
HashPassword(ArraySegment<Byte>, Int32, Argon2Configuration)	Computes a hash of the specified `password` and returns it in encoded form. The method generates a random (16 bytes long) salt (parameter 'S' from Argon2 specification) before hashing. The format of the encoded hash is described in the remarks section of Argon2 class documentation.
HashPassword(Byte[], Byte[], Int32, Argon2Configuration)	Computes a hash of the specified `password` and returns it in encoded form. The format of the encoded hash is described in the remarks section of Argon2 class documentation.
HashPassword(Byte[], Int32, Argon2Configuration)	Computes a hash of the specified `password` and returns it in encoded form. Generates a random (16 bytes long) salt (parameter 'S' from Argon2 specification) before hashing. The format of the encoded hash is described in the remarks section of Argon2 class documentation.
HashPassword(String, ArraySegment<Byte>, Int32, Argon2Configuration)	Computes a hash of the specified `password` and returns it in encoded form. The format of the encoded hash is described in the remarks section of Argon2 class documentation.
HashPassword(String, Byte[], Int32, Argon2Configuration)	Computes a hash of the specified `password` and returns it in encoded form. The format of the encoded hash is described in the remarks section of Argon2 class documentation.
HashPassword(String, Int32, Argon2Configuration)	Computes a hash of the specified `password` and returns it in encoded form. The method generates a random (16 bytes long) salt (parameter 'S' from Argon2 specification) before hashing. The format of the encoded hash is described in the remarks section of Argon2 class documentation.
Reset()	Resets the state of the Argon2 instance.
VerifyPassword(String, ArraySegment<Byte>)	Verifies that the `encodedPasswordHash` matches the hash of the `password`. The format of the encoded hash is described in the remarks section of Argon2 class documentation.
VerifyPassword(String, Byte[])	Verifies that the `encodedPasswordHash` matches the hash of the `password`. The format of the encoded hash is described in the remarks section of Argon2 class documentation.
VerifyPassword(String, String)	Verifies that the `encodedPasswordHash` matches the hash of the `password`. The format of the encoded hash is described in the remarks section of Argon2 class documentation.