Argon2 Component

Properties   Methods   Events   Config Settings   Errors  

This component implements Argon2 cryptographic hashing function designed for password hashing and protecting against various types of attacks.

Syntax

nsoftware.IPWorksEncrypt.Argon2

Remarks

Argon2 is a memory-hard algorithm that can be used for secure key derivation. It supports three different variants of the algorithm.

To create a key using this component, start by setting the required properties:

• Password
• Salt

Optionally, specify the Algorithm variant, KeyLength in bytes, number of Iterations, degree of Parallelism and MemoryCost in kilobytes.

After calling the CreateKey method, the Key will be populated with the derived key.

Note: By default, the component uses the following values which are recommended by RFC 9106: Argon2id variant with 3 iterations, 4 degrees of parallelism, 64 MB of RAM, and 32 byte key length.

Create Key Example

//Create a key using Argon2 component Argon2 argon2 = new Argon2(); argon2.Password = "password"; argon2.Salt = "AAAABBBBCCCCDDDD"; //16 bytes string argon2.UseHex = true; //hex encoded key argon2.CreateKey(); Console.WriteLine(argon2.Key); //outputs the derived key, 32 bytes by default

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

Algorithm Property (Argon2 Component)

The variant used to derive the key.

Syntax

• C#
• VB.NET

public Argon2Algorithms Algorithm { get; set; }

enum Argon2Algorithms {
  aArgon2d,
  aArgon2i,
  aArgon2id
}

Public Property Algorithm As Argon2Algorithms

Enum Argon2Algorithms
  aArgon2d
  aArgon2i
  aArgon2id
End Enum

Default Value

2

Remarks

This property specifies which type of algorithm to use. Possible values are:

Iterations Property (Argon2 Component)

Number of iterations to perform.

Syntax

• C#
• VB.NET

public int Iterations { get; set; }

Public Property Iterations As Integer

Default Value

3

Remarks

The number of iterations is used to adjust the running time indepenently of the memory size. Valid values are from 1 to 2^(32)-1.

Key Property (Argon2 Component)

The derived key.

Syntax

• C#
• VB.NET

public string Key { get; }
public byte[] KeyB { get; }

Public ReadOnly Property Key As String
Public ReadOnly Property KeyB As Byte()

Default Value

""

Remarks

This property holds the derived key. After calling CreateKey this property will be populated.

This property is read-only.

KeyLength Property (Argon2 Component)

The desired length of the derived key (in bytes).

Syntax

• C#
• VB.NET

public int KeyLength { get; set; }

Public Property KeyLength As Integer

Default Value

32

Remarks

This property specifies the length of the key (in bytes) which will be created when CreateKey is called. Valid values are from 4 to 2^(32)-1.

MemoryCost Property (Argon2 Component)

The memory usage in kilobytes.

Syntax

• C#
• VB.NET

public int MemoryCost { get; set; }

Public Property MemoryCost As Integer

Default Value

65536

Remarks

This property defines the memory used (in kilobytes) when calling CreateKey.

Parallelism Property (Argon2 Component)

The degree of parallelism.

Syntax

• C#
• VB.NET

public int Parallelism { get; set; }

Public Property Parallelism As Integer

Default Value

4

Remarks

This proprety specifies the number of lanes used when calling CreateKey.

Password Property (Argon2 Component)

The password from which a derived key is generated.

Syntax

• C#
• VB.NET

public string Password { get; set; }
public byte[] PasswordB { get; set; }

Public Property Password As String
Public Property PasswordB As Byte()

Default Value

""

Remarks

This property specifies the password from which the derived key is created.

Salt Property (Argon2 Component)

The cryptographic salt used during key creation.

Syntax

• C#
• VB.NET

public string Salt { get; set; }
public byte[] SaltB { get; set; }

Public Property Salt As String
Public Property SaltB As Byte()

Default Value

""

Remarks

This proprety specifies the salt used when CreateKey is called. The salt should be a unique value and should be at least 16 bytes in length.

UseHex Property (Argon2 Component)

Whether the key is hex encoded.

Syntax

• C#
• VB.NET

public bool UseHex { get; set; }

Public Property UseHex As Boolean

Default Value

False

Remarks

This property specifies whether the created Key is hex encoded when calling CreateKey. The default value is false.

Config Method (Argon2 Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

CreateKey Method (Argon2 Component)

Derives a key from the specified password.

Syntax

• C#
• VB.NET

public void CreateKey();

Async Version
public async Task CreateKey();
public async Task CreateKey(CancellationToken cancellationToken);

Public Sub CreateKey()

Async Version
Public Sub CreateKey() As Task
Public Sub CreateKey(cancellationToken As CancellationToken) As Task

Remarks

This method derives a key from the specified password using Argon2.

The following properties are applicable when calling this method:

• Password (required)
• Salt (required)
• Algorithm
• Iterations
• KeyLength
• MemoryCost
• Parallelism

Create Key Example

//Create a key using Argon2 component Argon2 argon2 = new Argon2(); argon2.Password = "password"; argon2.Salt = "AAAABBBBCCCCDDDD"; //16 bytes string argon2.UseHex = true; //hex encoded key argon2.CreateKey(); Console.WriteLine(argon2.Key); //outputs the derived key, 32 bytes by default

Reset Method (Argon2 Component)

Resets the component.

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

When called, the component will reset all of its properties to their default values.

Error Event (Argon2 Component)

Fired when information is available about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, Argon2ErrorEventArgs e);

public class Argon2ErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As Argon2ErrorEventArgs)

Public Class Argon2ErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Config Settings (Argon2 Component)

Argon2 Config Settings

Base Config Settings

Trappable Errors (Argon2 Component)

Argon2 Errors