Package com.saperion.common.crypto

Interface Cipher

  • public interface Cipher

    Cipher encapsulates a CipherStrategy and offers methods for:

    • encryption/decryption
    • key-generation
    • key conversion

    Its main purpose is to simplify the complexity of the javax.crypto and java.security packages. Their many different free combinable pieces are put together in a few default CipherStrategys for typical use by SAPERION and all methods are centralized in this Cipher. This results in a simple-to-use practical API, on the cost of some method-signatures looking a bit weird and some methods not working well with all CipherStrategys.

    A Cipher is created using the CipherFactory and is based on a CipherStrategy and a KeyDerivationAlgorithm.

    The CipherStrategy defines the encryption algorithm, block mode, padding type and key size to use and enumerates the few strategies used by SAPERION.

    The KeyDerivationAlgorithm defines the algorithm of deriving a Key from a password and salt. This method only works for symmetric encryption algorithms. First create a salt, than get a key from a password and salt and remember the salt, f.e. together with the encrypted text or in a user-database together with the generated key. To decrypt the text or to test the password against the key use the same method again.

    Use newKeys() to create a new pair of keys. If the encryption algorithm is asymmetric the first is the public key and the second is the private key. If the encryption algorithm is symmetric both keys are the same instance.

    To export or store a Key use Key.getEncoded() and for an asymmetric encryption algorithm remember whether it is the public or private key (well in many circumstances this should be implicitly clear out of the location WHERE the key is stored or exported to/imported from). To restore such a Key again, use getKey(byte[], boolean).

    To encrypt/decrypt binary data use encrypt(Key, byte[])/decrypt(Key, byte[]), or the streaming overrides encrypt(Key, InputStream, OutputStream)/decrypt(Key, InputStream, OutputStream).

    For ease of use there are convenient methods for String-encryption/decryption (encrypt(Key, String)/ decrypt(Key, String)). The String to encrypt is first converted to a byte[] using a "UTF-8"-encoding, than encrypted and the result is converted to a hexadecimal representation. Decryption works vice versa.

    The implementations are not synchronized. If used by different threads concurrently, external synchronization is necessary.

    Author:
    agz
    See Also:
    CipherStrategy, KeyDerivationAlgorithm, CipherFactory

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      byte[] decrypt​(java.security.Key key, byte[] arEncryptedData)
      Decrypts the specified encrypted data using the specified Key and returns the clear data.
      java.lang.String decrypt​(java.security.Key key, char[] arEncryptedData)
      Decrypts the specified encrypted data using the specified Key and returns the clear data.
      void decrypt​(java.security.Key key, java.io.InputStream inEncryptedData, java.io.OutputStream outClearData)
      Decrypts the encrypted data of the specified InputStream using the specified Key and writes the clear data to the specified OutputStream.
      java.lang.String decrypt​(java.security.Key key, java.lang.String encryptedData)
      Decrypts the specified encrypted data using the specified Key and returns the clear data.
      byte[] encrypt​(java.security.Key key, byte[] arClearData)
      Encrypts the specified clear data using the specified Key and returns the encrypted data.
      void encrypt​(java.security.Key key, java.io.InputStream inClearData, java.io.OutputStream outEncryptedData)
      Encrypts the clear data of the specified InputStream using the specified Key and writes the encrypted data to the specified OutputStream.
      char[] encrypt​(java.security.Key key, java.lang.String clearData)
      Encrypts the specified clear data using the specified Key and returns the encrypted data.
      CipherStrategy getCipherStrategy()
      Returns the CipherStrategy of this Cipher.
      java.security.Key getKey​(byte[] encodedKey, boolean firstKey)
      Restores a Key from the specified encoded representation (as retrieved by Key.getEncoded()).
      java.security.Key getKey​(java.lang.String password, byte[] salt)
      Creates a Key from the specified password and salt implicitly using the KeyDerivationAlgorithm associated with this Cipher.
      KeyDerivationAlgorithm getKeyDerivationAlgorithm()
      Returns the KeyDerivationAlgorithm of this Cipher.
      Pair<java.security.Key,​java.security.Key> newKeys()
      Creates a Pair of new keys.
      byte[] newSalt()
      Creates a new salt of the correct size initialized with secure random values.

    • Method Detail

      • newKeys

        Pair<java.security.Key,​java.security.Key> newKeys()
        Creates a Pair of new keys. If the encryption algorithm is asymmetric the first is the public key and the second is the private key. If the encryption algorithm is symmetric both keys are the same instance.
        Returns:
        a Pair of new keys

      • getKey

        java.security.Key getKey​(byte[] encodedKey,
                         boolean firstKey)
        Restores a Key from the specified encoded representation (as retrieved by Key.getEncoded()).

        The specified encoded representation must represent a valid key of the CipherStrategy of this Cipher.

        Parameters:
        encodedKey - encoded representation of the Key to get
        firstKey - whether the first or second Key should be restored. If the encryption algorithm is asymmetric the first is the public key and the second is the private key. If the encryption algorithm is symmetric both keys are the same, and this parameter has no effect.
        Returns:
        the Key

      • getKey

        java.security.Key getKey​(java.lang.String password,
                         byte[] salt)
        Creates a Key from the specified password and salt implicitly using the KeyDerivationAlgorithm associated with this Cipher.

        The specified password and salt must not be null.

        Parameters:
        password - password
        salt - salt
        Returns:
        the Key created from the specified password and salt
        See Also:
        newSalt()

      • newSalt

        byte[] newSalt()
        Creates a new salt of the correct size initialized with secure random values.
        Returns:
        new salt
        See Also:
        getKey(String, byte[])

      • encrypt

        void encrypt​(java.security.Key key,
             java.io.InputStream inClearData,
             java.io.OutputStream outEncryptedData)
      throws java.io.IOException
        Encrypts the clear data of the specified InputStream using the specified Key and writes the encrypted data to the specified OutputStream.

        The specified key must not be null and must be valid for the CipherStrategy of this Cipher.

        Both specified streams must not be null.

        Parameters:
        key - Key
        inClearData - InputStream to read clear data from
        outEncryptedData - OutputStream to write the encrypted data to
        Throws:
        java.io.IOException - on errors handling one of the streams
        See Also:
        decrypt(Key, InputStream, OutputStream), encrypt(Key, byte[]), encrypt(Key, String)

      • decrypt

        void decrypt​(java.security.Key key,
             java.io.InputStream inEncryptedData,
             java.io.OutputStream outClearData)
      throws java.io.IOException
        Decrypts the encrypted data of the specified InputStream using the specified Key and writes the clear data to the specified OutputStream.

        The specified key must not be null and must be valid for the CipherStrategy of this Cipher.

        Both specified streams must not be null.

        Parameters:
        key - Key
        inEncryptedData - InputStream to read encrypted data from
        outClearData - OutputStream to write the clear data to
        Throws:
        java.io.IOException - on errors handling one of the streams
        See Also:
        encrypt(Key, InputStream, OutputStream), decrypt(Key, byte[]), decrypt(Key, char[]), decrypt(Key, String)