Argon2.Interop.Extensions.Calibration 1.0.0-beta-0001

Argon2 Interop

An interop allowing for Argon2 hashing in .NET Core using the Argon2 C implementation.

This library is still in early development. More documentation will be released as time permits.

How to Use

To use Argon2 Interop you will need to install the Argon2.Interop nuget package, as well as ensure the proper DLL is available at runtime based on your runtime architecture.

1. Install the Argon2.Interop nuget package.
2. Use the Argon2Interop class from the Argon2.Interop namespace to generate hashes.
3. Place a precompiled libargon2 DLL from the Assets directory next to your processes executable.

Which DLL to Use

The DLL you choose to use should be based on your runtime architecture. A simple table has been created below.

Several architectures are not available pre-compiled. This is due to my own limitations as I do not have all hardware available on which to compile libargon. If your desired architecture is not available you may compile libargon yourself, it has been included as a submodule under Source/External/phc-winner-argon2/ for your convenience.

Options

All common Argon2 options are available and their default values reflect that of a secure configuration. In most cases options should not need to be adjusted. Default option values can be located within the Argon2Options class.

Calibration

Argon2 options can be calibrated to your runtime hardware automatically based on a flexible set of calibration options. You can simply define your minimum/maximum values as well as the maximum duration Argon2 should take to generate a hash. Default calibration option values can be located within the Argon2CalibratorOptions class.

Calibrating Argon2

var calibrator = new Argon2Calibrator(); // Use default options.
var result = calibrator.Calibrate();

var bestOptions = result.BestResult?.Options;

if (bestOptions == default) {
    throw new CryptographyException("Failed to generate Argon2 options that meet base requirements.");
}

var argon2 = new Argon2Interop(bestOptions); // Pass calibrated options to Argon2Interop.
var hash = argon2.Hash("ilikecheese");

Usage Examples

Password Hashing

Under normal use, excluding extraordinary circumstances or requirements, the default option values are secure enough for most use cases. The following is all you typically will need.

Hashing a password:

var argon = new Argon2Interop();
var hash = argon2.Hash("ilikecheese"); // Returnes an encoded hashed password.

Verifying a Password

To verify a password, pass both the encoded password hash and the password to compare it against to the Verify function.

var argon = new Argon2Interop();

if (! argon.Verify(encoded, "ilikecheese")) {
    throw new InvalidPasswordException();
}

Custom Options

Custom options can be passed to the Argon2 constructor.

Using custom options:

var argon = new Argon2Interop(new Argon2InteropOptions() {
    MemoryCost = 1024 * 64,
    TimeCost = 24,
    Parallelism = 6,
    HashLength = 128,
    Type = Argon2Type.D,
    Version = Argon2Version.Nineteen
    });

var hash = argon2.Hash("ilikecheese");

Hashing to Bytes

In certain circumstances you may wish to work with the hash bytes directly. Hash bytes can be obtained by using the Hash overload that outputs both the hash bytes as well as the encoded hash string.

Hashing to bytes:

var argon = new Argon2Interop();
argon2.Hash("ilikecheese", out var hash, out var encoded); // Outputs hash bytes as well as an encoded hash string.

Custom Salts

Custom salts can be passed, though they are not necessarily required. By default a random cryptographically secured salt will be generated based on the password length.

Using custom salts:

var argon = new Argon2Interop();
argon2.Hash("ilikecheese", "qwe123!@#");