Cipher | Java In A Nutshell, 5th Edition

Cipher

javax.crypto

Java 1.4

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 :

AES	DES	RSA
AESWrap	DESede	PBEWithMD5AndDES
ARCFOUR	DESedeWrap	PBEWithMD5AndTripleDES
Blowfish	RC2	PBEWithSHA1AndRC2_40

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

Subclasses

NullCipher

Passed To

CipherInputStream.CipherInputStream( ) , CipherOutputStream.CipherOutputStream( ) , EncryptedPrivateKeyInfo.getKeySpec( ) , SealedObject.{getObject( ) , SealedObject( )}