com.github.davidcarboni.cryptolite

Class Crypto

java.lang.Object

com.github.davidcarboni.cryptolite.Crypto

public class Crypto
extends Object

This class provides simple encryption and decryption of Strings and streams. This class uses the "AES" algorithm in "CTR" mode. This hides the complexity involved in selecting types and values for these and allows the caller to simply request encryption and decryption operations. Some effort has been invested in choosing these values so that they are suitable for the needs of a web application:

• AES cipher: NIST standard for the transmission of classified US government data.
• CTR cipher mode: NIST standard cipher mode.
• No padding: the CTR cipher mode is a "streaming" mode and therefore does not require padding.
• Inline initialisation vector: this avoids the need to handle the IV as an additional out-of-band parameter.

Notes on background information used in selecting the cipher, mode and padding:

• Wikipedia: http://en.wikipedia.org/wiki/Advanced_Encryption_Standard

"AES was announced by National Institute of Standards and Technology (NIST) as U.S. FIPS PUB 197 (FIPS 197) on November 26, 2001 after a 5-year standardization process in which fifteen competing designs were presented and evaluated before Rijndael was selected as the most suitable (see Advanced Encryption Standard process for more details). It became effective as a Federal government standard on May 26, 2002 after approval by the Secretary of Commerce. It is available in many different encryption packages. AES is the first publicly accessible and open cipher approved by the NSA for top secret information."

• Beginning Cryptography with Java

"CTR has been standardised by NIST in SP 800-38a and RFC 3686"

• http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html

"AES is about as standard as you can get, and has done a good job of resisting cryptologic attacks over the past decade. Using CTR mode avoids the weakness of ECB mode, the complex (and bug-prone) process of padding and unpadding of partial blocks (or ciphertext stealing), and vastly reduces the risk of side channel attacks thanks to the fact that the data being input to AES is not sensitive." NOTE: CTR mode is "malleable", so if there is a requirement to assure the integrity of the data, on top of encrypting it, this blog recommends adding an HMAC (Hash-based Message Authentication Code).

• http://www.javamex.com/tutorials/cryptography/initialisation_vector.shtml

The initialisation vector used in this class is a random one which, according to this site, provides about the same risk of collision as OFB. Given that a relatively small number of items will be encrypted, as compared to a stream of messages which may contain tens of thousands of messages, this makes is a good choice.

• Wikipedia: http://en.wikipedia.org/wiki/Advanced_Encryption_Standard

U.S. Government announced ... "The design and strength of all key lengths of the AES algorithm (i.e., 128, 192 and 256) are sufficient to protect classified information up to the SECRET level. TOP SECRET information will require use of either the 192 or 256 key lengths". This class has been designed to use 128-bit keys as this does not require unlimited strength encryption and still provides a level of protection equivalent to that used by SECRET level information. Since we are not transmitting these data over the Internet, this seems a reasonable level of protection. It is not clear at the time of writing what the performance impact of using longer keys will be in practice, so this is not a factor in selection of the key size.

Author:

David Carboni

Field Summary

Fields

Modifier and Type	Field and Description
static String	CIPHER_ALGORITHM The name of the cipher algorithm to use for symmetric cryptographic operations.
static String	CIPHER_MODE The name of the cipher mode to use for symmetric cryptographic operations.
static String	CIPHER_NAME The full name of the Cipher to use for cryptographic operations, in a format suitable for passing to the JCE.
static String	CIPHER_PADDING The name of the padding type to use for symmetric cryptographic operations.

Constructor Summary

Constructors

Modifier	Constructor and Description
	Crypto() Initialises the instance by getting and caching a Cipher instance for "AES/CTR/NoPadding".
protected	Crypto(String cipherName) This constructor is protected so that, should you need a different algorithm (e.g.

Method Summary

Methods

Modifier and Type	Method and Description
protected byte[]	decrypt(byte[] bytes, SecretKey key) This method decrypts the given bytes and returns the plain text.
InputStream	decrypt(InputStream source, SecretKey key) This method wraps the source InputStream with a CipherInputStream.
InputStream	decrypt(InputStream source, String password) This method wraps the source InputStream with a CipherInputStream.
String	decrypt(String encrypted, SecretKey key) This method decrypts the given String and returns the plain text.
String	decrypt(String encrypted, String password) This method decrypts the given String and returns the plain text.
protected byte[]	encrypt(byte[] bytes, SecretKey key) This method encrypts a byte array.
InputStream	encrypt(InputStream source, SecretKey key) This method wraps the source InputStream with a CipherInputStream.
OutputStream	encrypt(OutputStream destination, SecretKey key) This method wraps the destination OutputStream with a CipherOutputStream.
OutputStream	encrypt(OutputStream destination, String password) This method wraps the destination OutputStream with a CipherOutputStream.
String	encrypt(String string, SecretKey key) This method encrypts the given String, returning a base-64 encoded String.
String	encrypt(String string, String password) This method encrypts the given String, returning a base-64 encoded String.
int	getIvSize()

Methods inherited from class java.lang.Object

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

Field Detail

CIPHER_ALGORITHM

public static final String CIPHER_ALGORITHM

The name of the cipher algorithm to use for symmetric cryptographic operations.

See Also:

Constant Field Values

CIPHER_MODE

public static final String CIPHER_MODE

The name of the cipher mode to use for symmetric cryptographic operations.

See Also:

Constant Field Values

CIPHER_PADDING

public static final String CIPHER_PADDING

The name of the padding type to use for symmetric cryptographic operations.

See Also:

Constant Field Values

CIPHER_NAME

public static final String CIPHER_NAME

The full name of the Cipher to use for cryptographic operations, in a format suitable for passing to the JCE.

See Also:

Constant Field Values

Constructor Detail

Crypto

public Crypto()

Initialises the instance by getting and caching a Cipher instance for "AES/CTR/NoPadding".

Crypto

protected Crypto(String cipherName)

This constructor is protected so that, should you need a different algorithm (e.g. if you're integrating with a system that uses different crypto settings) it is possible to create a subclass with different settings.

Parameters:

cipherName - This should normally be "AES/CTR/NoPadding".

Method Detail

encrypt

public String encrypt(String string,
             String password)

This method encrypts the given String, returning a base-64 encoded String. Note that the base-64 String will be longer than the input String due base-64 encoding, the inclusion of an initialisation vector and a salt value for the key generated from the given password. A fixed length database field can therefore hold less encrypted than plain-text data.

Parameters:

string - The input String.

password - A password to use as the basis for generating an encryption key. This method calls Keys.generateSecretKey(String, String)

Returns:

The encrypted String, base-64 encoded, or null if the given String is null. An empty string can be encrypted, but a null one cannot.

Throws:

IllegalArgumentException - If the given key is not a valid "AES" key.

See Also:

decrypt(String, String)

encrypt

public String encrypt(String string,
             SecretKey key)

This method encrypts the given String, returning a base-64 encoded String. Note that the base-64 String will be longer than the input String due base-64 encoding and the inclusion of an initialisation vector. A fixed length database field can therefore hold less encrypted than plain-text data.

Parameters:

string - The input String.

key - The key to be used to encrypt the String.

Returns:

The encrypted String, base-64 encoded, or null if the given String is null. An empty string can be encrypted, but a null one cannot.

Throws:

IllegalArgumentException - If the given key is not a valid "AES" key.

See Also:

decrypt(String, SecretKey)

encrypt

protected byte[] encrypt(byte[] bytes,
             SecretKey key)

This method encrypts a byte array. This is useful if you have raw binary data you need to encrypt. To keep the interface simple, this method is marked as protected. The intention is that, if you need to encrypt byte arrays, you can subclass Crypto to expose this method. This is the bread-and-butter of most encryption operations, but ultimately is a less common application-level use-case, because binary data is usually stream-based and the rest of the time it tends to be Strings you need to deal with. This is why it isn't exposed by default.

Parameters:

bytes - The input data.

key - The key to be used to encrypt the data.

Returns:

The encrypted data, or null if the given byte array is null. An empty array can be encrypted, but a null one cannot.

Throws:

IllegalArgumentException - If the given key is not a valid "AES" key.

See Also:

decrypt(byte[], SecretKey)

decrypt

public String decrypt(String encrypted,
             String password)

This method decrypts the given String and returns the plain text.

Parameters:

encrypted - The encrypted String, base-64 encoded, as returned by encrypt(String, SecretKey).

password - The password used for encryption. This will be used to generate the correct key by calling Keys.generateSecretKey(String, String)

Returns:

The decrypted String, or null if the encrypted String is null.

Throws:

IllegalArgumentException - If the given key is not a valid "AES" key.

See Also:

encrypt(String, SecretKey)

decrypt

public String decrypt(String encrypted,
             SecretKey key)

This method decrypts the given String and returns the plain text.

Parameters:

encrypted - The encrypted String, base-64 encoded, as returned by encrypt(String, SecretKey).

key - The key to be used for decryption.

Returns:

The decrypted String, or null if the encrypted String is null.

Throws:

IllegalArgumentException - If the given key is not a valid "AES" key.

See Also:

encrypt(String, SecretKey)

decrypt

protected byte[] decrypt(byte[] bytes,
             SecretKey key)

This method decrypts the given bytes and returns the plain text. This is useful if you have raw binary data you need to decrypt. To keep the interface simple, this method is marked as protected. The intention is that, if you need to encrypt byte arrays, you can subclass Crypto to expose this method. This is the bread-and-butter of most encryption operations, but ultimately is a less common application-level use-case, because binary data is usually stream-based and the rest of the time it tends to be Strings you need to deal with. This is why it isn't exposed by default.

Parameters:

bytes - The encrypted data.

key - The key to be used for decryption.

Returns:

The decrypted String, or null if the encrypted String is null.

Throws:

IllegalArgumentException - If the given key is not a valid "AES" key.

See Also:

encrypt(byte[], SecretKey)

encrypt

public OutputStream encrypt(OutputStream destination,
                   String password)
                     throws IOException

This method wraps the destination OutputStream with a CipherOutputStream. Typical usage is when you have an InputStream for a source of unencrypted data, such as a user-uploaded file, and an OutputStream to write the input to disk. You would call this method to wrap the OutputStream and use the returned CipherOutputStream instead to write the data to, so that it is encrypted as it is written to disk. Note that this method writes a salt value and an initialisation vector to the destination OutputStream, so the destination parameter will have some bytes written to it before this method returns. These bytes are necessary for decryption and a corresponding call to decrypt(InputStream, String) will read and filter them out from the underlying InputStream before returning it.

Parameters:

destination - The output stream to be wrapped with a CipherOutputStream.

password - The password to be used to generate a key to encrypt data written to the returned CipherOutputStream.

Returns:

A CipherOutputStream, which wraps the given OutputStream.

Throws:

IOException - If an error occurs in writing the initialisation vector to the destination stream.

IllegalArgumentException - If the given key is not a valid "AES" key.

See Also:

decrypt(InputStream, String)

encrypt

public OutputStream encrypt(OutputStream destination,
                   SecretKey key)
                     throws IOException

This method wraps the destination OutputStream with a CipherOutputStream. Typical usage is when you have an InputStream for a source of unencrypted data, such as a user-uploaded file, and an OutputStream to write the input to disk. You would call this method to wrap the OutputStream and use the returned CipherOutputStream instead to write the data to, so that it is encrypted as it is written to disk. Note that this method writes an initialisation vector to the destination OutputStream, so the destination parameter will have some bytes written to it before this method returns. These bytes are necessary for decryption and a corresponding call to decrypt(InputStream, SecretKey) will read and filter them out from the underlying InputStream before returning it.

Parameters:

destination - The output stream to be wrapped with a CipherOutputStream.

key - The key to be used to encrypt data written to the returned CipherOutputStream.

Returns:

A CipherOutputStream, which wraps the given OutputStream.

Throws:

IOException - If an error occurs in writing the initialisation vector to the destination stream.

IllegalArgumentException - If the given key is not a valid "AES" key.

See Also:

decrypt(InputStream, SecretKey)

encrypt

public InputStream encrypt(InputStream source,
                  SecretKey key)
                    throws IOException

This method wraps the source InputStream with a CipherInputStream. Typical usage is when you have an InputStream for a source of encrypted data on disk, and an OutputStream to send the file to an HTTP response. You would call this method to wrap the InputStream and use the returned CipherInputStream to read the data from instead so that it is decrypted as it is read and can be written to the response unencrypted. Note that this method reads and discards the random initialisation vector from the source InputStream, so the source parameter will have some bytes read from it before this method returns. These bytes are necessary for decryption and the call to encrypt(OutputStream, SecretKey) will have added these to the start of the underlying data automatically.

Parameters:

source - The source InputStream, containing encrypted data.

key - The key to be used for decryption.

Returns:

A CipherInputStream, which wraps the given source stream and will decrypt the data as they are read.

Throws:

IOException - If an error occurs in reading the initialisation vector from the source stream.

IllegalArgumentException - If the given key is not a valid "AES" key.

See Also:

encrypt(OutputStream, SecretKey)

decrypt

public InputStream decrypt(InputStream source,
                  String password)
                    throws IOException

This method wraps the source InputStream with a CipherInputStream. Typical usage is when you have an InputStream for a source of encrypted data on disk, and an OutputStream to send the file to an HTTP response. You would call this method to wrap the InputStream and use the returned CipherInputStream to read the data from instead so that it is decrypted as it is read and can be written to the response unencrypted. Note that this method reads and discards a salt value and the random initialisation vector from the source InputStream, so the source parameter will have some bytes read from it before this method returns. These bytes are necessary for decryption and the call to encrypt(OutputStream, String) will have added these to the start of the underlying data automatically.

Parameters:

source - The source InputStream, containing encrypted data.

password - The password to be used for decryption.

Returns:

A CipherInputStream, which wraps the given source stream and will decrypt the data as they are read.

Throws:

IOException - If an error occurs in reading the initialisation vector from the source stream.

IllegalArgumentException - If the given key is not a valid "AES" key.

See Also:

encrypt(OutputStream, String)

decrypt

public InputStream decrypt(InputStream source,
                  SecretKey key)
                    throws IOException

This method wraps the source InputStream with a CipherInputStream. Typical usage is when you have an InputStream for a source of encrypted data on disk, and an OutputStream to send the file to an HTTP response. You would call this method to wrap the InputStream and use the returned CipherInputStream to read the data from instead so that it is decrypted as it is read and can be written to the response unencrypted. Note that this method reads and discards the random initialisation vector from the source InputStream, so the source parameter will have some bytes read from it before this method returns. These bytes are necessary for decryption and the call to encrypt(OutputStream, SecretKey) will have added these to the start of the underlying data automatically.

Parameters:

source - The source InputStream, containing encrypted data.

key - The key to be used for decryption.

Returns:

A CipherInputStream, which wraps the given source stream and will decrypt the data as they are read.

Throws:

IOException - If an error occurs in reading the initialisation vector from the source stream.

IllegalArgumentException - If the given key is not a valid "AES" key.

See Also:

encrypt(OutputStream, SecretKey)

getIvSize

public int getIvSize()

Returns:

The initialization vector size, in bytes. This is useful if you want to check whether the size of input data is large enough to represent encrypted data. Encrypted strings and streams will always start with and IV and can only be decrypted if the input is at least this long.