Module page.codeberg.friedolyn.Friedolyn

Package page.codeberg.friedolyn.crypto

Class Cryptor

java.lang.Object

page.codeberg.friedolyn.crypto.Cryptor

public class Cryptor
extends Object

Provides methods for symmetric encryption using the AES algorithm in GCM mode and for deriving encryption keys from human-readable passwords using the Argon2 key derivation function.

See Also:

• encrypt(String, byte[])
• deriveKeyFromPassword(byte[])
• CipherText.decrypt(byte[])

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	Cryptor.KeyDerivationResult	The result of a key derivation operation.

Field Summary

Fields

Modifier and Type	Field	Description
static final @NonNull String	ALGORITHM	The encryption method used by this class: AES in GCM mode without padding.
static final int	ARGON2_ITERATIONS	The default number of iterations to be used by the Argon2 key derivation function: 4.
static final int	ARGON2_LENGTH_BYTES	The default length of the Argon2 hash: 32 bytes = 256 bits.
static final int	ARGON2_MEMORY_KiB	The default memory size (in kibibytes) to be used by the Argon2 key derivation function: 256 MiB.
static final int	ARGON2_PARALLELISM	The default degree of parallelism to be used by the Argon2 key derivation function: 8.
static final @NonNull Pattern	ARGON2_PASSWORD_PATTERN	Matches the PHC string format for Argon2 password hints (i.e.
static final Argon2Variant	ARGON2_VARIANT	The default variant of the Argon2 key derivation function: Argon2Variant.ARGON2_ID.
static final @NonNull Argon2Version	ARGON2_VERSION	The default version of the Argon2 key derivation function: 19 (decimal) = 13 (hex).
static final int	INITIALISATION_VECTOR_BYTES	The AES-GCM specification recommends that the initialisation vector should be 96 bits = 12 bytes long.
static final int	KEY_SIZE_BYTES	The default length of the encryption secret: 32 bytes = 256 bits.
static final int	TAG_LENGTH_BITS	The length of the tag: 128 bits = 16 bytes.

Constructor Summary

Constructors

Constructor	Description
Cryptor()

Method Summary

Modifier and Type	Method	Description
static @NonNull SecretKey	bytesToSecretKey(byte[] key)	Converts an encryption key in the form of a byte array to a SecretKey object.
static @NonNull Cryptor.KeyDerivationResult	deriveKeyFromPassword(byte[] password)	Converts a given human-readable password into a 256-bit key suitable for AES encryption, using the Argon2 key derivation function.
static @NonNull Cryptor.KeyDerivationResult	deriveKeyFromPassword(byte[] password, byte[] salt)	Converts a given human-readable password into a 256-bit key suitable for AES encryption, using the Argon2 key derivation function.
static byte[]	deriveKeyFromPassword(byte[] password, byte[] salt, int iterations, int memory, int length, int parallelism, @NonNull Argon2Version version)	Converts a given human-readable password into a key of the given length, using the Argon2 key derivation function.
static @NonNull CipherText	encrypt(@NonNull String plainText, byte[] password)	Uses the AES encryption algorithm in GCM mode to encrypt a given plaintext with a given password and a randomly generated initialisation vector.
static byte[]	generateRandomBytes(int length)	Securely creates an array of randomly generated bytes.
static @NonNull HashingResult	hash(@NonNull String input)	Hashes the given input using the Argon2 hash function with the default parameters: Argon2 version: Argon2Version.ARGON2_VERSION_19 Memory size: ARGON2_MEMORY_KiB Number of iterations: ARGON2_ITERATIONS KnownDegree of parallelism: ARGON2_PARALLELISM Hash length: KEY_SIZE_BYTES Salt: A randomly generated byte array of length ARGON2_LENGTH_BYTES See RFC 9106 for details.
static @NonNull HashingResult	hash(@NonNull String input, @NonNull Argon2Configuration argon2Configuration)	Hashes the given input using the Argon2 hash function with the parameters specified in the given Argon2Configuration.

Methods inherited from class java.lang.Object

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

Field Details

ALGORITHM

@NonNull
public static final @NonNull String ALGORITHM

The encryption method used by this class: AES in GCM mode without padding.

See Also:

• Constant Field Values

KEY_SIZE_BYTES

public static final int KEY_SIZE_BYTES

The default length of the encryption secret: 32 bytes = 256 bits.

See Also:

• Constant Field Values

TAG_LENGTH_BITS

public static final int TAG_LENGTH_BITS

The length of the tag: 128 bits = 16 bytes.

See Also:

• NIST SP 800-38D
• Constant Field Values

INITIALISATION_VECTOR_BYTES

public static final int INITIALISATION_VECTOR_BYTES

The AES-GCM specification recommends that the initialisation vector should be 96 bits = 12 bytes long.

See Also:

• Constant Field Values

ARGON2_MEMORY_KiB

public static final int ARGON2_MEMORY_KiB

The default memory size (in kibibytes) to be used by the Argon2 key derivation function: 256 MiB.

See Also:

• Constant Field Values

ARGON2_ITERATIONS

public static final int ARGON2_ITERATIONS

The default number of iterations to be used by the Argon2 key derivation function: 4.

See Also:

• Constant Field Values

ARGON2_PARALLELISM

public static final int ARGON2_PARALLELISM

The default degree of parallelism to be used by the Argon2 key derivation function: 8.

See Also:

• Constant Field Values

ARGON2_LENGTH_BYTES

public static final int ARGON2_LENGTH_BYTES

The default length of the Argon2 hash: 32 bytes = 256 bits.

See Also:

• Constant Field Values

ARGON2_VERSION

@NonNull
public static final @NonNull Argon2Version ARGON2_VERSION

The default version of the Argon2 key derivation function: 19 (decimal) = 13 (hex).

ARGON2_VARIANT

public static final Argon2Variant ARGON2_VARIANT

The default variant of the Argon2 key derivation function: Argon2Variant.ARGON2_ID.

ARGON2_PASSWORD_PATTERN

@NonNull
public static final @NonNull Pattern ARGON2_PASSWORD_PATTERN

Matches the PHC string format for Argon2 password hints (i.e. without the password hash, which is used as a key for symmetric encryption).

• Group 1: The Argon2 variant, i.e. "argon2i", "argon2d" or "argon2id".
• Group 2: The version of the algorithm in decimal notation.
• Group 3: The memory size in kibibytes.
• Group 4: The number of iterations.
• Group 5: The degree of parallelism.
• Group 6: The salt as a base64-encoded string.

See Also:

• Argon2Configuration.toArgon2PasswordHint()
• Argon2Configuration.parse(java.lang.String)

Constructor Details

Cryptor

public Cryptor()

Method Details

hash

@NonNull
public static @NonNull HashingResult hash(@NonNull
 @NonNull String input)
                                   throws RuntimeException

Hashes the given input using the Argon2 hash function with the default parameters:

• Argon2 version: Argon2Version.ARGON2_VERSION_19
• Memory size: ARGON2_MEMORY_KiB
• Number of iterations: ARGON2_ITERATIONS
• KnownDegree of parallelism: ARGON2_PARALLELISM
• Hash length: KEY_SIZE_BYTES
• Salt: A randomly generated byte array of length ARGON2_LENGTH_BYTES

See RFC 9106 for details.

Parameters:

input - The text that shall be hashed. Must not be blank.

Returns:

The Argon2 hash of the input text.

invalid reference

HashingResult#getHash()

will be 256 bits in length.

Throws:

RuntimeException - If the input is blank or if the hash unexpectedly fails for unknown reasons.

hash

@NonNull
public static @NonNull HashingResult hash(@NonNull
 @NonNull String input,
 @NonNull
 @NonNull Argon2Configuration argon2Configuration)
                                   throws IllegalArgumentException

Hashes the given input using the Argon2 hash function with the parameters specified in the given Argon2Configuration.

Parameters:

input - The text that shall be hashed. Must not be blank.

argon2Configuration - The parameters that shall be passed to the hash function.

Returns:

The

invalid reference

Argon2 hash

of the input text. Will be 256 bits in length.

Throws:

IllegalArgumentException - If the input is blank or if the Argon2Configuration is invalid.

bytesToSecretKey

@NonNull
public static @NonNull SecretKey bytesToSecretKey(byte[] key)
                                           throws IllegalArgumentException

Converts an encryption key in the form of a byte array to a SecretKey object. Does not check if the key is a valid AES key. Does not modify the key.

Parameters:

key - The encryption secret as a byte array.

Returns:

The encryption secret as a SecretKey object.

Throws:

IllegalArgumentException - If the provided key is not a valid AES key.

encrypt

@NonNull
public static @NonNull CipherText encrypt(@NonNull
 @NonNull String plainText,
 byte[] password)
                                   throws RuntimeException

Uses the AES encryption algorithm in GCM mode to encrypt a given plaintext with a given password and a randomly generated initialisation vector.

Parameters:

plainText - The secret message that shall be encrypted. Must not be blank.

password - The human-readable password that shall be used to derive the encryption key. Must not be empty (but otherwise it is not checked if it is secure enough) and must not be shared with anyone. Recommended: Call PasswordGenerator.estimatePasswordStrength(char[]) to check the strength of the password before using it for encryption. (According to Kerckhoffs' principle, the security of the encryption used must solely rely on the secrecy of the key, meaning that the caller is responsible for providing a secure password.)

Returns:

The encrypted message as a CipherText object. It will be virtually impossible to convert it back to the original message without the correct password.

Throws:

RuntimeException - If the plaintext is blank, the password is empty or the encryption unexpectedly fails for unknown reasons.

generateRandomBytes

public static byte[] generateRandomBytes(int length)

Securely creates an array of randomly generated bytes. Suitable for use as a salt or initialisation vector.

Parameters:

length - How many bytes the array should contain. One byte is eight bits.

Returns:

The randomly generated values. The array returned will be of the length specified.

deriveKeyFromPassword

@NonNull
public static @NonNull Cryptor.KeyDerivationResult deriveKeyFromPassword(byte[] password)
                                                                  throws RuntimeException

Converts a given human-readable password into a 256-bit key suitable for AES encryption, using the Argon2 key derivation function.

Default configuration

See RFC 9106 for details.

• Argon2 version: Argon2Version.ARGON2_VERSION_19
• Memory size: ARGON2_MEMORY_KiB
• Number of iterations: ARGON2_ITERATIONS
• KnownDegree of parallelism: ARGON2_PARALLELISM
• Hash length: KEY_SIZE_BYTES
• Salt: A randomly generated byte array of length ARGON2_LENGTH_BYTES

Parameters:

password - The user-provided encryption secret that shall be converted into a key.

Returns:

A Cryptor.KeyDerivationResult with

• The derived key as a byte array ( for security reasons) of length KEY_SIZE_BYTES.
• The Argon2Configuration with the parameters that were used to derive the key.

Throws:

RuntimeException - If the key derivation unexpectedly fails for unknown reasons.

See Also:

• deriveKeyFromPassword(byte[], byte[])
• deriveKeyFromPassword(byte[], byte[], int, int, int, int, Argon2Version)
• RFC 9106

Implementation Note:

The salt is generated using a cryptographically secure random number generator.

The key derivation function is Argon2 (instead of PBKDF2 or scrypt), because it is the winner of the Password Hashing Competition and is considered the state-of-the-art key derivation function.

deriveKeyFromPassword

@NonNull
public static @NonNull Cryptor.KeyDerivationResult deriveKeyFromPassword(byte[] password,
 byte[] salt)
                                                                  throws RuntimeException

Converts a given human-readable password into a 256-bit key suitable for AES encryption, using the Argon2 key derivation function.

Default configuration

See RFC 9106 for details.

• Argon2 version: Argon2Version.ARGON2_VERSION_19
• Memory size: ARGON2_MEMORY_KiB
• Number of iterations: ARGON2_ITERATIONS
• KnownDegree of parallelism: ARGON2_PARALLELISM
• Hash length: KEY_SIZE_BYTES

Parameters:

password - The user-provided encryption secret that shall be converted into a key.

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 be a number of bytes from 4 to 2^(32)-1.

Returns:

A Cryptor.KeyDerivationResult with

• the derived key as a byte array (for security reasons) of length KEY_SIZE_BYTES.
• the Cryptor.KeyDerivationResult.argon2Configuration() with the parameters that were used to derive the key.

Throws:

RuntimeException - If the salt is invalid or if the key derivation unexpectedly fails for unknown reasons.

See Also:

• deriveKeyFromPassword(byte[], byte[], int, int, int, int, Argon2Version)
• deriveKeyFromPassword(byte[])
• RFC 9106

Implementation Note:

The key derivation function is Argon2 (instead of PBKDF2 or scrypt), because it is the winner of the Password Hashing Competition and is considered the state-of-the-art key derivation function.

deriveKeyFromPassword

public static byte[] deriveKeyFromPassword(byte[] password,
 byte[] salt,
 int iterations,
 int memory,
 int length,
 int parallelism,
 @NonNull
 @NonNull Argon2Version version)
                                    throws IllegalArgumentException

Converts a given human-readable password into a key of the given length, using the Argon2 key derivation function.

Parameters:

password - The user-provided encryption secret that shall be converted into a key.

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.

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

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

length - The output size of the derived key. MUST be between 4 and 2^(32)-1.

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

version - The Argon2 revision to use. Strongly recommended: Argon2Version.ARGON2_VERSION_19.

Returns:

The derived key as a byte array of the given length.

Throws:

IllegalArgumentException - If any of the parameters does not meet the requirements.

See Also:

• deriveKeyFromPassword(byte[])
• deriveKeyFromPassword(byte[], byte[])
• RFC 9106

Implementation Note:

The key derivation function is Argon2 (instead of PBKDF2 or scrypt), because it is the winner of the Password Hashing Competition and is considered the state-of-the-art key derivation function.