javax.crypto
Class Cipher

java.lang.Object
  |
  +--javax.crypto.Cipher

Direct Known Subclasses:

NullCipher

public class Cipher

extends Object

Engine class for algorithm independent Cipher object creation.

Attention: This is not a SUN implementation!

This class has been developed by IAIK according to the documentation publically available.
For SUNīs documentation of this class see http://java.sun.com/security/JCE1.2/spec/apidoc/index.html

This class represents the super API class for building cipher objects (e.g. DES, IDEA) for data encryption and data decryption. For creating a Cipher object use the getInstance method supplied with the particular cryptographic algorithm in mind. Additionally you explicitly may specify a feedback mode and padding scheme to be used and a particular provider.

e.g: Cipher des_cipher = Cipher.getInstance("DES"/ECB/PKCS5Padding");

The string "algorithm/operation mode/padding scheme" is called transformation. At least you have to specifiy the algorithm name; the other parameters may be set by agreeing with default settings. Generally, a cipher object may be used for either encrypting or decrypting. It therefore has to be properly initialized by using one of the corresponding init methods, at least supplied with operation mode (ENCRYPT_MODE or DECRYPT_MODE) and key:

e.g.: des_cipher.init(Cipher.ENCRYPT_MODE, des_key);

The following cipher modes are supported by the IAIK} provider:

• ECB (default) (Electronic Code Book) mode encrypting plaintext blocks into ciphertext blocks independently from each other. The ECB mode is prone to codebook attacks and block replay. A codebook attack may be successfully when being able to read plain- and corresponding ciphertext blocks for a certain quantity of messages making it possible to generate a codebook for decrypting blocks of further messages without knowing the key. For being effective against codebook analyses and block replay (often messages contain common sub-parts making it possible to unnoticed replace these blocks) one can use the CBC mode makes the encryption of one block of plain data conditional on all previously encrypted data blocks.

  Since ECB encrypts each single block independently, it enables random access to encrypted data blocks which may be preferable for database encrypting. Often ECB is used for key-encrypting.

• CBC (Cipher Block Chaining) mode adding some feedback mechanism to a block cipher, so that encrypting the actual block will depend on all previously encrypted data blocks. For ensuring to encrypt identical plaintext blocks to different ciphertext blocks, randomly chosen data is used as first block (initialization vector) when starting the encryption process. A feedback register is filled with the initialization vector to be XORed with the first block of plaintext data. The resulting block is encrypted giving the first ciphertext block which not only is transmitted, but also fed back into the register for being XORed with the next plaintext block before encrypting it. This proceeding continues until whole the given data is encrypted. For decrypting a ciphertext block it is necessary to know its predecessor: After decrypting a received ciphertext block it is XORed with its predecessor ciphertext block - stored in a feedback register - to obtain the corresponding plaintext block.

  CBC is effective against block replay and makes it harder to try a codebook attack; presuming that using different initialization vectors for every message to be encrypted.

  If in CBC some error occurs when transmitting a ciphertext block, this and the immediately following block cannot be decrypted correctly. All subsequent blocks will not be affected by the error. This kind of error propagation may be utilized by an eavesdropper to distort some single ciphertext block for calculated impairing the subsequently decrypted plaintext block. For that reason, the receiver should never trust a block following a faulty block.

  CBC often is used for encrypting files.

• PCBC (Propagated Cipher Block Chaining), a variant of the Cipher Block Chaining (CBC) mode. PCBC is initialized in the same way as CBC, but XORcombines both, previous plaintext and ciphertext block with the actual plaintext block before encrypting it. As in contrast to CBC, where a single bit cipher text error only affects the corresponding and immediately following (decrypted) plaintext block, in PCBC a single-bit cipher text error propagates through all the subsequent (decrypted) plaintext blocks.

• CFB (Cipher Feedback) for running a block cipher in a stream cipher mode.

  The CFB mode uses the underlying block cipher for generating a key stream. Initially, an input register of given length (which is allowed to be smaller than the block size of the the underlying block cipher) is filled with an initilaization vector that has to be changed with every new message to be encrypted. After encrypting the contents of the input register it is XORcombined with the corresponding number of plaintext characters, giving the first ciphertext sequence. Additionally the result of this XORcombination is fed back into the input register to contribute to the generation of the next sequence of the key stream. On the decryption side the block cipher also is used in encryption mode. The initiailization vector for initially filling the register is the same. Every incoming cipher text sequence is fed into the register, encrypted and subsequently XORcombined with the corresponding number of ciphertext characters for forming the corresponding plaintext sequence.

  In contrast to OFB, there is an error propagation when using CFB. A single-bit ciphertext error causes a single-bit error in the plaintext and distorts ciphertext as long as the error passes through the block cipherīs input register. All subsequent ciphertext will be decrypted correctly. An eavesdropper may change single plaintext characters for avtive impairing a ciphertext character leading to the desired plaintext character after decrypting. Since such an attack will strongly distort the subsequently decrypted text, it should be detected, as long as the modified bit is not the last bit of the message.

  CFB is self-recovering and self-synchronizing.

• OFB (Output Feedback) mode for running a block cipher in stream cipher mode.

  As in common with CFB, OFB uses the underlying block cipher for generating a key stream. Unlike CFB, in OFB the plaintext is not involved into the key stream generation process: The encrypted input register (initially filled with an initialization vector) output is fed back into the register before being XORed with plaintext characters to form the actual ciphertext sequence.

  On decryption side, the key stream also is generated independently from the received ciphertext. Again, the underlying block cipher only is used in encryption mode on both encryption and decryption side.

  There is no error propagation in OFB making it possible for some eavesdropper to calculated modify the decrypted plaintext by correspondingly changing the ciphertext. It is important when using OFB to ensure that encryption and decryption side work fully syncronized. If some synchronization error occurs, the received text cannot be decrypted correctly. For that reason, take care for particular synchronization mechanism when using OFB!

• CTR (Counter Mode Encryption)

  Counter-mode encryption ("CTR mode") was introduced by Diffie and Hellman. CTR mode has significant efficiency advantages over the standard encryption modes without weakening the security. In particular its tight security has been proven. Most of the perceived disadvantages of CTR mode are not valid criticisms, but rather caused by the lack of knowledge.

• blocktypes 0, 1, and 2 for RSA encryption, according to PKCS#1

The following padding schemes are supported by the IAIK provider:

• NoPadding No padding
• PKCS5Padding according to PKCS#5
• SSL3Padding according to the Secure Sockets Layer SSL v3.0 specification
• PKCS1Padding for RSA ciphers according to PKCS#1 v1.5
• OAEP for RSA ciphers as specified by PKCS#1 v2.0 and P1363
• ISO78164Padding as specified by the ISO 7816-4 Standard (Information technology -- Identification cards -- Integrated circuit(s) cards with contacts -- Part 4: Interindustry commands for interchange)

Version:

File Revision 31

See Also:

KeyGenerator, SecretKey, AlgorithmParameters, AlgorithmParameterSpec

Field Summary

static int	DECRYPT_MODE Cipher decrypt mode.
static int	ENCRYPT_MODE Cipher encrypt mode.
static int	PRIVATE_KEY Type identifying a private key.
static int	PUBLIC_KEY Type identifying a public key.
static int	SECRET_KEY Type identifying a secret key.
static int	UNWRAP_MODE Mode for key unwrapping (JCE 1.2.1)
static int	WRAP_MODE Mode for key wrapping (JCE 1.2.1)

Constructor Summary

protected

Cipher(CipherSpi cipherSpi, Provider provider, String transformation) Creates a Cipher object.

Method Summary

byte[]	doFinal() Returns the result of the last step of a multi-step en/decryption operation by processing any remaining buffered data.
byte[]	doFinal(byte[] input) Returns the result of the last step of a multi-step en/decryption operation or the result of a single-step en/decryption operation by processing the given input data and any remaining buffered data.
int	doFinal(byte[] output, int outputOffset) Performs the last step of a multi-step en/decryption operation by processing any remaining buffered data.
byte[]	doFinal(byte[] input, int inputOffset, int inputLen) Returns the result of the last step of a multi-step en/decryption operation or the result of a single-step en/decryption operation by processing the given input data and any remaining buffered data.
int	doFinal(byte[] input, int inputOffset, int inputLen, byte[] output) Performs the last step of a multi-step en/decryption operation or a single-step en/decryption operation by processing the given input data and any remaining buffered data.
int	doFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) Performs the last step of a multi-step en/decryption operation or a single-step en/decryption operation by processing the given input data and any remaining buffered data.
String	getAlgorithm() Returns the algorithm name used when creating this object.
int	getBlockSize() Returns the block size corresponding to this cipher.
ExemptionMechanism	getExemptionMechanism() Return the exemption mechanism for this cipher (JCE 1.2.1).
static Cipher	getInstance(String algorithm) Returns the default provider Cipher object implementation of the specified algorithm.
static Cipher	getInstance(String algorithm, String provider) Returns a Cipher object for the specified algorithm, implemented by the given provider.
byte[]	getIV() Returns a byte array containing the initialization vector (IV).
int	getOutputSize(int inputLen) Returns the output buffer size necessary for capturing the data resulting from the next update or doFinal operation including any data currently being buffered.
AlgorithmParameters	getParameters() Returns the parameters used with this cipher.
Provider	getProvider() Returns the provider used for creating this Cipher object.
void	init(int opmode, Certificate certificate) Initialize this cipher.
void	init(int opmode, Certificate certificate, SecureRandom random) Initialize this cipher.
void	init(int opmode, Key key) Initializes this cipher object with a proper key.
void	init(int opmode, Key key, AlgorithmParameters params) Initializes this cipher with a key and a set of algorithm parameters.
void	init(int opmode, Key key, AlgorithmParameterSpec params) Initializes this cipher object with proper key and algorithm parameters.
void	init(int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random) Initializes this cipher object with proper key and algorithm parameters, and some random seed.
void	init(int opmode, Key key, AlgorithmParameters params, SecureRandom random) Initializes this cipher with a key, a set of algorithm parameters, and a source of randomness.
void	init(int opmode, Key key, SecureRandom random) Initializes this cipher object with a proper key and some random seed.
String	toString() Returns a string representation of this Cipher.
Key	unwrap(byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType) Unwrap a wrapped key.
byte[]	update(byte[] input) Returns the result of the next step of a multi-step en/decryption operation.
byte[]	update(byte[] input, int inputOffset, int inputLen) Returns the result of the next step of a multi-step en/decryption operation.
int	update(byte[] input, int inputOffset, int inputLen, byte[] output) Performs the next step of a multi-step en/decryption operation.
int	update(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) Performs the next step of a multi-step en/decryption operation.
byte[]	wrap(Key key) Wrap a key.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ENCRYPT_MODE

public static final int ENCRYPT_MODE

Cipher encrypt mode.

DECRYPT_MODE

public static final int DECRYPT_MODE

Cipher decrypt mode.

WRAP_MODE

public static final int WRAP_MODE

Mode for key wrapping (JCE 1.2.1)

UNWRAP_MODE

public static final int UNWRAP_MODE

Mode for key unwrapping (JCE 1.2.1)

PUBLIC_KEY

public static final int PUBLIC_KEY

Type identifying a public key. For use with key wrapping (JCE 1.2.1)

PRIVATE_KEY

public static final int PRIVATE_KEY

Type identifying a private key. For use with key wrapping (JCE 1.2.1)

SECRET_KEY

public static final int SECRET_KEY

Type identifying a secret key. For use with key wrapping (JCE 1.2.1)

Constructor Detail

Cipher

protected Cipher(CipherSpi cipherSpi,
                 Provider provider,
                 String transformation)

Creates a Cipher object. Only internally used for creating a Cipher object. Applications shall use one of the getInstance factory methods for obtaining a Cipher object.

Parameters:

cipherSpi - the SPI Cipher implementation of the given provider

provider - the provider

transformation - the transformation

Method Detail

getInstance

public static Cipher getInstance(String algorithm)
                          throws NoSuchAlgorithmException,
                                 NoSuchPaddingException

Returns the default provider Cipher object implementation of the specified algorithm. If the default provider does not support the requested algorithm, other available provider packages are searched for it.

Parameters:

algorithm - the algorithm as string transformation e.g., DES/CBC/PKCS5Padding

Returns:

a Cipher object implementing this algorithm, supplied by the default provider

Throws:

NoSuchAlgorithmException - if this algorithm is not implemented

NoSuchPaddingException - if the specified padding is not supported

getInstance

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

Returns a Cipher object for the specified algorithm, implemented by the given provider. If the specified transformation does not include a cipher mode or/and padding scheme, the defaults are left to the cipher implementation, engineSetMode() and engineSetPadding() are not called. For the IAIK cipher implementations the defaults are "ECB" mode and "NoPadding".

Parameters:

algorithm - the algorithm as string transformation e.g., DES/CBC/PKCS5Padding

providerName - the name of the provider implementing this algorithm.

Returns:

a Cipher object implementing this algorithm, supplied by the specified provider

Throws:

NoSuchAlgorithmException - if this algorithm is not implemented by this provider

NoSuchProviderException - if this provider cannot be fetched

NoSuchPaddingException - if the specified padding is not supported

getProvider

public final Provider getProvider()

Returns the provider used for creating this Cipher object.

Returns:

the provider used for creating this Cipher object.

getAlgorithm

public final String getAlgorithm()

Returns the algorithm name used when creating this object.

getBlockSize

public final int getBlockSize()

Returns the block size corresponding to this cipher. The block size is returned in bytes. If the implemented algorithm is not a block cipher, 0 is returned.

Returns:

the block size (in bytes) if this cipher is a block cipher, 0 otherwise.

getOutputSize

public final int getOutputSize(int inputLen)
                        throws IllegalStateException

Returns the output buffer size necessary for capturing the data resulting from the next update or doFinal operation including any data currently being buffered.

Parameters:

inputLen - the number of bytes to process

Returns:

the size of the output buffer (in bytes)

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not yet been initialized)

getIV

public final byte[] getIV()

Returns a byte array containing the initialization vector (IV). If the algorithm corresponding to this cipher object does not use an initialization vector, null is returned.

Returns:

the initialization vector in a byte array if this cipher object operates with an IV and the IV already has been set, null otherwise.

getParameters

public final AlgorithmParameters getParameters()

Returns the parameters used with this cipher. The returned parameters may be the same that were used to initialize this cipher, or may contain the default set of parameters or a set of randomly generated parameters used by the underlying cipher implementation (provided that the underlying cipher implementation uses a default set of parameters or creates new parameters if it needs parameters but was not initialized with any).

Returns:

the parameters used with this cipher, or null if this cipher does not use any parameters

init

public final void init(int opmode,
                       Key key)
                throws InvalidKeyException

Initializes this cipher object with a proper key. Before a cipher object is ready for data processing, it has to be initialized according to the desired cryptographic operation, which is specified by the opmode parameter (either ENCRYPT_MODE or DECCRYPT_MODE).

e.g. cipher_obj.init(Cipher.ENCRYPT_MODE, key);

Parameters:

opmode - the operation mode for which this cipher is used (ENCRYPT_MODE or DECRYPT_MODE)

key - the key

Throws:

InvalidKeyException - if the given key cannot be used for initializing this cipher

init

public final void init(int opmode,
                       Key key,
                       SecureRandom random)
                throws InvalidKeyException

Initializes this cipher object with a proper key and some random seed. Before a cipher object is ready for data processing, it has to be initialized according to the desired cryptographic operation, which is specified by the opmode parameter (either ENCRYPT_MODE or DECCRYPT_MODE).

e.g. cipher_obj.init(Cipher.ENCRYPT_MODE, key, random_seed);

If this cipher (including its underlying feedback or padding scheme) requires any random bytes, it will get them from random.

Parameters:

opmode - the operation mode for which this cipher is used (ENCRYPT_MODE or DECRYPT_MODE)

key - the key

random - the random seed

Throws:

InvalidKeyException - if the given key cannot be used for initializing this cipher

init

public final void init(int opmode,
                       Key key,
                       AlgorithmParameterSpec params)
                throws InvalidKeyException,
                       InvalidAlgorithmParameterException

Initializes this cipher object with proper key and algorithm parameters. Before a cipher object is ready for data processing, it has to be initialized according to the desired cryptographic operation, which is specified by the opmode parameter (either ENCRYPT_MODE or DECCRYPT_MODE).

e.g. cipher_obj.init(Cipher.ENCRYPT_MODE, key, alg_params);

Parameters:

opmode - the operation mode for which this cipher is used (ENCRYPT_MODE or DECRYPT_MODE)

key - the key

params - the algorithm parameters

Throws:

InvalidKeyException - if the given key cannot be used for initializing this cipher

InvalidAlgorithmParameterException - if the given algorithm parameters do not match to this cipher

init

public final void init(int opmode,
                       Key key,
                       AlgorithmParameterSpec params,
                       SecureRandom random)
                throws InvalidKeyException,
                       InvalidAlgorithmParameterException

Initializes this cipher object with proper key and algorithm parameters, and some random seed. Before a cipher object is ready for data processing, it has to be initialized according to the desired cryptographic operation, which is specified by the opmode parameter (either ENCRYPT_MODE or DECCRYPT_MODE).

e.g. cipher_obj.init(Cipher.ENCRYPT_MODE, key, alg_params, random_seed);

Parameters:

opmode - the operation mode for which this cipher is used (ENCRYPT_MODE or DECRYPT_MODE)

key - the key

params - the algorithm parameters

random - the random seed

Throws:

InvalidKeyException - if the given key cannot be used for initializing this cipher

InvalidAlgorithmParameterException - if the given algorithm parameters donīt match to this cipher

init

public final void init(int opmode,
                       Key key,
                       AlgorithmParameters params)
                throws InvalidKeyException,
                       InvalidAlgorithmParameterException

Initializes this cipher with a key and a set of algorithm parameters. The cipher is initialized for encryption or decryption, depending on the value of opmode. Note that when a Cipher object is initialized, it loses all previously-acquired state. In other words, initializing a Cipher is equivalent to creating a new instance of that Cipher and initializing it.

Parameters:

opmode - the operation mode of this cipher (this is either ENCRYPT_MODE or DECRYPT_MODE)

key - the encryption key

params - the algorithm parameters

Throws:

InvalidKeyException - if the given key is inappropriate for initializing thiscipher

InvalidAlgorithmParameterException - if the given algorithm parameters are inappropriate for this cipher

init

public final void init(int opmode,
                       Key key,
                       AlgorithmParameters params,
                       SecureRandom random)
                throws InvalidKeyException,
                       InvalidAlgorithmParameterException

Initializes this cipher with a key, a set of algorithm parameters, and a source of randomness. The cipher is initialized for encryption or decryption, depending on the value of opmode. If this cipher (including its underlying feedback or padding scheme) requires any random bytes, it will get them from random. Note that when a Cipher object is initialized, it loses all previously-acquired state. In other words, initializing a Cipher is equivalent to creating a new instance of that Cipher and initializing it.

Parameters:

opmode - the operation mode of this cipher (this is either ENCRYPT_MODE or DECRYPT_MODE)

key - the encryption key

params - the algorithm parameters

random - the source of randomness

Throws:

InvalidKeyException - if the given key is inappropriate for initializing thiscipher

InvalidAlgorithmParameterException - if the given algorithm parameters are inappropriate for this cipher

init

public final void init(int opmode,
                       Certificate certificate)
                throws InvalidKeyException

Initialize this cipher. New method in JCE 1.2.1.

init

public final void init(int opmode,
                       Certificate certificate,
                       SecureRandom random)
                throws InvalidKeyException

Initialize this cipher. New method in JCE 1.2.1.

update

public final byte[] update(byte[] input)
                    throws IllegalStateException

Returns the result of the next step of a multi-step en/decryption operation. The data to be processed is given in an input byte array, and the resulting en/decrypted data is returned as a output byte array.

Parameters:

input - the byte array holding the data to be processed

Returns:

the byte array containing the en/decrypted data

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not yet been initialized)

update

public final byte[] update(byte[] input,
                           int inputOffset,
                           int inputLen)
                    throws IllegalStateException

Returns the result of the next step of a multi-step en/decryption operation. The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted. The result is returned as a byte array.

Parameters:

input - the byte array holding the data to be processed

inputOffset - the offset indicating the start position within the input byte array

inputLen - the number of bytes to be processed

Returns:

the byte array containing the en/decrypted data

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not yet been initialized)

update

public final int update(byte[] input,
                        int inputOffset,
                        int inputLen,
                        byte[] output)
                 throws IllegalStateException,
                        ShortBufferException

Performs the next step of a multi-step en/decryption operation. The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted. The result is stored in the given output byte array. The number of bytes stored in this output byte array are returned.

Parameters:

input - the byte array holding the data to be processed

inputOffset - the offset indicating the start position within the input byte array

inputLen - the number of bytes to be processed

output - the byte array for holding the result

Returns:

the number of bytes that are stored in the output byte array

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not yet been initialized)

ShortBufferException - if the given output buffer is too small for holding the result

update

public final int update(byte[] input,
                        int inputOffset,
                        int inputLen,
                        byte[] output,
                        int outputOffset)
                 throws IllegalStateException,
                        ShortBufferException

Performs the next step of a multi-step en/decryption operation. The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted. The result is stored in the given output byte array, beginning at outputOffset. The number of bytes stored in this output byte array are returned.

Parameters:

input - the byte array holding the data to be processed

inputOffset - the offset indicating the start position within the input byte array

inputLen - the number of bytes to be processed

output - the byte array for holding the result

outputOffset - the offset indicating the start position within the output byte array to which the en/decrypted data is written

Returns:

the number of bytes that are stored in the output byte array

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not yet been initialized)

ShortBufferException - if the given output buffer is too small for holding the result

doFinal

public final byte[] doFinal()
                     throws IllegalStateException,
                            IllegalBlockSizeException,
                            BadPaddingException

Returns the result of the last step of a multi-step en/decryption operation by processing any remaining buffered data. If necessary, padding is performed. The result is returned as a byte array.

Returns:

the byte array containing the en/decrypted data

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not yet been initialized)

IllegalBlockSizeException - if the total length of the processed data is not a multiple of the block size for a (no padding performing) block cipher

BadPaddingException - if the decrypted data is not bounded by the proper padding bytes after data decryption including (un)padding

doFinal

public final int doFinal(byte[] output,
                         int outputOffset)
                  throws IllegalStateException,
                         IllegalBlockSizeException,
                         ShortBufferException,
                         BadPaddingException

Performs the last step of a multi-step en/decryption operation by processing any remaining buffered data. If necessary, padding is performed. The result is stored within a given output byte array, beginning at outputOffset. The number of bytes stored in the output byte array are returned.

Parameters:

output - the byte array for holding the result

outputOffset - the offset indicating the start position within the output byte array to which the en/decrypted data is written

Returns:

the number of bytes stored in the output byte array

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not yet been initialized)

IllegalBlockSizeException - if the total length of the processed data is not a multiple of the block size for a (no padding performing) block cipher

ShortBufferException - if the given output buffer is too small for holding the result

BadPaddingException - if the decrypted data is not bounded by the proper padding bytes after data decryption including (un)padding

doFinal

public final byte[] doFinal(byte[] input)
                     throws IllegalStateException,
                            IllegalBlockSizeException,
                            BadPaddingException

Returns the result of the last step of a multi-step en/decryption operation or the result of a single-step en/decryption operation by processing the given input data and any remaining buffered data. If necessary, padding is performed. The result is returned as a output byte array.

Parameters:

input - the byte array holding the data to be processed

Returns:

the byte array containing the en/decrypted data

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not yet been initialized)

IllegalBlockSizeException - if the total length of the processed data is not a multiple of the block size for a (no padding performing) block cipher

BadPaddingException - if the decrypted data is not bounded by the proper padding bytes after data decryption including (un)padding

doFinal

public final byte[] doFinal(byte[] input,
                            int inputOffset,
                            int inputLen)
                     throws IllegalStateException,
                            IllegalBlockSizeException,
                            BadPaddingException

Returns the result of the last step of a multi-step en/decryption operation or the result of a single-step en/decryption operation by processing the given input data and any remaining buffered data. The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted, including any buffered bytes of a previous update operation. If necessary, padding is performed. The result is returned as a output byte array.

Parameters:

input - the byte array holding the data to be processed

inputOffset - the offset indicating the start position within the input byte array

inputLen - the number of bytes to be processed

Returns:

the byte array containing the en/decrypted data

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not yet been initialized)

IllegalBlockSizeException - if the total length of the processed data is not a multiple of the block size for a (no padding performing) block cipher

BadPaddingException - if the decrypted data is not bounded by the proper padding bytes after data decryption including (un)padding

doFinal

public final int doFinal(byte[] input,
                         int inputOffset,
                         int inputLen,
                         byte[] output)
                  throws IllegalStateException,
                         ShortBufferException,
                         IllegalBlockSizeException,
                         BadPaddingException

Performs the last step of a multi-step en/decryption operation or a single-step en/decryption operation by processing the given input data and any remaining buffered data. The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted, including any buffered bytes of a previous update operation. If necessary, padding is performed. The result is stored in the given output byte array. The number of bytes stored in this byte array are returned.

Parameters:

input - the byte array holding the data to be processed

inputOffset - the offset indicating the start position within the input byte array

inputLen - the number of bytes to be processed

output - the byte array for holding the result

Returns:

the number of bytes stored in the output byte array

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not yet been initialized)

ShortBufferException - if the given output buffer is too small for holding the result

IllegalBlockSizeException - the offset indicating the start position within the output byte array to which the en/decrypted data is written

BadPaddingException - if the decrypted data is not bounded by the proper padding bytes after data decryption including (un)padding

doFinal

public final int doFinal(byte[] input,
                         int inputOffset,
                         int inputLen,
                         byte[] output,
                         int outputOffset)
                  throws IllegalStateException,
                         ShortBufferException,
                         IllegalBlockSizeException,
                         BadPaddingException

Performs the last step of a multi-step en/decryption operation or a single-step en/decryption operation by processing the given input data and any remaining buffered data. The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted, including any buffered bytes of a previous update operation. If necessary, padding is performed. The result is stored in the given output byte array, beginning at outputOffset. The number of bytes stored in this byte array are returned.

Parameters:

input - the byte array holding the data to be processed

inputOffset - the offset indicating the start position within the input byte array

inputLen - the number of bytes to be processed

output - the byte array for holding the result

outputOffset - the offset indicating the start position within the output byte array to which the en/decrypted data is written

Returns:

the number of bytes stored in the output byte array

Throws:

IllegalStateException - if this cipher is in a wrong state (e.g., has not yet been initialized)

ShortBufferException - if the given output buffer is too small for holding the result

IllegalBlockSizeException - if the total length of the processed data is not a multiple of the block size for a (no padding performing) block cipher

BadPaddingException - if the decrypted data is not bounded by the proper padding bytes after data decryption including (un)padding

wrap

public final byte[] wrap(Key key)
                  throws IllegalStateException,
                         IllegalBlockSizeException,
                         InvalidKeyException

Wrap a key. This is basically the same as encrypting the encoding of the key. Introduced in JCE 1.2.1.

unwrap

public final Key unwrap(byte[] wrappedKey,
                        String wrappedKeyAlgorithm,
                        int wrappedKeyType)
                 throws IllegalStateException,
                        InvalidKeyException,
                        NoSuchAlgorithmException

Unwrap a wrapped key. This is basically the same as decrypting the encoding and reconstructing a key object from it. Introduced in JCE 1.2.1.

getExemptionMechanism

public final ExemptionMechanism getExemptionMechanism()

Return the exemption mechanism for this cipher (JCE 1.2.1). NOTE that this method ALWAYS returns null as the IAIK does not implement 1.2.1 policies or exemptions at the moment.

toString

public String toString()

Returns a string representation of this Cipher.

Overrides:

toString in class Object

Returns:

a string representation