All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class java.security.Cipher

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

public abstract synchronized class Cipher
extends Object
implements Cloneable

ATTENTION:

This is NOT the implementation from Sun. This class has been developed by IAIK according to the documentation publically available. Only the documentation from Sun has been inserted into the source files.

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.

blockSize
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.
cryptInternal(byte[], int, int, byte[], int): This method performs a cipher mode specific encryption or decryption without buffering or padding.
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.
getInitializationVector(): Gets the initialization vector for this object.
getInitializationVectorLength(): Returns the size of the initialization vector expected by setInitializationVector.
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.
outBufferSize(int, boolean): Returns the size of the output buffer necessary to hold the data resulting from a call to crypt or a call to update.
setCipherMode(FeedbackCipher): Set the cipher mode of the new Cipher instance.
setInitializationVector(byte[]): Sets the initialization vector for this object.
setPadding(Padding): Set the padding algorithm of the new Cipher instance.
update(byte[], int, int, boolean): This is the corresponding method to engineUpdate().
update(byte[], int, int, byte[], int, boolean): This is the corresponding method to engineUpdate().

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

blockSize

 protected int blockSize

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. At this time buffering and padding are implemented by this class. But implBuffering and implPadding are ignored for subclasses.

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

It is also possible to use the modes CFB and OFB as n-Bit modes ( n must be a multiple of 8 and less or equal the blocksize of the cipher in bits). Using these two modes it is possible to use a block cipher (ie DES) as a stream cipher. Just call:

     cipher = Cipher.getInstance("DES.CFB8");

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:: s 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

setInitializationVector

 public void setInitializationVector(byte iv[]) throws InvalidAlgorithmParameterException

Sets the initialization vector for this object. Note that FeedbackCiphers will usually default to a randomly generated vector if none is provided.

This method may only be called on an uninitialized cipher (one in the UNINITIALIZED state) that implements FeedbackCipher.

Parameters:: iv - - the initialization vector.
Throws: InvalidParameterException: if the initialization vector is of the wrong length or otherwise invalid.

getInitializationVector

 public byte[] getInitializationVector()

Gets the initialization vector for this object. This may be called on a cipher implementing FeedbackCipher. It will return null if the initialization vector has not been set.

Returns:: the initialization vector for this cipher object.

getInitializationVectorLength

 public int getInitializationVectorLength()

Returns the size of the initialization vector expected by setInitializationVector.

Returns:: the required size of the argument to setInitializationVector or 0 if mode is "ECB".

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

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

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.

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

outBufferSize

 public final int outBufferSize(int inLen,
                                boolean isFinal) throws IllegalBlockSizeException

Parameters:: inLen - the number of bytes to process.; isFinal - if this is the last call to update(), the internal buffer should be flushed and padding should be done
Returns:: the size of the output buffer
Throws: IllegalBlockSizeException: if the total input length is not a valid length (only if this cipher uses no Padding).

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

crypt

 public final byte[] crypt(byte in[],
                           int inOff,
                           int inLen) 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

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.; inOff - - the offset indicating where the subarray starts in the in array.; inLen - - the length of the subarray.; out - - the output buffer.; outOff - - 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

update

 public int update(byte in[],
                   int inOff,
                   int inLen,
                   byte out[],
                   int outOff,
                   boolean isFinal) throws IllegalBlockSizeException

This is the corresponding method to engineUpdate(). This method is NOT defined in SUN's JCE API ?!? This method is used to encrypt or decrypt chunks of data of any length. The last call to this method must be done with isFinal = true to empty the buffer and to append the padding if specified.

Parameters:: in - the input data.; inOff - the offset indicating where the subarray starts in the in array.; inLen - the length of the subarray.; out - the output buffer.; outOff - the offset indicating where to start writing the result into the output buffer.; isFinal - true, if this is the last call to update
Returns:: number of bytes written to out array.
Throws: IllegalBlockSizeException: is raised if inLen is not a multiple of blocksize, isFinal = true and padding is not used.

update

 public byte[] update(byte in[],
                      int inOff,
                      int inLen,
                      boolean isFinal) throws IllegalBlockSizeException

Parameters:: in - the input data.; inOff - the offset indicating where the subarray starts in the in array.; inLen - the length of the subarray.; isFinal - true, if this is the last call to update
Returns:: array containing the en/decrypted data
Throws: IllegalBlockSizeException: is raised if inLen is not a multiple of blocksize, isFinal = true and padding is not used.

cryptInternal

 protected void cryptInternal(byte in[],
                              int inOff,
                              int inLen,
                              byte out[],
                              int outOff)

This method performs a cipher mode specific encryption or decryption without buffering or padding.

Parameters:: in - the input data.; inOff - the offset indicating where the subarray starts in the in array.; inLen - the length of the subarray. Must be a multiple of blockSize.; out - the output buffer.; outOff - the offset indicating where to start writing the result into the output buffer.

setCipherMode

 protected void setCipherMode(FeedbackCipher feedbackCipher)

Set the cipher mode of the new Cipher instance.

Parameters:: feedbackCipher - the mode of operation for this cipher
See Also:: CBCMode

setPadding

 protected void setPadding(Padding padding)

Set the padding algorithm of the new Cipher instance.

Parameters:: padding - the padding algorithm to use
See Also:: PKCS5

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. Not implemented at this time (used if subclass implements buffering).

Parameters:: inLen - the number of bytes to process.; isFinal - flush buffer
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. Not implemented at this time (used if subclass implements buffering).

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

All Packages  Class Hierarchy  This Package  Previous  Next  Index