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 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.

 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

 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

 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

 protected Cipher()

Constructor used for dynamic instantiation.

 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.

 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

 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

 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

 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").

 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".)

 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".)

 public final String getProvider()

Returns the name of the provider of this cipher.

Returns:

the provider name (such as "SUN").

 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.

 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.

 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.

 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.

 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

 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

 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

 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.

 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.

 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.

 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.

 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.

 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