Argon2.Interop 1.0.0-beta-0007

This is a prerelease version of Argon2.Interop.
dotnet add package Argon2.Interop --version 1.0.0-beta-0007                
NuGet\Install-Package Argon2.Interop -Version 1.0.0-beta-0007                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Argon2.Interop" Version="1.0.0-beta-0007" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Argon2.Interop --version 1.0.0-beta-0007                
#r "nuget: Argon2.Interop, 1.0.0-beta-0007"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Argon2.Interop as a Cake Addin
#addin nuget:?package=Argon2.Interop&version=1.0.0-beta-0007&prerelease

// Install Argon2.Interop as a Cake Tool
#tool nuget:?package=Argon2.Interop&version=1.0.0-beta-0007&prerelease                

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.

Operating System x86 x64 arm64
Linux x86/libargon.so x64/libargon.so
MacOS arm64/libargon.dylib
Windows x86/libargon.dll x64/libargon.dll

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!@#");
Product Compatible and additional computed target framework versions.
.NET net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net7.0

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Argon2.Interop:

Package Downloads
Argon2.Interop.Extensions.Calibration

Automatically calibrate Argon2 Interop options to achieve maximum hash strength based on a flexible set of requirements.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.0-beta-0007 199 1/11/2024

Initial beta release.