    All Packages  Class Hierarchy  This Package  Previous  Next  Index

# Class java.security.Cipher

    java.lang.Object
       |
       +----java.security.Cipher

public abstract class Cipher
extends Object
implements Cloneable

This class is used to provide the functionality of a general-purpose encryption algorithm, such as `DES` or `RSA`. Encryption is used to ensure confidentiality of digital data.

This class follows the general algorithm architecture found elsewhere in the security API: the base class provides an algorithm-independent interface to basic encryption functionality, with provider implementation subclassing a subset of the behaviors.

A Cipher object is able to perform encryption and decryption.

Like other algorithm-based classes in JavaSecurity, the Cipher class is composed of both application and provider interfaces.

Cipher API (Application Programming Interface)
  This is the interface of methods called by applications needing encryption services. The API consists of all public methods.
Cipher SPI (Service Provider Interface)
  This is the interface implemented by providers that supply specific algorithms. It consists of all methods whose names are prefixed by `engine`. Each such method is called by a correspondingly-named public API method. For example, the `engineCrypt` method is called by the `crypt` method.

##

DECRYPT
  The state of the cipher when it is ready to decrypt, that is, the state it is in right after a call to `initDecrypt`.
ENCRYPT
  The state of the cipher when it is ready to encrypt, that is, the state it is in right after a call to `initEncrypt`.
UNINITIALIZED
  The state of the cipher object when it is uninitialized, that is, the state it is in right after it has been created by a call to `getInstance`.

##

Cipher()
  Constructor used for dynamic instantiation.
Cipher(boolean, boolean, String)
  Constructor for a Cipher.

##

blockSize()
  Returns the length of a input block, in bytes.
crypt(byte[])
  Encrypts or decrypts the specified array of data.
crypt(byte[], int, int)
  Encrypts or decrypts the specified subarray of data.
crypt(byte[], int, int, byte[], int)
  Encrypts or decrypts the specified subarray of data and places the result in the specified output buffer.
engineBlockSize()
  SPI: Returns the length of an input block, in bytes.
engineCrypt(byte[], int)
  This method is overriden by ciphers that handle their own buffering.
engineInitDecrypt(Key)
  SPI: Initializes this cipher for decryption, using the specified key.
engineInitEncrypt(Key)
  SPI:Initializes this cipher for encryption, using the specified key.
engineOutBufferSize(int, boolean)
  SPI: Returns the length of an output block, in bytes.
engineUpdate(byte[], int, int, byte[], int)
  Updates some data.
getAlgorithm()
  Returns this cipher's standard algorithm name.
getInstance(String)
  Generates a Cipher object that implements the specified algorithm.
getInstance(String, String)
  Generates a block Cipher object implementing the specified algorithm from the specified provider.
getMode()
  Returns this cipher's standard mode name.
getPadding()
  Returns this cipher's padding scheme name.
getProvider()
  Returns the name of the provider of this cipher.
getState()
  Returns the state of this cipher object.
initDecrypt(Key)
  Initializes this cipher for decryption, using the specified key.
initEncrypt(Key)
  Initializes this cipher for encryption, using the specified key.
outBufferSize(int)
  Returns the size of the output buffer necessary to hold the data resulting from a call to crypt or a call to update.

##

UNINITIALIZED

     public static final int UNINITIALIZED

  The state of the cipher object when it is uninitialized, that is, the state it is in right after it has been created by a call to `getInstance`.

  See Also:
    getInstance

ENCRYPT

     public static final int ENCRYPT

  The state of the cipher when it is ready to encrypt, that is, the state it is in right after a call to `initEncrypt`.

  See Also:
    initEncrypt

DECRYPT

     public static final int DECRYPT

  The state of the cipher when it is ready to decrypt, that is, the state it is in right after a call to `initDecrypt`.

  See Also:
    initDecrypt

##

Cipher

     protected Cipher()

  Constructor used for dynamic instantiation.

Cipher

     protected Cipher(boolean implBuffering,
                      boolean implPadding,
                      String provider)

  Constructor for a Cipher. This constructor is only for use by subclasses, which should pass the correct arguments to convey their behavior to the superclass. Applications should not call this constructor to get a Cipher; they should call one of the `getInstance` factory methods instead.

  Parameters:
    implBuffering - if true, this argument indicates that the implementation implements buffering, and that therefore the superclass does not need to provide the subclass with block-sized data blocks.
    implPadding - if true, this argument indicates that the implementation implements padding, and that it is OK to call `crypt` after any length of data has been updated, including lengths which are not multiples of the block size.
    provider - the name of the provider of the underlying cryptographic engine. Refer to Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.

##

getInstance

     public static Cipher getInstance(String algorithm) throws NoSuchAlgorithmException

  Generates a Cipher object that implements the specified algorithm. If the default provider package contains a Cipher subclass implementing the algorithm, an instance of that subclass is returned. If the algorithm is not available in the default package, other packages are searched.

  For block ciphers, this method returns a block cipher in ECB mode, with no padding. A more specialized `getInstance` method should be called if a block cipher implementing a different mode and padding scheme is desired. The algorithm string should specify algorithm, mode and padding. For example,

           cipher = Cipher.getInstance("DES/ECB/PKCS#5");

  Parameters:
    algorithm - the standard string name of the algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
  Returns:
    the new Cipher object, in the UNINITIALIZED state.
  Throws: NoSuchAlgorithmException
    if the algorithm is not available in the environment.
  See Also:
    UNINITIALIZED

getInstance

     public static Cipher getInstance(String algorithm,
                                      String provider) throws NoSuchAlgorithmException, NoSuchProviderException

  Generates a block Cipher object implementing the specified algorithm from the specified provider.

  Parameters:
    algorithm - the standard string name of the algorithm. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.
    provider - the name of the provider.
  Returns:
    the new Cipher object, in the UNINITIALIZED state.
  Throws: NoSuchAlgorithmException
    if the algorithm is not available from this provider.
  Throws: NoSuchProviderException
    if the provider is not available in this environment.
  See Also:
    UNINITIALIZED, Provider

getState

     public final int getState()

  Returns the state of this cipher object. Possible states are:

  UNINITIALIZED
    The cipher has not been initialized.
  ENCRYPT
    The cipher has been initialized for encryption. It may be used for encryption only.
  DECRYPT
    The cipher has been initialized for decryption. It may be used for decryption only.

  Returns:
    the state of this cipher object.
  See Also:
    UNINITIALIZED, ENCRYPT, DECRYPT

getAlgorithm

     public final String getAlgorithm()

  Returns this cipher's standard algorithm name. See Appendix A in the Java Cryptography Architecture API Specification & Reference for information about standard algorithm names.

  Returns:
    the algorithm's standard name (such as "DES").

getMode

     public final String getMode()

  Returns this cipher's standard mode name. See Appendix A in the Java Cryptography Extension API Specification & Reference for information about standard mode names.

  Returns:
    the cipher's standard mode name (such as "CBC-EDE3".)

getPadding

     public final String getPadding()

  Returns this cipher's padding scheme name. See Appendix A in the Java Cryptography Extension API Specification & Reference for information about standard padding scheme names.

  Returns:
    the cipher's standard padding scheme name (such as "PKCS#5" or "NONE".)

getProvider

     public final String getProvider()

  Returns the name of the provider of this cipher.

  Returns:
    the provider name (such as "SUN").

outBufferSize

     public final int outBufferSize(int inLen)

  Returns the size of the output buffer necessary to hold the data resulting from a call to crypt or a call to update. This call takes into account any data currently being buffered, either by this class or by the underlying implementation.

  Returns:
    inLen the number of bytes to process.
  Throws: IllegalBlockSizeException
    if the total input length is not a valid length.

blockSize

     public final int blockSize()

  Returns the length of a input block, in bytes. This is used for both input and output considerations:
  - For non-padding algorithms, when the total amount of data to be encrypted must be a multiple of the block size.
  - For all algorithms, the total amount of data to be decrypted must be a multiple of block size.

  Block sizes are returned in bytes.

  Returns:
    the length in bytes of a block for this cipher.

initEncrypt

     public final void initEncrypt(Key key) throws KeyException

  Initializes this cipher for encryption, using the specified key. A successful call to this method puts the cipher in the ENCRYPT state. This method may be called on a cipher in any state. Any state information (key, feedback buffer,...) is lost and reset.

  Parameters:
    key - the key to use for encryption.
  Throws: KeyException
    if the key is invalid.

initDecrypt

     public final void initDecrypt(Key key) throws KeyException

  Initializes this cipher for decryption, using the specified key. A successful call to this method puts the cipher in the DECRYPT state. This method may be called on a cipher in any state. Any state information (key, feebcack buffer,...) is lost and reset.

  Parameters:
    key - the key to use for decryption.
  Throws: KeyException
    if the key is invalid.

crypt

     public final byte[] crypt(byte in[]) throws IllegalBlockSizeException

  Encrypts or decrypts the specified array of data. Whether the data is encrypted or decrypted depends on the cipher's initialization state. This method will automatically allocate an output buffer of the right size.

  Parameters:
    in - the input data.
  Returns:
    the encryption or decryption result.
  Throws: IllegalBlockSizeException
    if the number of bytes in the array is not a multiple of the block size, and the cipher is not a padding cipher in ENCRYPT mode.
  See Also:
    initEncrypt, initDecrypt

crypt

     public final byte[] crypt(byte in[],
                               int off,
                               int len) throws IllegalBlockSizeException

  Encrypts or decrypts the specified subarray of data. Whether the data is encrypted or decrypted depends on the cipher's initialization state. This method will automatically allocate an output buffer of the right size.

  Parameters:
    in - the input data.
    off - the offset indicating where the subarray starts in the `in` array.
    len - the length of the subarray.
  Returns:
    the encryption or decryption result.
  Throws: IllegalBlockSizeException
    if the number of bytes in the array is not a multiple of the block size, and the cipher is not a padding cipher in ENCRYPT mode.
  See Also:
    initEncrypt, initDecrypt

crypt

     public final int crypt(byte in[],
                            int inOff,
                            int inLen,
                            byte out[],
                            int outOff) throws IllegalBlockSizeException

  Encrypts or decrypts the specified subarray of data and places the result in the specified output buffer. Whether the data is encrypted or decrypted depends on the cipher's initialization state.

  Parameters:
    in - the input data.
    off - the offset indicating where the subarray starts in the `in` array.
    len - the length of the subarray.
    out - the output buffer.
    outOffset - the offset indicating where to start writing the result into the output buffer.
  Throws: IllegalBlockSizeException
    if the number of bytes in the array is not a multiple of the block size, and the cipher is not a padding cipher in ENCRYPT mode.
  See Also:
    initEncrypt, initDecrypt

engineBlockSize

     protected abstract int engineBlockSize()

  SPI: Returns the length of an input block, in bytes.

  Returns:
    the length in bytes of a block for this cipher.

engineOutBufferSize

     protected int engineOutBufferSize(int inLen,
                                       boolean isFinal)

  SPI: Returns the length of an output block, in bytes.

  Returns:
    the length in bytes of a block for this cipher.

engineInitEncrypt

     protected abstract void engineInitEncrypt(Key key) throws InvalidKeyException

  SPI:Initializes this cipher for encryption, using the specified key.

  After a call to this method, the cipher's state is ENCRYPT.

  Parameters:
    key - the key to use for encryption.
  Throws: InvalidKeyException
    if the key is invalid.

engineInitDecrypt

     protected abstract void engineInitDecrypt(Key key) throws InvalidKeyException

  SPI: Initializes this cipher for decryption, using the specified key.

  After a call to this method, the cipher's state is DECRYPTION.

  Parameters:
    key - the key to use for decryption.
  Throws: InvalidKeyException
    if the key is invalid.

engineUpdate

     protected abstract int engineUpdate(byte in[],
                                         int inOff,
                                         int inLen,
                                         byte out[],
                                         int outOff)

  Updates some data. This method is the main engine method for updating data. For non-buffering implementations, this method will always be called with block-sized chunks of data.

  If the underlying implementation handles buffering, it should, as a rule, buffer less than two blocks for padding ciphers in decryption mode and less than one block for all other ciphers.

  Parameters:
    in - the input data.
    offset - the offset into `in` specifying where the data starts,
    len - the length of the subarray. In the case of a non-buffering implementation, this is always the block size.
    out - the output buffer.
    outOffset - the offset indicating where to start writing into the `out` output buffer.

engineCrypt

     protected int engineCrypt(byte out[],
                               int offset)

  This method is overriden by ciphers that handle their own buffering. It should flush the internal buffer, and process any remaining data. By default, this method returns 0.

  Parameters:
    out - the output buffer into which to write the result.

    All Packages  Class Hierarchy  This Package  Previous  Next  Index