Class Cryptor

java.lang.Object
de.gustavblass.commons.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. Currently only suitable to encrypt raw text messages and not large binary data (such as files).
See Also:

  • Field Details

  • Constructor Details

    • Cryptor

      public Cryptor()

  • Method Details

    • hash

      @NonNull public static @NonNull HashingResult hash(byte @NonNull [] input) throws de.gustavblass.commons.exceptions.IllegalArgumentException

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

      See RFC 9106 for details.

      Parameters:
      input - The text that shall be hashed. Must not be empty.
      Returns:

      The Argon2 hash of the input text.

      invalid reference 
      HashingResult#getHash()
      will be

      256 bits in length.

      Throws:
      de.gustavblass.commons.exceptions.IllegalArgumentException - If the input is empty.

    • hash

      @NonNull public static @NonNull HashingResult hash(byte @NonNull [] input, @NonNull @NonNull Argon2Configuration argon2Configuration) throws de.gustavblass.commons.exceptions.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 [HashingResult#getHash() Argon2 hash] of the input text. Will be 256 bits in length.
      Throws:
      de.gustavblass.commons.exceptions.IllegalArgumentException - If the input is blank or if the Argon2Configuration is invalid.

    • bytesToSecretKey

      @NonNull public static @NonNull SecretKey bytesToSecretKey(byte @NonNull [] key) throws de.gustavblass.commons.exceptions.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:
      de.gustavblass.commons.exceptions.IllegalArgumentException - If the provided key is not a valid AES key.

    • encrypt

      @NonNull public static @NonNull CipherText encrypt(@NonNull @NonNull String plainText, byte @NonNull [] password) throws de.gustavblass.commons.exceptions.IllegalArgumentException, org.bouncycastle.openssl.EncryptionException
      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:
      de.gustavblass.commons.exceptions.IllegalArgumentException -

      If:

      • The plaintext is blank.
      • The password is empty.
      • No valid AES key could be derived from the password.
      • The cipher could not be initialised.
      org.bouncycastle.openssl.EncryptionException - In case of any error conditions thought impossible (should never happen).

    • 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 @NonNull [] password) throws de.gustavblass.commons.exceptions.IllegalArgumentException

      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.

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

      A Cryptor.KeyDerivationResult with

      Throws:
      de.gustavblass.commons.exceptions.IllegalArgumentException - If no valid salt could be generated (should never happen).
      See Also:
      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 @NonNull [] password, byte @NonNull [] salt) throws de.gustavblass.commons.exceptions.IllegalArgumentException

      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.

      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

      Throws:
      de.gustavblass.commons.exceptions.IllegalArgumentException - If the salt is not of a valid length (see Argon2Configuration.setSalt(byte[])
      See Also:
      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

      @NonNull public static @NonNull Cryptor.KeyDerivationResult deriveKeyFromPassword(byte @NonNull [] password, Argon2Configuration argon2Configuration, int length) throws de.gustavblass.commons.exceptions.IllegalArgumentException

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

      See RFC 9106.

      Parameters:
      password - The user-provided encryption secret that shall be converted into a key.
      argon2Configuration - The Argon2 parameters that shall be used to derive the key.
      length - The output size of the derived key. MUST be between 4 and 2^(32)-1.
      Returns:
      The derived key as a byte array of the given length.
      Throws:
      de.gustavblass.commons.exceptions.IllegalArgumentException - If any of the parameters does not meet the requirements.
      See Also:
      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.