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:

DES

DESede

DESedeWrap

RC2

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;  
}