Class Argon2Configuration

java.lang.Object
de.gustavblass.commons.crypto.Argon2Configuration
All Implemented Interfaces:
de.gustavblass.commons.Copyable<Argon2Configuration>
public class Argon2Configuration extends Object implements de.gustavblass.commons.Copyable<Argon2Configuration>
The configuration of the Argon2 key derivation function. See RFC 9106.

  • Field Details

    • LOG

      private static final org.apache.logging.log4j.Logger LOG

    • ARGON2ID_BASE64

      private static final String ARGON2ID_BASE64
      The string argon2id in Base64 encoding.
      See Also:

    • MINIMUM_PARALLELISM_FACTOR_FOR_MEMORY

      public static final long MINIMUM_PARALLELISM_FACTOR_FOR_MEMORY
      The Argon2 specification requires that m >= 8 * p, where m is the memory size in kibibytes and p is the degree of parallelism.
      See Also:

    • MAXIMUM_PARALLELISM

      public static final double MAXIMUM_PARALLELISM

    • 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() throws de.gustavblass.commons.exceptions.IllegalStateException
      Creates a new Argon2 configuration with the default parameters and a randomly generated salt of 32 bytes length.
      Throws:
      de.gustavblass.commons.exceptions.IllegalStateException - If no valid salt could be generated (should never happen).

    • Argon2Configuration

      public Argon2Configuration(byte @NonNull [] salt) throws de.gustavblass.commons.exceptions.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:
      de.gustavblass.commons.exceptions.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 @NonNull [] salt) throws de.gustavblass.commons.exceptions.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:
      de.gustavblass.commons.exceptions.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 de.gustavblass.commons.exceptions.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:
      de.gustavblass.commons.exceptions.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 de.gustavblass.commons.exceptions.IllegalArgumentException
      Updates the number of iterations of this configuration.
      Parameters:
      iterations - The new number of iterations. MUST be greater than 0.
      Throws:
      de.gustavblass.commons.exceptions.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 de.gustavblass.commons.exceptions.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:
      de.gustavblass.commons.exceptions.IllegalArgumentException - If the parallelism is not positive or too large.

    • setSalt

      public void setSalt(byte @NonNull [] salt) throws de.gustavblass.commons.exceptions.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:
      de.gustavblass.commons.exceptions.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 de.gustavblass.commons.exceptions.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 created 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:
      de.gustavblass.commons.exceptions.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 de.gustavblass.commons.exceptions.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:
      de.gustavblass.commons.exceptions.IllegalArgumentException - If the provided string is formatted incorrectly or if any of the parameters are invalid.

    • copy

      @NonNull public @NonNull Argon2Configuration copy() throws IllegalStateException
      Specified by:
      copy in interface de.gustavblass.commons.Copyable<Argon2Configuration>
      Returns:
      A deep copy of this Argon2Configuration object, with the exact same values, but a different reference.
      Throws:
      IllegalStateException - If the current values of this Argon2Configuration's fields are considered invalid by the constructor.
      Implementation Note:
      Throws an unchecked IllegalStateException instead of a checked one because Copyable.copy() does not throw checked exceptions.

    • equals

      public boolean equals(@Nullable @Nullable Object object)
      Compares all fields of this Argon2Configuration to the fields of another one (if it is an Argon2Configuration at all).
      Overrides:
      equals in class Object
      Parameters:
      object - A different Argon2Configuration that shall be compared to this one.
      Returns:
      True if all fields are identical, false otherwise.