Module page.codeberg.friedolyn.Friedolyn

Package page.codeberg.friedolyn.crypto

Class Argon2Configuration

java.lang.Object

page.codeberg.friedolyn.crypto.Argon2Configuration

All Implemented Interfaces:

Copyable<Argon2Configuration>

public class Argon2Configuration
extends Object
implements Copyable<Argon2Configuration>

The configuration of the Argon2 key derivation function.

See Also:

• RFC 9106

Field Summary

Fields

Modifier and Type	Field	Description
private static final String	ARGON2ID_BASE64	The string argon2id in Base64 encoding.
private int	iterations	Number of passes (used to tune the running time independently of the memory size).
private int	memory	The memory size m MUST be a number of kibibytes from 8*p to 2^(32)-1.
private int	parallelism	KnownDegree of parallelism p determines how many independent (but synchronising) computational chains (lanes) can be run.
private byte[]	salt	The nonce (number used once) that must be unique for each key.
private @NonNull Argon2Variant	variant	The variant of the Argon2 key derivation function that shall be used.
private @NonNull Argon2Version	version	The revision of the Argon2 key derivation function.

Constructor Summary

Constructors

Constructor	Description
Argon2Configuration()	Creates a new Argon2 configuration with the default parameters and a randomly generated salt of 32 bytes length.
Argon2Configuration(byte[] salt)	Creates a new Argon2 configuration with the default parameters and the provided salt.
Argon2Configuration(@NonNull Argon2Variant variant, @NonNull Argon2Version version, int memory, int iterations, int parallelism, byte[] salt)	Constructs a new Argon2 configuration with the specified parameters.

Method Summary

Modifier and Type	Method	Description
@NonNull Argon2Configuration	copy()
boolean	equals(@NonNull Argon2Configuration other)	Compares all fields of this Argon2Configuration to the fields of another Argon2Configuration.
static @NonNull Argon2Configuration	fromBase64(@NonNull String hint)	Converts a Base64-encoded string representation of an Argon2Configuration back to an Argon2Configuration object.
static @NonNull Argon2Configuration	parse(@NonNull String hint)	Converts an Argon2 password hint back to an Argon2Configuration.
void	setIterations(int iterations)	Updates the number of iterations of this configuration.
void	setMemory(int memory)	Updates the memory size m of this configuration.
void	setParallelism(int parallelism)	Updates the degree of parallelism p of this configuration.
void	setSalt(byte[] salt)	Updates the salt of this configuration.
void	setVariant(@NonNull Argon2Variant variant)	Updates the variant of the Argon2 key derivation function that shall be used.
void	setVersion(@NonNull Argon2Version version)	Updates the version of the Argon2 key derivation function that shall be used.
@NonNull String	toArgon2PasswordHint()	Converts this configuration to a PHC string, but without the password hash, i.e.
@NonNull String	toBase64()	Converts this configuration to the format $base64$base64$base64$base64 where the four Base64 strings are: The string argon2id v=[version] where [version] is Argon2Version.version m=[memory],t=[iterations],p=[parallelism] with memory, iterations and parallelism The Base64-encoded salt The resulting string can be converted back to an Argon2Configuration using parse(String).
@NonNull String	toString()	Alias for toArgon2PasswordHint().

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

ARGON2ID_BASE64

private static final String ARGON2ID_BASE64

The string argon2id in Base64 encoding.

See Also:

• Constant Field Values

variant

@NonNull
private @NonNull Argon2Variant variant

The variant of the Argon2 key derivation function that shall be used.

version

@NonNull
private @NonNull Argon2Version version

The revision of the Argon2 key derivation function.

memory

private int memory

The memory size m MUST be a number of kibibytes from 8*p to 2^(32)-1.

iterations

private int iterations

Number of passes (used to tune the running time independently of the memory size). MUST be between 1 and 2^(32) - 1.

parallelism

private int parallelism

KnownDegree of parallelism p determines how many independent (but synchronising) computational chains (lanes) can be run. It MUST be a value from 1 to 2^(24)-1.

salt

private byte[] salt

The nonce (number used once) that must be unique for each key. Use the same salt during decryption that was used during encryption, but never re-use a salt for different keys.

MUST NOT be longer than 2^(32)-1 and SHOULD be 32 bytes long.

Constructor Details

Argon2Configuration

public Argon2Configuration()

Creates a new Argon2 configuration with the default parameters and a randomly generated salt of 32 bytes length.

Argon2Configuration

public Argon2Configuration(byte[] salt)
                    throws IllegalArgumentException

Creates a new Argon2 configuration with the default parameters and the provided salt.

Parameters:

salt - The salt for this configuration. MUST NOT be null or empty. SHOULD be 32 bytes long. You will NOT be warned if your salt is insecurely short or if it is “predictable”.

Throws:

IllegalArgumentException - If the salt is null or empty.

Argon2Configuration

public Argon2Configuration(@NonNull
 @NonNull Argon2Variant variant,
 @NonNull
 @NonNull Argon2Version version,
 int memory,
 int iterations,
 int parallelism,
 byte[] salt)
                    throws IllegalArgumentException

Constructs a new Argon2 configuration with the specified parameters.

Parameters:

variant - The variant of the Argon2 key derivation function that shall be used. Strongly recommended: Argon2Variant.ARGON2_ID.

version - The revision of the Argon2 key derivation function that shall be used. Strongly recommended: Argon2Version.ARGON2_VERSION_19.

memory - memory size (m) – in kibibytes – to be used by the Argon2 key derivation function. Must be a value from 8*p to 2^(32)-1. See also Cryptor.ARGON2_MEMORY_KiB.

iterations - number of passes (i) to be used by the Argon2 key derivation function (used to tune the running time independently of the memory size). MUST be between 1 and 2^(32) - 1. See also Cryptor.ARGON2_ITERATIONS.

parallelism - The degree of parallelism (p) to be used by the Argon2 key derivation function. MUST be a value from 1 to 2^(24)-1. See also Cryptor.ARGON2_PARALLELISM.

salt - The nonce (number used once) that must be unique for each key. Use the same salt during decryption that was used during encryption, but never re-use a salt for different keys. MUST NOT be longer than 2^(32)-1 and SHOULD be 32 bytes long. You will NOT be warned if your salt is insecurely short or if it is “predictable”.

Throws:

IllegalArgumentException - If:

• the number of iterations is not positive or too large.
• the degree of parallelism is not positive or too large.
• the memory size is too small, too large or not positive.
• the salt is null or empty.

Method Details

setVariant

public void setVariant(@NonNull
 @NonNull Argon2Variant variant)

Updates the variant of the Argon2 key derivation function that shall be used.

Parameters:

variant - The new Argon2 variant.

setVersion

public void setVersion(@NonNull
 @NonNull Argon2Version version)

Updates the version of the Argon2 key derivation function that shall be used.

Parameters:

version - The new Argon2 version.

setMemory

public void setMemory(int memory)
               throws IllegalArgumentException

Updates the memory size m of this configuration.

Parameters:

memory - The new memory size m in kibibytes. MUST be greater than 8*p.

Throws:

IllegalArgumentException - If the memory size is too small, too large or not positive.

Implementation Note:

We do not need to check whether the memory is larger than the absolute limit, because Integer.MAX_VALUE is less than 2^32 - 1 (the Argon2 limit).

setIterations

public void setIterations(int iterations)
                   throws IllegalArgumentException

Updates the number of iterations of this configuration.

Parameters:

iterations - The new number of iterations. MUST be greater than 0.

Throws:

IllegalArgumentException - If the number of iterations is not positive or too large.

Implementation Note:

We do not need to check whether the number of iterations is too large, because Integer.MAX_VALUE is less than 2^32 - 1 (the Argon2 limit).

setParallelism

public void setParallelism(int parallelism)
                    throws IllegalArgumentException

Updates the degree of parallelism p of this configuration.

Parameters:

parallelism - The new degree of parallelism p. MUST be a value from 1 to 2^(24) - 1.

Throws:

IllegalArgumentException - If the parallelism is not positive or too large.

setSalt

public void setSalt(byte[] salt)
             throws IllegalArgumentException

Updates the salt of this configuration.

Parameters:

salt - The new salt for this configuration. MUST NOT be null or empty. SHOULD be 32 bytes long. You will NOT be warned if your salt is insecurely short or if it is “predictable”.

Throws:

IllegalArgumentException - If the salt is null or empty.

Implementation Note:

We do not need to check whether the salt is too large, because the maximum array length is 2^31 - 1 (per Arrays.copyOf(byte[], int)), which is less than 2^32 - 1 (the Argon2 limit).

toArgon2PasswordHint

@NonNull
public @NonNull String toArgon2PasswordHint()

Converts this configuration to a PHC string, but without the password hash, i.e. in the format $argon2id$v=[version]$m=[memory],t=[iterations],p=[parallelism]$[salt] where

1. [version] is Argon2Version.version
2. [memory] is memory
3. [iterations] is iterations
4. [parallelism] is parallelism
5. [salt] is the base64-encoded salt

This is useful when you want to use Argon2 for deriving a key for symmetric encryption, because when trying to decrypt the ciphertext later on, you will need to use the exact same Argon2 configuration.

Important: None of the parameters included in the returned password hint are secret, so they can safely be appended to the ciphertext. (According to Kerckhoffs' principle, the security of the encryption used must solely rely on the secrecy of the key.)

Returns:

This configuration as a PHC string.

toString

@NonNull
public @NonNull String toString()

Alias for toArgon2PasswordHint().

Overrides:

toString in class Object

Returns:

This configuration as a PHC string, but without the hash itself.

toBase64

@NonNull
public @NonNull String toBase64()

Converts this configuration to the format $base64$base64$base64$base64 where the four Base64 strings are:

1. The string argon2id
2. v=[version] where [version] is Argon2Version.version
3. m=[memory],t=[iterations],p=[parallelism] with memory, iterations and parallelism
4. The Base64-encoded salt

The resulting string can be converted back to an Argon2Configuration using parse(String).

Returns:

The parameters of this configuration in Base64, separated by $ characters.

parse

@NonNull
public static @NonNull Argon2Configuration parse(@NonNull
 @NonNull String hint)
                                          throws IllegalArgumentException

Converts an Argon2 password hint back to an Argon2Configuration.

Parameters:

hint - Must match the format $argon2id$v=[version]$m=[memory],t=[iterations],p=[parallelism]$[salt]. Usually reated by toArgon2PasswordHint(). Refer to Argon2Configuration for more information on the values that are allowed.

Returns:

A new Argon2Configuration with the parameters from the hint.

Throws:

IllegalArgumentException - If the hint does not match the pattern or if any of the parameters are invalid.

fromBase64

@NonNull
public static @NonNull Argon2Configuration fromBase64(@NonNull
 @NonNull String hint)
                                               throws IllegalArgumentException

Converts a Base64-encoded string representation of an Argon2Configuration back to an Argon2Configuration object.

Parameters:

hint - The Base64-encoded string representation of an Argon2Configuration object, as returned by toBase64(). Must contain four parts, separated by $ characters:

1. argon2id for Argon2Variant.ARGON2_ID, argon2d for Argon2Variant.ARGON2_D or argon2i for Argon2Variant.ARGON2_I
2. v=[version] where [version] is Argon2Version.version
3. m=[memory],t=[iterations],p=[parallelism] with memory, iterations and parallelism
4. The Base64-encoded salt

Returns:

The Argon2Configuration object that was represented by the provided string.

Throws:

IllegalArgumentException - If the provided string is formatted incorrectly or if any of the parameters are invalid.

copy

@NonNull
public @NonNull Argon2Configuration copy()

Specified by:

copy in interface Copyable<Argon2Configuration>

Returns:

A deep copy of this Argon2Configuration object, with the exact same values, but a different reference.

equals

public boolean equals(@NonNull
 @NonNull Argon2Configuration other)

Compares all fields of this Argon2Configuration to the fields of another Argon2Configuration.

Parameters:

other - A different Argon2Configuration that shall be compared to this one.

Returns:

True if all fields are identical, false otherwise.