Class CipherText

java.lang.Object

de.gustavblass.commons.crypto.CipherText

All Implemented Interfaces:

de.gustavblass.commons.Copyable<CipherText>

public class CipherText
extends Object
implements de.gustavblass.commons.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(byte[], byte[], de.gustavblass.commons.crypto.Argon2Configuration) 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 @NonNull []	cipherText	The secret message after it has been encrypted.
private final byte @NonNull []	initialisationVector	The initialisation vector (nonce) that was passed to the AES in Galois/Counter Mode.
private static final org.apache.logging.log4j.Logger	LOG

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
@NonNull CipherText	copy()
@NonNull String	decrypt(byte @NonNull [] 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(@Nullable 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

LOG

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

cipherText

private final byte @NonNull [] cipherText

The secret message after it has been encrypted.

initialisationVector

private final byte @NonNull [] 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 @NonNull [] cipherText,
 byte @NonNull [] initialisationVector,
 @NonNull
 @NonNull Argon2Configuration argon2Configuration)
           throws de.gustavblass.commons.exceptions.IllegalArgumentException

Constructs a new CipherText object with the provided message, initialisationVector 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:

de.gustavblass.commons.exceptions.IllegalArgumentException - If the provided message or initialisationVector is null or empty.

See Also:

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

Method Details

decrypt

@NonNull
public @NonNull String decrypt(byte @NonNull [] password)
                        throws AEADBadTagException,
de.gustavblass.commons.exceptions.IllegalStateException,
org.bouncycastle.crypto.CryptoException

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 as the ones that were used to encrypt the message.

Returns:

The human-readable message that was previously encrypted.

Throws:

AEADBadTagException - If the provided password is not the one that was used to encrypt the message or if the message has been tampered with. (Those two cases are indistinguishable by construction.)

de.gustavblass.commons.exceptions.IllegalStateException - If the encryption key could not be derived from the provided password with the current Argon2 parameters.

org.bouncycastle.crypto.CryptoException - If the provided password is not a valid AES password 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 initialisationVector.
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 initialisationVector.
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()
                         throws IllegalStateException

Specified by:

copy in interface de.gustavblass.commons.Copyable<CipherText>

Throws:

IllegalStateException - If the fields of this CipherText 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 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:

1. 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.
2. 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 de.gustavblass.commons.exceptions.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 initialisationVector.
7. [ciphertext] is the base64-encoded encrypted message.

Returns:

The CipherText object that was represented by the provided string.

Throws:

de.gustavblass.commons.exceptions.IllegalArgumentException - If the provided string is not a valid CipherText string representation or if the [configuration][Argon2Configuration Argon2] cannot be parsed.

See Also:

• toString()
• Argon2Configuration.parse(String)

fromBase64

@NonNull
public static @NonNull CipherText fromBase64(@NonNull
 @NonNull String base64)
                                      throws de.gustavblass.commons.exceptions.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:

de.gustavblass.commons.exceptions.IllegalArgumentException - If the provided string is not a valid CipherText string representation or if the [configuration][Argon2Configuration Argon2] cannot be parsed.

See Also:

• toBase64()
• parse(String)