Shane32.Argon2 1.1.0

Shane32.Argon2

Provides a set of functions for hashing passwords using the Argon2 algorithm into a composite string containing the hash parameters, salt and hash.

Usage

The algorithm typically creates a single string containing both the hash parameters, salt and the hash itself.

using Shane32.Argon2;

// Select a set of parameters to use that require at least 0.2 seconds of hashing time
var parameters = await Argon2Library.SelectParametersAsync(
    parallelism: 2,
    minTime: TimeSpan.FromSeconds(0.2),
    hashLengthBits: 256,
    saltLengthBits: 128);

// Create a hash with generated parameters
var hash = await Argon2Library.HashAsync("password", parameters);

// Create a hash with custom parameters
var hash2 = await Argon2Library.HashAsync(
    "foobar",
    new Argon2Parameters(
        parallelism: 4,
        iterations: 16,
        memorySizeKb: 4096,
        hashLengthBits: 64));

// Verify a hash
var ok = await Argon2Library.VerifyAsync("password", hash);

You can also generate a string containing the parameters and salt separately from the hash:

// Create a salt
var salt = Argon2Library.CreateArgonSalt(parameters);

// Create a hash
var hash = await Argon2Library.HashAsync("password", salt, 256);

// Verify a hash
var ok = await Argon2Library.VerifyAsync("password", hash, salt);

It is also possible to create the hash with a known secret by passing a byte array to the above functions. The hash does not contain the secret and will require the secret to verify the hash against a password.

Format

The hash string is composed of multiple parts, separated by $, as shown below:

$a2id${parallelism}${iterations}${memorySize}${salt}${hash}

Example:

$a2id$4$4$12$08ivHvoRWVg=$Upe6Dg66bMM=

The above hash string was generated using the following parameters:

When the salt is stored separately from the hash, the salt string is the same as the hash described above, excluding the hash:

Notes

• This uses the Konscious.Security.Cryptography.Argon2 underlying library to create the Argon2 hash. The library is a C# implementation of Argon2 and may be subject to side-channel attacks.

• The Argon2id variant is used when creating hashes.

• The salt generation function uses the default .NET cryptographic random number generator and currently generates a salt of the same length as the desired hash length.

• The password fed to the Argon2id implementation is the UTF-16 little-endian encoding of the password string.

Recommended parameters

Current recommendations for Argon2 parameters vary widly based on the source and use case; some say:

The algorithm within SelectParametersAsync starts with the following parameters and then alternately doubles the iterations and memory size until the desired minimum hashing time is reached:

On the hardware used for testing, the following parameters were generated with a minimum hashing time of 0.5 seconds and a parallelism value of 2:

The SelectParametersAsync algorithm was designed with a certain use case in mind and may not fit your needs. It is also important to note that if the SelectParametersAsync algorithm is run concurrently with other tasks on the same machine, the generated parameters may be lower than typical.

Possible future features

• Support for Argon2, Argon2i, and Argon2d formats (would use unique prefix for each format)
• Support for verifying BCrypt passwords
• Integration of the underlying library to avoid the dependency
• Use of another underlying library that is not subject to side-channel attacks
• Execution of hash verification functions on a thread with a lower priority, and execution of parameter selection functions on a thread with a higher priority
• Wrapper to provide resistance to denial-of-service attacks

Credits

Glory to Jehovah, Lord of Lords and King of Kings, creator of Heaven and Earth, who through his Son Jesus Christ, has reedemed me to become a child of God. -Shane32