Module page.codeberg.friedolyn.Friedolyn

Package page.codeberg.friedolyn.crypto

Class CipherText

java.lang.Object

page.codeberg.friedolyn.crypto.CipherText

All Implemented Interfaces:

Copyable<CipherText>

public class CipherText
extends Object
implements Copyable<CipherText>

Represents a secret message that has been encrypted using the AES algorithm in Galois/Counter Mode (GCM). The message can be decrypted again using the same human-readable password that was used to encrypt it. Of course, that password is not stored in the CipherText object but must be provided by the caller.

Implementation Note:

This class is not a record, because the constructor needs to check that the provided cipher text and initialisation vector are not null or empty and throw an IllegalArgumentException if that's the case. While that could be done in a record as well, we cannot add throws IllegalArgumentException to the record's constructor signature, risking that callers of the constructor will not handle the exception. JavaDoc is not a sufficient replacement here!

Field Summary

Fields

Modifier and Type	Field	Description
private final @NonNull Argon2Configuration	argon2Configuration	The Argon2 parameters that were used to derive the AES encryption key from the user's human-readable password.
private final byte[]	cipherText	The secret message after it has been encrypted.
private final byte[]	initialisationVector	The initialisation vector (nonce) that was passed to the AES in Galois/Counter Mode.

Constructor Summary

Constructors

Constructor	Description
CipherText(byte[] cipherText, byte[] initialisationVector, @NonNull Argon2Configuration argon2Configuration)	Constructs a new CipherText object with the provided message, initialisation vector and Argon2 parameters.

Method Summary

Modifier and Type	Method	Description
@NonNull CipherText	copy()
@NonNull String	decrypt(byte[] password)	Converts the secret message from its encrypted form back to its human-readable form, using the AES algorithm in Galois/Counter Mode (GCM).
boolean	equals(@NonNull Object object)	Compares the field's values of this CipherText object to those of another object.
static @NonNull CipherText	fromBase64(@NonNull String base64)
static @NonNull CipherText	parse(@NonNull String cipherText)	Converts a string representation of a CipherText object back to a CipherText object.
@NonNull String	toBase64()	Converts the secret message to a string representation that contains all the information necessary to convert it back to a CipherText object and decrypt the message again.
@NonNull String	toString()	Converts the secret message to a string representation that contains all the information necessary to convert it back to a CipherText object and decrypt the message again.

Methods inherited from class java.lang.Object

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

Field Details

cipherText

private final byte[] cipherText

The secret message after it has been encrypted.

initialisationVector

private final byte[] initialisationVector

The initialisation vector (nonce) that was passed to the AES in Galois/Counter Mode.

argon2Configuration

@NonNull
private final @NonNull Argon2Configuration argon2Configuration

The Argon2 parameters that were used to derive the AES encryption key from the user's human-readable password.

Constructor Details

CipherText

public CipherText(byte[] cipherText,
 byte[] initialisationVector,
 @NonNull
 @NonNull Argon2Configuration argon2Configuration)
           throws IllegalArgumentException

Constructs a new CipherText object with the provided message, initialisation vector and Argon2 parameters.

Parameters:

cipherText - The secret message after it has been encrypted.

initialisationVector - The initialisation vector (nonce) that was passed to the AES in Galois/Counter Mode.

argon2Configuration - The Argon2 parameters that were used to derive the AES encryption key from the user's human-readable password.

Throws:

IllegalArgumentException - If the provided message or initialisation vector is null or empty.

See Also:

• Cryptor.encrypt(String, byte[])
• decrypt(byte[])

Method Details

decrypt

@NonNull
public @NonNull String decrypt(byte[] password)
                        throws RuntimeException

Converts the secret message from its encrypted form back to its human-readable form, using the AES algorithm in Galois/Counter Mode (GCM).

Parameters:

password - The human-readable password that the user entered to encrypt the message. Will be used to derive the actual encryption key using the Argon2 algorithm with the exact same parameters that were used to encrypt the message.

Returns:

The human-readable message that was previously encrypted.

Throws:

RuntimeException - If the provided password is not a valid AES password, if the provided password does not match the password that was used to encrypt the message or if an unexpected error occurs during the decryption process.

toString

@NonNull
public @NonNull String toString()

Converts the secret message to a string representation that contains all the information necessary to convert it back to a CipherText object and decrypt the message again. The string representation is in the format $argon2id$v=[version]$m=[memory],t=[iterations],p=[parallelism]$[salt]$[iv]$[ciphertext] where

1. [version] is Argon2Version.version
2. [memory] is
   invalid reference

   Argon2Configuration#getMemory()

3. [iterations] is
   invalid reference

   Argon2Configuration#getIterations()

4. [parallelism] is
   invalid reference

   Argon2Configuration#getParallelism()

5. [salt] is the base64-encoded
   invalid reference

   salt

   .
6. [iv] is the base64-encoded initialisation vector.
7. [ciphertext] is the base64-encoded encrypted message.

Overrides:

toString in class Object

Returns:

The cipher text as a string with all necessary information to decrypt it again.

See Also:

• parse(String)
• decrypt(byte[])

toBase64

@NonNull
public @NonNull String toBase64()

Converts the secret message to a string representation that contains all the information necessary to convert it back to a CipherText object and decrypt the message again. The string representation is in the format $base64$base64$base64$base64$[iv]$[ciphertext] where

1. The string argon2id in Base64
2. v=[version] where [version] is Argon2Version.version
3. m=[memory],t=[iterations],p=[parallelism] with
   invalid reference

   Argon2Configuration#getMemory()

   ,
   invalid reference

   Argon2Configuration#getIterations()

   and
   invalid reference

   Argon2Configuration#getParallelism()

4. [salt] is the base64-encoded
   invalid reference

   salt

   .
5. [iv] is the base64-encoded initialisation vector.
6. [ciphertext] is the base64-encoded encrypted message.

Returns:

The cipher text as a string with all necessary information to decrypt it again.

See Also:

• parse(String)
• decrypt(byte[])

copy

@NonNull
public @NonNull CipherText copy()

Specified by:

copy in interface Copyable<CipherText>

Returns:

A deep copy of the object, i.e. a clone that has the exact same values as the original object, but is a different instance (new reference).

equals

public boolean equals(@NonNull
 @NonNull Object object)

Compares the field's values of this CipherText object to those of another object.

Overrides:

equals in class Object

Parameters:

object - The object to compare this CipherText object to.

Returns:

• true if the provided object is a CipherText object and all fields of the given CipherText object match those of this CipherText object, especially (but not exclusively) if both objects are the same reference.
• false if the provided object is not a CipherText object or if any field of the given CipherText object does not match the corresponding field of this CipherText.

parse

@NonNull
public static @NonNull CipherText parse(@NonNull
 @NonNull String cipherText)
                                 throws IllegalArgumentException

Converts a string representation of a CipherText object back to a CipherText object.

Parameters:

cipherText - The string representation of a CipherText object, as returned by toString(), i.e. in the format $argon2id$v=[version]$m=[memory],t=[iterations],p=[parallelism]$[salt]$[iv]$[ciphertext] where

1. [version] is Argon2Version.version
2. [memory] is
   invalid reference

   Argon2Configuration#getMemory()

3. [iterations] is
   invalid reference

   Argon2Configuration#getIterations()

4. [parallelism] is
   invalid reference

   Argon2Configuration#getParallelism()

5. [salt] is the base64-encoded
   invalid reference

   salt

   .
6. [iv] is the base64-encoded initialisation vector.
7. [ciphertext] is the base64-encoded encrypted message.

Returns:

The CipherText object that was represented by the provided string.

Throws:

IllegalArgumentException - If the provided string is not a valid CipherText string representation or if the Argon2 configuration cannot be parsed.

See Also:

• toString()
• Argon2Configuration.parse(String)

fromBase64

@NonNull
public static @NonNull CipherText fromBase64(@NonNull
 @NonNull String base64)
                                      throws IllegalArgumentException

Parameters:

base64 - The string representation of a CipherText object, as returned by toBase64(), i.e. in the format $base64$base64$base64$base64$[iv]$[ciphertext] where

1. The string argon2id in Base64
2. v=[version] where [version] is Argon2Version.version
3. m=[memory],t=[iterations],p=[parallelism] with
   invalid reference

   Argon2Configuration#getMemory()

   ,
   invalid reference

   Argon2Configuration#getIterations()

   and
   invalid reference

   Argon2Configuration#getParallelism()

4. [salt] is the base64-encoded
   invalid reference

   salt

   .
5. [iv] is the base64-encoded initialisation vector.
6. [ciphertext] is the base64-encoded encrypted message.

Returns:

The CipherText object that was represented by the provided string.

Throws:

IllegalArgumentException - If the provided string is not a valid CipherText string representation or if the Argon2 configuration cannot be parsed.

See Also:

• toBase64()
• parse(String)