Java in a Nutshell, 5th Edition [Electronic resources]

This class performs encryption and decryption of byte arrays. Cipher is provider-based, so to obtain a Cipher object, you must call the static getInstance( ) factory method. The arguments to getInstance( ) are a string that describes the type of encryption desired and, optionally, the name of the provider whose implementation should be used. To specify the desired type of encryption, you can simply specify the name of an encryption algorithm, such as "DES". In Java 5.0, the "SunJCE" provider supports the following algorithm names:

Advanced users may specify a three-part algorithm name that includes the encryption algorithm, the algorithm operating mode, and the padding scheme. These three parts are separated by slash characters, as in "DES/CBC/PKCS5Padding". Finally, if you are requesting a block cipher algorithm in a stream mode, you can specify the number of bits to be processed at a time by following the name of the feedback mode with a number of bits. For example: "DES/CFB8/NoPadding". Details of supported operating modes and padding schemes are beyond the scope of this book. In Java 5.0, you can obtain details about the services available through the SunJCE (or any other) provider through the java.security.Provider.Services class.

Once you have obtained a Cipher object for the desired cryptographic algorithm, mode, and padding scheme, you must initialize it by calling one of the init( ) methods. The first argument to init( ) is one of the constants ENCRYPT_MODE or DECRYPT_MODE. The second argument is a java.security.Key object that performs the encryption or decryption. If you use one of the symmetric (i.e., nonpublic key) encryption algorithms supported by the "SunJCE" provider, this Key object is a SecretKey implementation. Note that some cryptographic providers restrict the maximum allowed key length based on a jurisdiction policy file. In Java 5.0 you can query the maximum allowed key length for a named encryption algorithm with getMaxAllowedKeyLength( ). You can optionally pass a java.security.SecureRandom object to init( ) to provide a source of randomness. If you do not, the Cipher implementation provides its own pseudorandom number generator.

Some cryptographic algorithms require additional initialization parameters; these can be passed to init( ) as a java.security.AlgorithmParameters object or as a java.security.spec.AlgorithmParameterSpec object. When encrypting, you can omit these parameters, and the Cipher implementation uses default values or generates appropriate random parameters for you. In this case, you should call getParameters( ) after performing encryption to obtain the AlgorithmParameters used to encrypt. These parameters are required in order to decrypt, and must therefore be saved or transferred along with the encrypted data. Of the algorithms supported by the "SunJCE" provider, the block ciphers "DES", "DESede", and "Blowfish" all require an initialization vector when they are used in "CBC", "CFB", "OFB", or "PCBC" mode. You can represent an initialization vector with a javax.crypto.spec.IvParameterSpec object and obtain the raw bytes of the initialization vector used by a Cipher with the getIV( ) method. The "PBEWithMD5AndDES" algorithm requires a salt and iteration count as parameters. These can be specified with a javax.crypto.spec.PBEParameterSpec object.

Once you have obtained and initialized a Cipher object, you are ready to use it for encryption or decryption. If you have only a single array of bytes to encrypt or decrypt, pass that input array to one of the doFinal( ) methods. Some versions of this method return the encrypted or decrypted bytes as the return value of the function. Other versions store the encrypted or decrypted bytes to another byte array you specify. If you choose to use one of these latter methods, you should first call getOutputSize( ) to determine the required size of the output array. If you want to encrypt or decrypt data from a streaming source or have more than one array of data, pass the data to one of the update( ) methods, calling it as many times as necessary. Then pass the last array of data to one of the doFinal( ) methods. If you are working with streaming data, consider using the CipherInputStream and CipherOutputStream classes instead.

Java 5.0 adds versions of the update( ) and doFinal( ) that work with ByteBuffer objects, which facilitates the use of encryption and decryption with the New I/O API of java.nio.

public class

Cipher { // Protected Constructors protected

Cipher (CipherSpi

cipherSpi , java.security.Provider

provider , String

transformation ); // Public Constants public static final int

DECRYPT_MODE ; =2 public static final int

ENCRYPT_MODE ; =1 public static final int

PRIVATE_KEY ; =2 public static final int

PUBLIC_KEY ; =1 public static final int

SECRET_KEY ; =3 public static final int

UNWRAP_MODE ; =4 public static final int

WRAP_MODE ; =3 // Public Class Methods public static final Cipher

getInstance (String

transformation ) throws java.security.NoSuchAlgorithmException, NoSuchPaddingException; public static final Cipher

getInstance (String

transformation , String

provider ) throws java.security.NoSuchAlgorithmException, java.security.NoSuchProviderException, NoSuchPaddingException; public static final Cipher

getInstance (String

transformation , java.security.Provider

provider ) throws java.security.NoSuchAlgorithmException, NoSuchPaddingException;

5.0 public static final int

getMaxAllowedKeyLength (String

transformation ) throws java.security.NoSuchAlgorithmException;

5.0 public static final java.security.spec.AlgorithmParameterSpec

getMaxAllowedParameterSpec (String

transformation ) throws java.security.NoSuchAlgorithmException; // Public Instance Methods public final byte[ ]

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

doFinal (byte[ ]

input ) throws IllegalBlockSizeException, BadPaddingException; public final int

doFinal (byte[ ]

output , int

outputOffset ) throws IllegalBlockSizeException, ShortBufferException, BadPaddingException;

5.0 public final int

doFinal (java.nio.ByteBuffer

input , java.nio.ByteBuffer

output ) throws ShortBufferException, IllegalBlockSizeException, BadPaddingException; public final byte[ ]

doFinal (byte[ ]

input , int

inputOffset , int

inputLen ) throws IllegalBlockSizeException, BadPaddingException; public final int

doFinal (byte[ ]

input , int

inputOffset , int

inputLen , byte[ ]

output ) throws ShortBufferException, IllegalBlockSizeException, BadPaddingException; public final int

doFinal (byte[ ]

input , int

inputOffset , int

inputLen , byte[ ]

output , int

outputOffset ) throws ShortBufferException, IllegalBlockSizeException, BadPaddingException; public final String

getAlgorithm ( ); public final int

getBlockSize ( ); public final ExemptionMechanism

getExemptionMechanism ( ); public final byte[ ]

getIV ( ); public final int

getOutputSize (int

inputLen ); public final java.security.AlgorithmParameters

getParameters ( ); public final java.security.Provider

getProvider ( ); public final void

init (int

opmode , java.security.cert.Certificate

certificate ) throws java.security.InvalidKeyException; public final void

init (int

opmode , java.security.Key

key ) throws java.security.InvalidKeyException; public final void

init (int

opmode , java.security.Key

key , java.security.AlgorithmParameters

params ) throws java.security.InvalidKeyException, java.security.InvalidAlgorithmParameterException; public final void

init (int

opmode , java.security.cert.Certificate

certificate , java.security.SecureRandom

random ) throws java.security.InvalidKeyException; public final void

init (int

opmode , java.security.Key

key , java.security.SecureRandom

random ) throws java.security.InvalidKeyException; public final void

init (int

opmode , java.security.Key

key , java.security.spec.AlgorithmParameterSpec

params ) throws java.security.InvalidKeyException, java.security.InvalidAlgorithmParameterException; public final void

init (int

opmode , java.security.Key

key , java.security.spec.AlgorithmParameterSpec

params , java.security.SecureRandom

random ) throws java.security.InvalidKeyException, java.security.InvalidAlgorithmParameterException; public final void

init (int

opmode , java.security.Key

key , java.security.AlgorithmParameters

params , java.security.SecureRandom

random ) throws java.security.InvalidKeyException, java.security.InvalidAlgorithmParameterException; public final java.security.Key

unwrap (byte[ ]

wrappedKey , String

wrappedKeyAlgorithm , int

wrappedKeyType ) throws java.security.InvalidKeyException, java.security.NoSuchAlgorithmException; public final byte[ ]

update (byte[ ]

input );

5.0 public final int

update (java.nio.ByteBuffer

input , java.nio.ByteBuffer

output ) throws ShortBufferException; public final byte[ ]

update (byte[ ]

input , int

inputOffset , int

inputLen ); public final int

update (byte[ ]

input , int

inputOffset , int

inputLen , byte[ ]

output ) throws ShortBufferException; public final int

update (byte[ ]

input , int

inputOffset , int

inputLen , byte[ ]

output , int

outputOffset ) throws ShortBufferException; public final byte[ ]

wrap (java.security.Key

key ) throws IllegalBlockSizeException, java.security.InvalidKeyException; }