Class Cryptor

java.lang.Object
org.tentackle.common.Cryptor
All Implemented Interfaces:
Function<String,String>
public class Cryptor extends Object implements Function<String,String>
A simple en- and decryptor.
Each application should provide a concrete subclass with a confidential salt and passphrase and a no-arg constructor. If provided, it is used to encrypt passwords in memory and during transmission at client/server login, or to decrypt passwords stored in backend.properties for database connections.
Example: 
   @Service(Cryptor.class)
   public class MyCryptor extends Cryptor {

     public MyCryptor() {
       super(SALT, PASSPHRASE);   // whatever
     }
   }
Notice that if the constructor of the application's cryptor throws a TentackleRuntimeException, getInstance() silently returns null, as if no cryptor were configured.

Texts, salts, and passphrases are converted to bytes via Settings.getEncodingCharset().

Cryptor also implements a Function<String,String> to encrypt strings like passwords to base64 and thus can directly be used by the tentackle-maven-plugin to generate properties for filtered resources.

Notice: the security of symmetric encryption algorithms in general depends on the confidentiality of the passphrase. Thus, the passphrase should ideally not be part of the application, but provided via some external media, a mounted USB-stick, manual input, PGP keyring, whatever. However, in practice this isn't always doable.

Cryptors are thread-safe. Since Cipher is stateful and not thread-safe, each thread gets its own cipher, created lazily via getCipher() (or, for Cryptor(SecretKey, Cipher), from the given template cipher). This is essential because the cryptor is usually a singleton shared by all threads, for example, by the encrypted transports of a server.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Cryptor(byte[] salt, char[] passphrase)
    Creates a cryptor with 1024 iterations and a key strength of 256.
    Notice that salt and passphrase will be scratched for security reasons.
    Cryptor(byte[] salt, char[] passphrase, int iterations, int keyStrength)
    Creates a cryptor.
    Notice that salt and passphrase will be scratched for security reasons.
    Cryptor(String salt, String passphrase)
    Creates a cryptor with 1024 iterations and a key strength of 256.
    This is just a convenience constructor.
    Cryptor(SecretKey key, Cipher cipher)
    Creates a cryptor.
    Notice that the given cipher serves as the template for the per-thread ciphers, i.e., its algorithm and provider are used to create them.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    apply(String s)
    Encrypts a string.
    Provided for the tentackle-maven-plugin.
    protected SecretKeySpec
    createSecretKeySpec(byte[] key)
    Creates the key spec.
    The default implementation returns an AES spec.
    byte[]
    decrypt(byte[] encryptedData)
    Decrypts the data.
    byte[]
    decrypt(byte[] encryptedData, int offset, int length)
    Decrypts the data.
    String
    decrypt64(String encryptedText)
    Decrypts a base64 encoded string.
    byte[]
    decrypt64ToBytes(String encryptedText)
    Decrypts a base64 encoded string.
    char[]
    decrypt64ToChars(String encryptedText)
    Decrypts a base64 encoded string.
    The method clears all traces in memory.
    char[]
    decryptToChars(byte[] encryptedData)
    Decrypts encrypted data to chars.
    String
    deriveURL(String url, String... protocols)
    Derives the unencrypted URL.
    The URL is considered to be encrypted if started with a fake protocol unsupported by the application in the given context.
    byte[]
    encrypt(byte[] data)
    Encrypts the data.
    byte[]
    encrypt(byte[] data, int offset, int length)
    Encrypts the data.
    byte[]
    encrypt(char[] chars)
    Encrypts a char array.
    The method clears all traces in memory, including the passed char array.
    String
    encrypt64(byte[] data)
    Encrypts data to base64 encoding.
    String
    encrypt64(char[] chars)
    Encrypts a char array to base64 encoding.
    The method clears all traces in memory, including the passed char array.
    String
    encrypt64(String text)
    Encrypts a string to base64 encoding.
    protected Cipher
    getCipher()
    Creates a cipher instance.
    The default implementation returns an AES cipher.
    static Cryptor
    getInstance()
    Gets the optional application-specific cryptor singleton.
    static Cryptor
    getInstanceSafely()
    Gets the application-specific cryptor singleton.
    protected SecretKeyFactory
    getSecretKeyFactory()
    Gets the key factory.
    The default implementation returns an instance of PBKDF2WithHmacSHA1.

    Methods inherited from class Object

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

    Methods inherited from interface Function

    andThen, compose

  • Constructor Details

    • Cryptor

      public Cryptor(SecretKey key, Cipher cipher)
      Creates a cryptor.
      Notice that the given cipher serves as the template for the per-thread ciphers, i.e., its algorithm and provider are used to create them. getCipher() is not used.
      Parameters:
      key - the secret key
      cipher - the cipher

    • Cryptor

      public Cryptor(byte[] salt, char[] passphrase, int iterations, int keyStrength)
      Creates a cryptor.
      Notice that salt and passphrase will be scratched for security reasons.
      Parameters:
      salt - the salt
      passphrase - the passphrase
      iterations - number of iterations for key generation
      keyStrength - the key strength
      Throws:
      TentackleRuntimeException - if the key could not be generated

    • Cryptor

      public Cryptor(byte[] salt, char[] passphrase)
      Creates a cryptor with 1024 iterations and a key strength of 256.
      Notice that salt and passphrase will be scratched for security reasons.
      Parameters:
      salt - the salt
      passphrase - the passphrase

    • Cryptor

      public Cryptor(String salt, String passphrase)
      Creates a cryptor with 1024 iterations and a key strength of 256.
      This is just a convenience constructor. Since strings are immutable, salt and passphrase cannot be scratched. Consider using Cryptor(byte[], char[]) instead.
      Parameters:
      salt - the salt
      passphrase - the passphrase

  • Method Details

    • getInstance

      public static Cryptor getInstance()
      Gets the optional application-specific cryptor singleton.
      Returns:
      the cryptor, null if no @Service(Cryptor.class) configured

    • getInstanceSafely

      public static Cryptor getInstanceSafely()
      Gets the application-specific cryptor singleton.
      Returns:
      the cryptor, never null
      Throws:
      TentackleRuntimeException - if no cryptor defined

    • encrypt

      public byte[] encrypt(byte[] data)
      Encrypts the data.
      Parameters:
      data - the byte array to encrypt
      Returns:
      the encrypted byte array
      Throws:
      TentackleRuntimeException - if encryption failed

    • encrypt

      public byte[] encrypt(byte[] data, int offset, int length)
      Encrypts the data.
      Parameters:
      data - the byte array to encrypt
      offset - the offset in data
      length - the number of bytes
      Returns:
      the encrypted byte array
      Throws:
      TentackleRuntimeException - if encryption failed

    • decrypt

      public byte[] decrypt(byte[] encryptedData, int offset, int length)
      Decrypts the data.
      Parameters:
      encryptedData - the encrypted byte array
      offset - the offset in the encrypted byte array
      length - the number of bytes to decrypt
      Returns:
      the decrypted data
      Throws:
      TentackleRuntimeException - if decryption failed

    • decrypt

      public byte[] decrypt(byte[] encryptedData)
      Decrypts the data.
      Parameters:
      encryptedData - the encrypted byte array
      Returns:
      the decrypted data
      Throws:
      TentackleRuntimeException - if decryption failed

    • encrypt64

      public String encrypt64(byte[] data)
      Encrypts data to base64 encoding.
      Parameters:
      data - the byte array to encrypt
      Returns:
      the encrypted string in base64 encoding
      Throws:
      TentackleRuntimeException - if encryption failed

    • encrypt

      public byte[] encrypt(char[] chars)
      Encrypts a char array.
      The method clears all traces in memory, including the passed char array.
      Parameters:
      chars - the char array to encrypt
      Returns:
      the encrypted bytes
      Throws:
      TentackleRuntimeException - if encryption failed

    • encrypt64

      public String encrypt64(char[] chars)
      Encrypts a char array to base64 encoding.
      The method clears all traces in memory, including the passed char array.
      Parameters:
      chars - the char array to encrypt
      Returns:
      the encrypted string in base64 encoding
      Throws:
      TentackleRuntimeException - if encryption failed

    • encrypt64

      public String encrypt64(String text)
      Encrypts a string to base64 encoding.
      Parameters:
      text - the text to encrypt
      Returns:
      the encrypted string in base64 encoding
      Throws:
      TentackleRuntimeException - if encryption failed

    • decryptToChars

      public char[] decryptToChars(byte[] encryptedData)
      Decrypts encrypted data to chars.
      Parameters:
      encryptedData - the encrypted data
      Returns:
      the char array
      Throws:
      TentackleRuntimeException - if decryption failed

    • decrypt64ToBytes

      public byte[] decrypt64ToBytes(String encryptedText)
      Decrypts a base64 encoded string.
      Parameters:
      encryptedText - the encrypted text in base64 encoding
      Returns:
      the decrypted data
      Throws:
      TentackleRuntimeException - if decryption failed

    • decrypt64ToChars

      public char[] decrypt64ToChars(String encryptedText)
      Decrypts a base64 encoded string.
      The method clears all traces in memory.
      Parameters:
      encryptedText - the encrypted text in base64 encoding
      Returns:
      the decrypted data
      Throws:
      TentackleRuntimeException - if decryption failed

    • decrypt64

      public String decrypt64(String encryptedText)
      Decrypts a base64 encoded string.
      Parameters:
      encryptedText - the encrypted text in base64 encoding
      Returns:
      the decrypted text
      Throws:
      TentackleRuntimeException - if decryption failed

    • apply

      public String apply(String s)
      Encrypts a string.
      Provided for the tentackle-maven-plugin.
      Specified by:
      apply in interface Function<String,String>
      Parameters:
      s - the string
      Returns:
      the encrypted string in base64 encoding

    • deriveURL

      public String deriveURL(String url, String... protocols)
      Derives the unencrypted URL.
      The URL is considered to be encrypted if started with a fake protocol unsupported by the application in the given context. The text after =~ up to the next & (or the end) is taken as the encrypted URL. Example: 
        https://somehost.somedomain.org/login?id=~GK+AG1QIjpBaD51HP/kw9HzpdKZLt2FrInFxd1jtPWvGzaw5lcLcHy5RB/q9yEKQ&user=100
      Hidden gem... ;)
      Parameters:
      url - the possibly encrypted URL
      protocols - the fake protocols not used by the application, such as "http:" or "https:"
      Returns:
      the decrypted URL or the unchanged URL, if no encryption pattern found
      Throws:
      TentackleRuntimeException - if decryption failed

    • getSecretKeyFactory

      protected SecretKeyFactory getSecretKeyFactory()
      Gets the key factory.
      The default implementation returns an instance of PBKDF2WithHmacSHA1.
      Returns:
      the factory

    • createSecretKeySpec

      protected SecretKeySpec createSecretKeySpec(byte[] key)
      Creates the key spec.
      The default implementation returns an AES spec.
      Parameters:
      key - the key
      Returns:
      the spec

    • getCipher

      protected Cipher getCipher()
      Creates a cipher instance.
      The default implementation returns an AES cipher.

      Invoked once per thread, unless the cryptor was created via Cryptor(SecretKey, Cipher). Implementations must return a new instance each time, since Cipher is not thread-safe.

      Returns:
      the cipher