Struct ipworksencrypt::Argon2

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

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, key_length in bytes, number of iterations, degree of parallelism and memory_cost in kilobytes.

After calling the create_key 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

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintained by IPWorksEncrypt. Due to this, the Argon2 struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of Argon2 when you have finished using the instance.

Property List

---

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

Method List

---

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

Event List

---

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

Config Settings

---

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

algorithm property (Argon2 Struct)

The variant used to derive the key.

Syntax

fn algorithm(&self ) -> Result<i32, IPWorksEncryptError> 
fn set_algorithm(&self, value : i32) ->  Option<IPWorksEncryptError> 

Possible Values

0   // Argon2d
1   // Argon2i
2   // Argon2id

Default Value

2

Remarks

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

Data Type

i32

iterations property (Argon2 Struct)

Number of iterations to perform.

Syntax

fn iterations(&self ) -> Result<i32, IPWorksEncryptError> 
fn set_iterations(&self, value : i32) ->  Option<IPWorksEncryptError> 

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

i32

key property (Argon2 Struct)

The derived key.

Syntax

fn key(&self ) -> Result<Vec<u8>, IPWorksEncryptError> 

Default Value

""

Remarks

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

This property is read-only.

Data Type

Vec

key_length property (Argon2 Struct)

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

Syntax

fn key_length(&self ) -> Result<i32, IPWorksEncryptError> 
fn set_key_length(&self, value : i32) ->  Option<IPWorksEncryptError> 

Default Value

32

Remarks

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

Data Type

i32

memory_cost property (Argon2 Struct)

The memory usage in kilobytes.

Syntax

fn memory_cost(&self ) -> Result<i32, IPWorksEncryptError> 
fn set_memory_cost(&self, value : i32) ->  Option<IPWorksEncryptError> 

Default Value

65536

Remarks

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

Data Type

i32

parallelism property (Argon2 Struct)

The degree of parallelism.

Syntax

fn parallelism(&self ) -> Result<i32, IPWorksEncryptError> 
fn set_parallelism(&self, value : i32) ->  Option<IPWorksEncryptError> 

Default Value

4

Remarks

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

Data Type

i32

password property (Argon2 Struct)

The password from which a derived key is generated.

Syntax

fn password(&self ) -> Result<Vec<u8>, IPWorksEncryptError> 
fn set_password(&self, value : Vec<u8>) ->  Option<IPWorksEncryptError> 
fn set_password_ref(&self, value : &[u8]) ->  Option<IPWorksEncryptError> 

Default Value

""

Remarks

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

Data Type

Vec

salt property (Argon2 Struct)

The cryptographic salt used during key creation.

Syntax

fn salt(&self ) -> Result<Vec<u8>, IPWorksEncryptError> 
fn set_salt(&self, value : Vec<u8>) ->  Option<IPWorksEncryptError> 
fn set_salt_ref(&self, value : &[u8]) ->  Option<IPWorksEncryptError> 

Default Value

""

Remarks

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

Data Type

Vec

use_hex property (Argon2 Struct)

Whether the key is hex encoded.

Syntax

fn use_hex(&self ) -> Result<bool, IPWorksEncryptError> 
fn set_use_hex(&self, value : bool) ->  Option<IPWorksEncryptError> 

Default Value

false

Remarks

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

Data Type

bool

config method (Argon2 Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &str) ->  Result<String, IPWorksEncryptError>

Remarks

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

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

create_key method (Argon2 Struct)

Derives a key from the specified password.

Syntax

fn create_key(&self) -> Result<(), IPWorksEncryptError>

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
• key_length
• memory_cost
• parallelism

This method populates the key property with the created (derived) key.

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

Resets the struct.

Syntax

fn reset(&self) -> Result<(), IPWorksEncryptError>

Remarks

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

on_error event (Argon2 Struct)

Fired when information is available about errors during data delivery.

Syntax

// Argon2ErrorEventArgs carries the Argon2 Error event's parameters.
pub struct Argon2ErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// Argon2ErrorEvent defines the signature of the Argon2 Error event's handler function.
pub trait Argon2ErrorEvent {
  fn on_error(&self, sender : Argon2, e : &mut Argon2ErrorEventArgs);
}

impl <'a> Argon2<'a> {
  pub fn on_error(&self) -> &'a dyn Argon2ErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn Argon2ErrorEvent);
  ...
}

Remarks

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

The error_code 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 Struct)

The struct accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

Argon2 Config Settings

Base Config Settings

Trappable Errors (Argon2 Struct)

Argon2 Errors