Argon2 Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

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 class with short descriptions. Click on the links for further details.

Method List

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

Event List

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

Config Settings

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

Algorithm Property (Argon2 Class)

The variant used to derive the key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAlgorithm();
int SetAlgorithm(int iAlgorithm);

Unicode (Windows)
INT GetAlgorithm();
INT SetAlgorithm(INT iAlgorithm);

A_ARGON_2D(0), 
A_ARGON_2I(1), 
A_ARGON_2ID(2)

int ipworksencrypt_argon2_getalgorithm(void* lpObj);
int ipworksencrypt_argon2_setalgorithm(void* lpObj, int iAlgorithm);

int GetAlgorithm();
int SetAlgorithm(int iAlgorithm);

Default Value

2

Remarks

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

Data Type

Integer

Iterations Property (Argon2 Class)

Number of iterations to perform.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIterations();
int SetIterations(int iIterations);

Unicode (Windows)
INT GetIterations();
INT SetIterations(INT iIterations);

int ipworksencrypt_argon2_getiterations(void* lpObj);
int ipworksencrypt_argon2_setiterations(void* lpObj, int iIterations);

int GetIterations();
int SetIterations(int iIterations);

Default Value

3

Remarks

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

Data Type

Integer

Key Property (Argon2 Class)

The derived key.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetKey(char* &lpKey, int &lenKey);

Unicode (Windows)
INT GetKey(LPSTR &lpKey, INT &lenKey);

int ipworksencrypt_argon2_getkey(void* lpObj, char** lpKey, int* lenKey);

QByteArray GetKey();

Default Value

""

Remarks

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

This property is read-only.

Data Type

Binary String

KeyLength Property (Argon2 Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetKeyLength();
int SetKeyLength(int iKeyLength);

Unicode (Windows)
INT GetKeyLength();
INT SetKeyLength(INT iKeyLength);

int ipworksencrypt_argon2_getkeylength(void* lpObj);
int ipworksencrypt_argon2_setkeylength(void* lpObj, int iKeyLength);

int GetKeyLength();
int SetKeyLength(int iKeyLength);

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.

Data Type

Integer

MemoryCost Property (Argon2 Class)

The memory usage in kilobytes.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetMemoryCost();
int SetMemoryCost(int iMemoryCost);

Unicode (Windows)
INT GetMemoryCost();
INT SetMemoryCost(INT iMemoryCost);

int ipworksencrypt_argon2_getmemorycost(void* lpObj);
int ipworksencrypt_argon2_setmemorycost(void* lpObj, int iMemoryCost);

int GetMemoryCost();
int SetMemoryCost(int iMemoryCost);

Default Value

65536

Remarks

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

Data Type

Integer

Parallelism Property (Argon2 Class)

The degree of parallelism.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetParallelism();
int SetParallelism(int iParallelism);

Unicode (Windows)
INT GetParallelism();
INT SetParallelism(INT iParallelism);

int ipworksencrypt_argon2_getparallelism(void* lpObj);
int ipworksencrypt_argon2_setparallelism(void* lpObj, int iParallelism);

int GetParallelism();
int SetParallelism(int iParallelism);

Default Value

4

Remarks

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

Data Type

Integer

Password Property (Argon2 Class)

The password from which a derived key is generated.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetPassword(char* &lpPassword, int &lenPassword);
int SetPassword(const char* lpPassword, int lenPassword);

Unicode (Windows)
INT GetPassword(LPSTR &lpPassword, INT &lenPassword);
INT SetPassword(LPCSTR lpPassword, INT lenPassword);

int ipworksencrypt_argon2_getpassword(void* lpObj, char** lpPassword, int* lenPassword);
int ipworksencrypt_argon2_setpassword(void* lpObj, const char* lpPassword, int lenPassword);

QByteArray GetPassword();
int SetPassword(QByteArray qbaPassword);

Default Value

""

Remarks

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

Data Type

Binary String

Salt Property (Argon2 Class)

The cryptographic salt used during key creation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSalt(char* &lpSalt, int &lenSalt);
int SetSalt(const char* lpSalt, int lenSalt);

Unicode (Windows)
INT GetSalt(LPSTR &lpSalt, INT &lenSalt);
INT SetSalt(LPCSTR lpSalt, INT lenSalt);

int ipworksencrypt_argon2_getsalt(void* lpObj, char** lpSalt, int* lenSalt);
int ipworksencrypt_argon2_setsalt(void* lpObj, const char* lpSalt, int lenSalt);

QByteArray GetSalt();
int SetSalt(QByteArray qbaSalt);

Default Value

""

Remarks

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

Data Type

Binary String

UseHex Property (Argon2 Class)

Whether the key is hex encoded.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetUseHex();
int SetUseHex(int bUseHex);

Unicode (Windows)
BOOL GetUseHex();
INT SetUseHex(BOOL bUseHex);

int ipworksencrypt_argon2_getusehex(void* lpObj);
int ipworksencrypt_argon2_setusehex(void* lpObj, int bUseHex);

bool GetUseHex();
int SetUseHex(bool bUseHex);

Default Value

FALSE

Remarks

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

Data Type

Boolean

Config Method (Argon2 Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* ipworksencrypt_argon2_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

CreateKey Method (Argon2 Class)

Derives a key from the specified password.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CreateKey();

Unicode (Windows)
INT CreateKey();

int ipworksencrypt_argon2_createkey(void* lpObj);

int CreateKey();

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Reset Method (Argon2 Class)

Resets the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Reset();

Unicode (Windows)
INT Reset();

int ipworksencrypt_argon2_reset(void* lpObj);

int Reset();

Remarks

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

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Error Event (Argon2 Class)

Fired when information is available about errors during data delivery.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(Argon2ErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} Argon2ErrorEventParams;


Unicode (Windows)
virtual INT FireError(Argon2ErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} Argon2ErrorEventParams;

#define EID_ARGON2_ERROR 1

virtual INT IPWORKSENCRYPT_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class Argon2ErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(Argon2ErrorEventParams *e);

// Or, subclass Argon2 and override this emitter function.
virtual int FireError(Argon2ErrorEventParams *e) {...}

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

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 Class)

Argon2 Config Settings

Base Config Settings

Trappable Errors (Argon2 Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Argon2 Errors