Section 12.5. The Cipher Class

Let's investigate some of the methods used in Example 12-4 and Example 12-5 in more detail.

12.5.1. init( )

Before a Cipher object can encrypt or decrypt data, it needs four things:

• The mode to operate in (encryption or decryption; not a block cipher mode)

• A key

• Algorithm parameters, e.g., an initialization vector

• A source of randomness

The init( ) method prepares the cipher by providing these four quantities or reasonable defaults. There are six overloaded variants:

public final void init(int opmode, Key key) throws InvalidKeyException
public final void init(int opmode, Key key, SecureRandom random)
  throws InvalidKeyException
public final void init(int opmode, Key key, AlgorithmParameterSpec params)
  throws InvalidKeyException, InvalidAlgorithmParameterException
public final void init(int opmode, Key key, AlgorithmParameterSpec params,
  SecureRandom random) throws InvalidKeyException,
  InvalidAlgorithmParameterException
public final void init(int opmode, Key key, AlgorithmParameters params)
  throws InvalidKeyException, InvalidAlgorithmParameterException
public final void init(int opmode, Key key, AlgorithmParameters params,
  SecureRandom random) throws InvalidKeyException,
  InvalidAlgorithmParameterException

You can reuse a cipher object by invoking its init( ) method a second time. If you do, all previous information in the object is lost.

12.5.1.1. Mode

The mode determines whether this cipher is used for encryption or decryption. The mode argument has two possible values, which are both mnemonic constants defined by the Cipher class: Cipher.ENCRYPT_MODE and Cipher.DECRYPT_MODE .

public static final int ENCRYPT_MODE
public static final int DECRYPT_MODE

12.5.1.2. Key

The key is an instance of the java.security.Key interface. Symmetric ciphers like DES use the same key for both encryption and decryption. Asymmetric ciphers like RSA use different keys for encryption or decryption. Keys generally depend on the cipher. For instance, an RSA key cannot be used to encrypt a DES file or vice versa. If the key you provide doesn't match the cipher's algorithm, an InvalidKeyException is thrown.

To create a key, you first use the bytes of the key to construct a KeySpec for the algorithm you're using. Key specs are instances of the java.security.spec.KeySpec interface. Algorithm-specific implementations in the java.security.spec package include EncodedKeySpec , X509EncodedKeySpec , KCS8EncodedKeySpec , DSAPrivateKeySpec , and DSAPublicKeySpec , RSAPrivateKeySpec , RSAPrivateCrtKeySpec , RSAMultiPrimePrivateCrtKeySpec , RSAPublicKeySpec , and X509EncodedKeySpec . Java 5 added ECPrivateKeySpec and ECPublicKeySpec for public key cryptography based on elliptic curves rather than prime factorization. The javax.crypto spec package provides a few more including DESKeySpec , DESedeKeySpec , DHPrivateKeySpec , DHPublicKeySpec , PBEKeySpec . For example, this code fragment creates a DESKeySpec object that can be used to encrypt or decrypt from a password string using the DES algorithm:

byte[] desKeyData = password.getBytes( );
DESKeySpec desKeySpec = new DESKeySpec(desKeyData);

Once you've constructed a key specification from the raw bytes of the key, a key factory generates the actual key. A key factory is normally an instance of an algorithm-specific subclass of java.security.KeyFactory . It's retrieved by passing the name of the algorithm to the factory method javax.crypto.SecretKeyFactory.getInstance( ) . For example:

SecretKeyFactory keyFactory = SecretKeyFactory.getInstance("DES");
SecretKey desKey = keyFactory.generateSecret(desKeySpec);

Providers should supply the necessary key factories and spec classes for any algorithms they implement.

A few algorithms, most notably Blowfish, use raw bytes as a key without any further manipulations. In these cases there may not be a key factory for the algorithm. Instead, you simply use the key spec as the secret key. For example:

byte[] blowfishKeyData = password.getBytes( );
SecretKeySpec blowfishKeySpec = new SecretKeySpec(blowfishKeyData,
                                                  "Blowfish");
Cipher blowfish = Cipher.getInstance("Blowfish/ECB/PKCS5Padding");
blowfish.init(Cipher.ENCRYPT_MODE, blowfishKeySpec);

Most of the examples in this book use very basic and not particularly secure passwords as keys. Stronger encryption requires more random keys. The javax.crypto.KeyGenerator class provides methods that generate random keys for any installed algorithm. For example:

KeyGenerator blowfishKeyGenerator = KeyGenerator.getInstance("Blowfish");
SecretKey blowfishKey = blowfishKeyGenerator.generateKey( );
Cipher blowfish = Cipher.getInstance("Blowfish/ECB/PKCS5Padding");
blowfish.init(Cipher.ENCRYPT_MODE, blowfishKey);

Generating random keys opens up the issue of how one stores and transmits the secret keys. To my way of thinking, random key generation makes more sense in public key cryptography, where all keys that need to be transmitted can be transmitted in the clear.

12.5.1.3. Algorithm parameters

The third possible argument to init( ) is a series of instructions for the cipher contained in an instance of the java.security.spec.AlgorithmParameterSpec interface or an instance of the java.security.AlgorithmParameters class. The AlgorithmParameterSpec interface declares no methods or constants. It's simply a marker for more specific subclasses that can provide additional, algorithm-dependent parameters for specific algorithms and modes (for instance, an initialization vector). If the algorithm parameters you provide don't fit the cipher's algorithm, an InvalidAlgorithmParameterException is thrown. The JCE provides several AlgorithmParameterSpec classes in the javax.crypto.spec package, including IVParameterSpec , which can set an initialization vector for modes that need it (CBC, CFB, and OFB), and PBEParameterSpec for password-based encryption.

12.5.1.4. Source of randomness

The final possible argument to init( ) is a SecureRandom object. This argument is only used when in encryption mode. It is an instance of the java.security.SecureRandom class, a subclass of java.util.Random that uses a pseudo-random number algorithm based on the SHA-1 hash algorithm instead of java.util.Random 's linear congruential formula. java.util.Random 's random numbers aren't random enough for strong cryptography. In this book, I will simply accept the default source of randomness.

12.5.2. update( )

Once the init( ) method has prepared the cipher for use, the update( ) method feeds data into it, encrypting or decrypting as it goes. This method has four overloaded variants. The first two return the encrypted or decrypted bytes:

public final byte[] update(byte[] input) throws IllegalStateException
public final byte[] update(byte[] input, int inputOffset, int inputLength)
  throws IllegalStateException

They may return null if you're using a block cipher and not enough data has been provided to fill a block. The input data to be encrypted or decrypted is passed in as an array of bytes. Optional offsets and lengths may be used to select a particular subarray to be processed . update( ) tHRows an IllegalStateException if the cipher has not been initialized or it has already been finished with doFinal( ) . In either case, it's not prepared to accept data until init( ) is called.

The second two variants of update( ) store the output in a buffer byte array passed in as the fourth argument and return the number of bytes stored in the buffer:

public final int update(byte[] input, int inputOffset, int inputLength,
    byte[] output) throws IllegalStateException, ShortBufferException
public final int update(byte[] input, int inputOffset, int inputLength,
    byte[] output, int outputOffset) throws IllegalStateException,
    ShortBufferException

You can also provide an offset into the output array to specify where in the array data should be stored. An offset is useful when you want to repeatedly encrypt/decrypt data into the same array until the data is exhausted. You cannot, however, specify a length for the output data because it's up to the cipher to determine how many bytes of data it's willing to provide. The trick here is to make sure your output buffer is big enough to hold the processed output. Most of the time, the number of output bytes is close to the number of input bytes. However, block ciphers sometimes return fewer bytes on one call and more on the next . You can use the getOutputSize( ) method to determine an upper bound on the amount of data that will be returned if you were to pass in inputLength bytes of data:

public final int getOutputSize(int inputLength) throws IllegalStateException

If you don't do this and your output buffer is too small, update( ) throws a ShortBufferException . In this case, the cipher stores the data for the next call to update( ) .

Java 5 added an update( ) method that reads from a ByteBuffer and writes into an output ByteBuffer :

public final int update(ByteBuffer input, ByteBuffer output)
  throws ShortBufferException, IllegalStateException,
  ReadOnlyBuffer Exception, IllegalArgumentException

Once you run out of data to feed to update( ) , invoke doFinal( ) . This signals the cipher that it should pad the data with extra bytes if necessary and encrypt or decrypt all remaining bytes.

12.5.3. doFinal( )

The doFinal( ) method is responsible for reading one final array of data, wrapping that up with any data remaining in the cipher's internal buffer, adding any extra padding that might be necessary, and then returning the last chunk of encrypted or decrypted data. The simplest implementation of doFinal( ) takes no arguments and returns an array of bytes containing the encrypted or decrypted data. This is used to flush out any data that still remains in the cipher's buffer.

public final byte[] doFinal( )
 throws IllegalStateException, IllegalBlockSizeException, BadPaddingException

An IllegalStateException means that the cipher is not ready to be finished; it has not been initialized; it has been initialized but no data has been fed into it; or it has already been finished and not yet reinitialized. An IllegalBlockSizeException is thrown by encrypting block ciphers if no padding has been requested, and the total number of bytes fed into the cipher is not a multiple of the block size. A BadPaddingException is thrown by a decrypting cipher that does not find the padding it expects to see.

There are five overloaded variants of doFinal( ) that allow you to provide additional input data or to place the result in an output buffer you supply. These variants are:

public final int doFinal(byte[] output, int outputOffset)
 throws IllegalStateException, IllegalBlockSizeException,
 ShortBufferException, BadPaddingException
public final byte[] doFinal(byte[] input)
 throws IllegalStateException, IllegalBlockSizeException, BadPaddingException
public final byte[] doFinal(byte[] input, int inputOffset, int inputLength)
 throws IllegalStateException, IllegalBlockSizeException, BadPaddingException
public final int doFinal(byte[] input, int inputOffset, int inputLength,
 byte[] output) throws IllegalStateException, ShortBufferException,
 IllegalBlockSizeException, BadPaddingException
public final int doFinal(byte[] input, int inputOffset, int inputLength,
 byte[] output, int outputOffset) throws IllegalStateException,
 ShortBufferException, IllegalBlockSizeException, BadPaddingException

All of the arguments are essentially the same as they are for update( ) . output is a buffer where the cipher places the encrypted or decrypted data. outputOffset is the position in the output buffer where this data is placed. input is a byte array that contains the last chunk of data to be encrypted. inputOffset and inputLength select a subarray of input to be encrypted or decrypted.

12.5.4. Accessor Methods

As well as the methods that actually perform the encryption, the Cipher class has several getter methods that provide various information about the cipher. The getProvider( ) method returns a reference to the Provider that's implementing this algorithm. This is an instance of a subclass of java.security.Provider .

public final Provider getProvider( )

For block ciphers, getBlockSize( ) returns the number of bytes in a block. For nonblock methods, it returns 0.

public final int getBlockSize( )

The getOutputSize( ) method tells you how many bytes of output this cipher produces for a given number of bytes of input. You generally use this before calling doFinal( ) or update( ) to make sure you provide a large enough byte array for the output, given inputLength additional bytes of data.

public final int getOutputSize(int inputLen) throws IllegalStateException

The length returned is the maximum number of bytes that may be needed. In some cases, fewer bytes may actually be returned when doFinal( ) is called. An IllegalStateException is thrown if the cipher is not ready to accept more data.

The getIV( ) method returns a new byte array containing this cipher's initialization vector. It's useful when the system picks a random initialization vector and you need to find out what that vector is so you can pass it to the decryption program, perhaps by storing it with the encrypted data.

public final byte[] getIV( )

getIV( ) returns null if the algorithm doesn't use initialization vectors or if the initialization vector isn't yet set.