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

Modifier and Type	Method	Description
byte[]	decrypt(Key key, byte[] arEncryptedData)	Decrypts the specified encrypted data using the specified Key and returns the clear data.
String	decrypt(Key key, char[] arEncryptedData)	Decrypts the specified encrypted data using the specified Key and returns the clear data.
void	decrypt(Key key, InputStream inEncryptedData, OutputStream outClearData)	Decrypts the encrypted data of the specified InputStream using the specified Key and writes the clear data to the specified OutputStream.
String	decrypt(Key key, String encryptedData)	Decrypts the specified encrypted data using the specified Key and returns the clear data.
byte[]	encrypt(Key key, byte[] arClearData)	Encrypts the specified clear data using the specified Key and returns the encrypted data.
void	encrypt(Key key, InputStream inClearData, 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(Key key, String clearData)	Encrypts the specified clear data using the specified Key and returns the encrypted data.
CipherStrategy	getCipherStrategy()	Returns the CipherStrategy of this Cipher.
Key	getKey(byte[] encodedKey, boolean firstKey)	Restores a Key from the specified encoded representation (as retrieved by Key.getEncoded()).
Key	getKey(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<Key,Key>	newKeys()	Creates a Pair of new keys.
byte[]	newSalt()	Creates a new salt of the correct size initialized with secure random values.

Method Details

getCipherStrategy

CipherStrategy getCipherStrategy()

Returns the CipherStrategy of this Cipher.

Returns:

the CipherStrategy of this Cipher

getKeyDerivationAlgorithm

KeyDerivationAlgorithm getKeyDerivationAlgorithm()

Returns the KeyDerivationAlgorithm of this Cipher.

Returns:

the KeyDerivationAlgorithm of this Cipher

newKeys

Pair<Key,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

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

Key getKey(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

byte[] encrypt(Key key,
 byte[] arClearData)

Encrypts the specified clear data using the specified Key and returns the encrypted data.

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

The specified clear data must not be null.

Parameters:

key - Key

arClearData - clear data

Returns:

encrypted data

See Also:

• decrypt(Key, byte[])
• encrypt(Key, InputStream, OutputStream)
• encrypt(Key, String)

decrypt

byte[] decrypt(Key key,
 byte[] arEncryptedData)

Decrypts the specified encrypted data using the specified Key and returns the clear data.

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

The specified encrypted data must not be null and must be a decryptable.

Parameters:

key - Key

arEncryptedData - encrypted data

Returns:

clear data

See Also:

• encrypt(Key, byte[])
• decrypt(Key, InputStream, OutputStream)
• decrypt(Key, char[])
• decrypt(Key, String)

encrypt

void encrypt(Key key,
 InputStream inClearData,
 OutputStream outEncryptedData)
      throws 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:

IOException - on errors handling one of the streams

See Also:

• decrypt(Key, InputStream, OutputStream)
• encrypt(Key, byte[])
• encrypt(Key, String)

decrypt

void decrypt(Key key,
 InputStream inEncryptedData,
 OutputStream outClearData)
      throws 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:

IOException - on errors handling one of the streams

See Also:

• encrypt(Key, InputStream, OutputStream)
• decrypt(Key, byte[])
• decrypt(Key, char[])
• decrypt(Key, String)

encrypt

char[] encrypt(Key key,
 String clearData)

Encrypts the specified clear data using the specified Key and returns the encrypted data. See the class documentation for a detailed description of the used algorithm.

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

The specified clear data must not be null.

Parameters:

key - Key

clearData - clear data

Returns:

encrypted data

See Also:

• decrypt(Key, char[])
• decrypt(Key, String)
• encrypt(Key, byte[])
• encrypt(Key, InputStream, OutputStream)

decrypt

String decrypt(Key key,
 char[] arEncryptedData)

Decrypts the specified encrypted data using the specified Key and returns the clear data. See the class documentation for a detailed description of the used algorithm.

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

The specified encrypted data must not be null and must be a decryptable.

Parameters:

key - Key

arEncryptedData - encrypted data

Returns:

clear data

See Also:

• encrypt(Key, String)
• decrypt(Key, String)
• decrypt(Key, byte[])
• decrypt(Key, InputStream, OutputStream)

decrypt

String decrypt(Key key,
 String encryptedData)

Decrypts the specified encrypted data using the specified Key and returns the clear data. See the class documentation for a detailed description of the used algorithm.

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

The specified encrypted data must not be null and must be a decryptable.

Parameters:

key - Key

encryptedData - encrypted data

Returns:

clear data

See Also:

• encrypt(Key, String)
• decrypt(Key, char[])
• decrypt(Key, byte[])
• decrypt(Key, InputStream, OutputStream)