javax.crypto
Class Cipher

java.lang.Object
  javax.crypto.Cipher

Direct Known Subclasses:

NullCipher

public class Cipher
extends Object

Field Summary

static int	DECRYPT_MODE Constant that initializes Ciper to decryption mode
static int	ENCRYPT_MODE Constant that initializes Cipher to encryption mode
static int	PRIVATE_KEY Constant that indicates key to be un-wrapped is a private key
static int	PUBLIC_KEY Constant that indicates key to be un-wrapped is a public key
static int	SECRET_KEY Constant that indicates key to be un-wrapped is a secret key
static int	UNWRAP_MODE Constant that initializes Cipher to key-unwrapping mode
static int	WRAP_MODE Constant that initializes Cipher to key-wrapping mode

Constructor Summary

protected

Cipher(CipherSpi cipher, Provider cipherProvider, String cipherTransformation) Creates a Cipher object

Method Summary

byte[]	doFinal() Finishes a multi-part encryption/decryption operation.
byte[]	doFinal(byte[] input) Finishes a multi-part encryption/decryption operation.
int	doFinal(byte[] output, int outputOffset) Finishes a multi-part encryption/decryption operation.
byte[]	doFinal(byte[] input, int start, int end) Finishes a multi-part encryption/decryption operation.
int	doFinal(byte[] input, int start, int end, byte[] output) Finishes a multi-part encryption/decryption operation.
int	doFinal(byte[] input, int start, int end, byte[] output, int outputStart) Finishes a multi-part encryption/decryption operation.
String	getAlgorithm() Returns the algorithm implemented by this Cipher
int	getBlockSize() Returns the block size (in bytes)
ExemptionMechanism	getExemptionMechanism() Returns the ExemptionMechanism in use with this Cipher
static Cipher	getInstance(String transformation) Returns an instance of Cipher that provides the specified transformation To find a Cipher that implements the specified transformation, the configured providers are searched in the following order: 1) The default provider 2) Other providers in the order of preference (see java.security)
static Cipher	getInstance(String transformation, Provider provider) Returns an instance of Cipher that provides the specified transformation The specified provider is checked for an implementation of the specified algorithm that also supports the requirments of the transformation.
static Cipher	getInstance(String transformation, String provider) Returns an instance of Cipher that provides the specified transformation The specified provider is checked for an implementation of the specified algorithm that also supports the requirments of the transformation.
byte[]	getIV() Returns the initialization vector in use with the Cipher (in a new buffer)
int	getOutputSize(int inputLen) Returns the size of an output buffer needed to hold the result of the next call to update or doFinal, given the input length.
AlgorithmParameters	getParameters() Returns the parameters in use with this Cipher.
Provider	getProvider() Returns the provider of this Cipher
void	init(int opMode, Certificate cert) Initializes the Cipher to operate in opMode using a the public key of the Certificate.
void	init(int opMode, Certificate cert, SecureRandom random) Initializes the Cipher to operate in opMode using a the public key of the Certificate.
void	init(int opMode, Key key) Initializes the Cipher to operate in opMode using the given Key.
void	init(int opMode, Key key, AlgorithmParameters params) Initializes the Cipher to operate in opMode using the given Key.
void	init(int opMode, Key key, AlgorithmParameterSpec params) Initializes the Cipher to operate in opMode using the given Key.
void	init(int opMode, Key key, AlgorithmParameterSpec params, SecureRandom random) Initializes the Cipher to operate in opMode using the given Key.
void	init(int opMode, Key key, AlgorithmParameters params, SecureRandom random) Initializes the Cipher to operate in opMode using the given Key.
void	init(int opMode, Key key, SecureRandom random) Initializes the Cipher to operate in opMode using the given Key.
Key	unwrap(byte[] input, String algorithm, int keyType) Unwraps a key
byte[]	update(byte[] input) Continues a multi-part encryption/decryption operation.
byte[]	update(byte[] input, int start, int end) Continues a multi-part encryption/decrytpion 0operation.
int	update(byte[] input, int start, int end, byte[] output) Continues a multi-part encryption/decryption operation.
int	update(byte[] input, int start, int end, byte[] output, int outputStart) Continues a multi-part encryption/decryption operation.
byte[]	wrap(Key key) Wraps a key

Methods inherited from class java.lang.Object

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

Field Detail

ENCRYPT_MODE

public static final int ENCRYPT_MODE

Constant that initializes Cipher to encryption mode

See Also:

Constant Field Values

DECRYPT_MODE

public static final int DECRYPT_MODE

Constant that initializes Ciper to decryption mode

See Also:

Constant Field Values

WRAP_MODE

public static final int WRAP_MODE

Constant that initializes Cipher to key-wrapping mode

See Also:

Constant Field Values

UNWRAP_MODE

public static final int UNWRAP_MODE

Constant that initializes Cipher to key-unwrapping mode

See Also:

Constant Field Values

PUBLIC_KEY

public static final int PUBLIC_KEY

Constant that indicates key to be un-wrapped is a public key

See Also:

Constant Field Values

PRIVATE_KEY

public static final int PRIVATE_KEY

Constant that indicates key to be un-wrapped is a private key

See Also:

Constant Field Values

SECRET_KEY

public static final int SECRET_KEY

Constant that indicates key to be un-wrapped is a secret key

See Also:

Constant Field Values

Constructor Detail

Cipher

protected Cipher(CipherSpi cipher,
                 Provider cipherProvider,
                 String cipherTransformation)

Creates a Cipher object

Parameters:

cipher - implementor of SPI for cipher

cipherProvider - provider of the cipher

cipherTransformation - transformation to be applied with the cipher

Method Detail

getInstance

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

Returns an instance of Cipher that provides the specified transformation The specified provider is checked for an implementation of the specified algorithm that also supports the requirments of the transformation.

Parameters:

transformation - the transformation that should be supported by the Cipher implementation

provider - the name of a provider that provides support for transformation

Returns:

Cipher an implementation of Cipher that supports the requested transformation

Throws:

NoSuchAlgorithmException - no provider implements the specified algorithm and/or transformation

NoSuchProviderException - the provider could not be found (it is not configured)

NoSuchPaddingException - no provider supports the padding algorithm specified in transformation

getInstance

public static final Cipher getInstance(String transformation,
                                       Provider provider)
                                throws NoSuchAlgorithmException,
                                       NoSuchPaddingException

Returns an instance of Cipher that provides the specified transformation The specified provider is checked for an implementation of the specified algorithm that also supports the requirments of the transformation.

Parameters:

transformation - the transformation that should be supported by the Cipher implementation

provider - a Provider that supports the supplied transformation

Returns:

Cipher an implementation of Cipher that supports the requested transformation

Throws:

NoSuchAlgorithmException - no provider implements the specified algorithm and/or transformation

NoSuchPaddingException - no provider supports the padding algorithm specified in transformation

getProvider

public final Provider getProvider()

Returns the provider of this Cipher

Returns:

Provider the Provider of this Cipher

getAlgorithm

public final String getAlgorithm()

Returns the algorithm implemented by this Cipher

Returns:

String algorithm provided by this Cipher

getBlockSize

public final int getBlockSize()

Returns the block size (in bytes)

Returns:

int Cipher's block size (in bytes)

getOutputSize

public final int getOutputSize(int inputLen)
                        throws IllegalStateException

Returns the size of an output buffer needed to hold the result of the next call to update or doFinal, given the input length. The actual number of bytes produced by that operation might be less that this result

Parameters:

inputLen - length of input (in bytes)

Returns:

int required output buffer size (in bytes)

Throws:

IllegalStateException - Cipher is in incorrect state

getParameters

public final AlgorithmParameters getParameters()

Returns the parameters in use with this Cipher.

Returns:

AlgorithmParameters parameters in use with this Cipher

init

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

Initializes the Cipher to operate in opMode using the given Key. Random data needed (such as for padding) will be obtained from the provided SecureRandom object. For encryption, any necessary algorithm parameters that cannot be inferred from the key will be set to provider-specific defaults. In the case of decryption, an InvalidKeyException will be thrown.

Parameters:

opMode - operation of Cipher (ENCRYPT_MODE, DECRYPT_MODE, ... )

key - key to be used with Cipher

random - source of random data

Throws:

InvalidKeyException - key not valid for the Cipher or the operation

init

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

Initializes the Cipher to operate in opMode using the given Key. Random data needed (such as for padding) will be obtained from the provided SecureRandom object. Parameters will be taken from params. If params is null for ENCRYPT_MODE, provider-specific defaults will be used. If params is null for DECRYPT_MODE, an InvalidAlgorithmParameterException will be thrown.

Parameters:

opMode - operation of Cipher (ENCRYPT_MODE, DECRYPT_MODE, ... )

key - key to be used with Cipher

params - parameters to be used with Cipher

random - source of random data

Throws:

InvalidKeyException - key not valid for Cipher or operation

InvalidAlgorithmParameterException - parameters missing, invalid or not applicable to operation

init

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

Initializes the Cipher to operate in opMode using the given Key. Random data needed (such as for padding) will be created using the highest-preference provider configured (see SecureRandom for info). Parameters will be taken from params. If params is null for ENCRYPT_MODE, provider-specific defaults will be used. If params is null for DECRYPT_MODE, an InvalidAlgorithmParameterException will be thrown.

Parameters:

opMode - operation of Cipher (ENCRYPT_MODE, DECRYPT_MODE, ... )

key - key to be used with Cipher

params - parameters to be used with Cipher

Throws:

InvalidKeyException - key not valid for Cipher or operation

InvalidAlgorithmParameterException - parameters missing, invalid or not applicable to operation

init

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

Initializes the Cipher to operate in opMode using the given Key. Random data needed (such as for padding) will be obtained from the provided SecureRandom object. Parameters will be taken from params. If params is null for ENCRYPT_MODE, provider-specific defaults will be used. If params is null for DECRYPT_MODE, an InvalidAlgorithmParameterException will be thrown.

Parameters:

opMode - operation of Cipher (ENCRYPT_MODE, DECRYPT_MODE, ... )

key - key to be used with Cipher

params - parameters to be used with Cipher

random -

Throws:

InvalidKeyException - key not valid for Cipher or operation

InvalidAlgorithmParameterException - parameters missing, invalid or not applicable to operation

init

public final void init(int opMode,
                       Certificate cert)
                throws InvalidKeyException

Initializes the Cipher to operate in opMode using a the public key of the Certificate. If the Certificate is an X.509 certificate and has a key-usage exension marked critical, the implementation will throw an InvalidKeyException if the key is not to be used for the operation requested. Random data needed (such as for padding) will be created using the highest-preference provider configured (see SecureRandom for info). Any parameters that cannot be infered from the public-key of the certificate will be set to provider-specific defaults for encryption; in the case of decrytpion, an InvalidKeyException will be thrown.

Parameters:

opMode - operation of Cipher (ENCRYPT_MODE, DECRYPT_MODE, ... )

cert - key to be used with Cipher

Throws:

InvalidKeyException - key not valid for Cipher or operation

init

public final void init(int opMode,
                       Certificate cert,
                       SecureRandom random)
                throws InvalidKeyException

Initializes the Cipher to operate in opMode using a the public key of the Certificate. If the Certificate is an X.509 certificate and has a key-usage exension marked critical, the implementation will throw an InvalidKeyException if the key is not to be used for the operation requested. Random data needed (such as for padding) will be obtained from the provided SecureRandom object. Any parameters that cannot be infered from the public-key of the certificate will be set to provider-specific defaults for encryption; in the case of decrytpion, an InvalidKeyException will be thrown.

Parameters:

opMode - operation of Cipher (ENCRYPT_MODE, DECRYPT_MODE, ... )

cert - key to be used with Cipher

random -

Throws:

InvalidKeyException - key not valid for Cipher or operation

update

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

Continues a multi-part encryption/decryption operation. Returns a new buffer with the processed output. Returns null if Cipher is a block Cipher and data is too short to create a new block or the input length is 0.

Parameters:

input - data to be processed

Returns:

byte[] processed data or null if input length is 0 or there is not enough data to fill a block (with block Cipher)

Throws:

IllegalStateException - Cipher is not in a valid state for an update

update

public final byte[] update(byte[] input,
                           int start,
                           int end)
                    throws IllegalStateException

Continues a multi-part encryption/decrytpion 0operation. Returns a new buffer with the processed output. Returns null if Cipher is a block Cipher and data is too short to create a new block or the input length is 0.

Parameters:

input - data to be encrypted

start - start offset of input in input buffer

end - end offset of input in input buffer

Returns:

byte[] processed data or null if input length is 0 or there is not enough data to fill a block (with block Cipher)

Throws:

IllegalStateException - Cipher is not in a valid state for an update

update

public final int update(byte[] input,
                        int start,
                        int end,
                        byte[] output)
                 throws IllegalStateException,
                        ShortBufferException

Continues a multi-part encryption/decryption operation. Returns a new buffer with the processed output. Returns null if Cipher is a block Cipher and data is too short to create a new block or the input length is 0.

Parameters:

input - data to be encrypted

start - start offset of input in plaintext buffer

end - end offset of input in plaintext buffer

output - encrypted data or null if input length is 0 or there is not enough data to fill a block (with block Cipher)

Returns:

int number of bytes written to output

Throws:

IllegalStateException - Cipher is not in a valid state for an update

ShortBufferException - cipherText buffer too short to contain result of the operation

doFinal

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

Finishes a multi-part encryption/decryption operation. Processes any buffered data from previous update operations and pads/unpads data if necessary to complete a block for a block cipher.

Returns:

byte[] processed output

Throws:

IllegalStateException - Cipher state not valid for doFinal operation

IllegalBlockSizeException - No padding has been requested (encryption-mode only) but input is not a multiple of the block size

BadPaddingException - Failure in processing padding in input during decryption operation

doFinal

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

Finishes a multi-part encryption/decryption operation. Processes any buffered data from previous update operations and pads/unpads data if necessary to complete a block for a block cipher.

Parameters:

output - output buffer

outputOffset - offset to start output in output buffer

Returns:

int number of bytes written to output

Throws:

IllegalStateException - Cipher state not valid for doFinal operation

IllegalBlockSizeException - No padding has been requested (encryption-mode only) but input is not a multiple of the block size

ShortBufferException - Not enough room available in output buffer to store processed output

BadPaddingException - Failure in processing padding in input during decryption operation

doFinal

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

Finishes a multi-part encryption/decryption operation. Processes any buffered data from previous update operations and pads/unpads data if necessary to complete a block for a block cipher.

Parameters:

input - data to be processed in addition to buffered input

Returns:

byte[] processed output

Throws:

IllegalStateException - Cipher state not valid for doFinal operation

IllegalBlockSizeException - No padding has been requested (encryption-mode only) but input is not a multiple of the block size

BadPaddingException - Failure in processing padding in input during decryption operation

doFinal

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

Finishes a multi-part encryption/decryption operation. Processes any buffered data from previous update operations and pads/unpads data if necessary to complete a block for a block cipher.

Parameters:

input - data to be processed in addition to buffered input

start - start offset of input in input buffer

end - end offset of input in input buffer

Returns:

byte[] processed output

Throws:

IllegalStateException - Cipher state not valid for doFinal operation

IllegalBlockSizeException - No padding has been requested (encryption-mode only) but input is not a multiple of the block size

BadPaddingException - Failure in processing padding in input during decryption operation

doFinal

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

Finishes a multi-part encryption/decryption operation. Processes any buffered data from previous update operations and pads/unpads data if necessary to complete a block for a block cipher.

Parameters:

input - data to be processed in addition to buffered input

start - start offset of input in input buffer

end - end offset of input in input buffer

output - buffer to which output should be written

Returns:

byte[] processed output

Throws:

IllegalStateException - Cipher state not valid for doFinal operation

IllegalBlockSizeException - No padding has been requested (encryption-mode only) but input is not a multiple of the block size

ShortBufferException - Not enough room available in output buffer to store processed output

BadPaddingException - Failure in processing padding in input during decryption operation

wrap

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

Wraps a key

Parameters:

key - key to be wrapped

Returns:

byte[] wrapped key

Throws:

IllegalStateException - Cipher not in proper state for key wrapping

IllegalBlockSizeException - If a block cipher is in use, no padding has been requested and the input length is not a multiple of the block size

InvalidKeyException - It is not possible or safe to wrap this key

unwrap

public final Key unwrap(byte[] input,
                        String algorithm,
                        int keyType)
                 throws IllegalStateException,
                        InvalidKeyException,
                        NoSuchAlgorithmException

Unwraps a key

Parameters:

input - a wrapped key

algorithm - the algorithm associated with the wrapped key

keyType - the type of key (must be PUBLIC_KEY, PRIVATE_KEY or SECRET_KEY)

Returns:

Key the unwrapped key

Throws:

IllegalStateException - Cipher not in proper state for key unwrapping

InvalidKeyException - input does not represent a wrapped key of keyType for algorithm

NoSuchAlgorithmException - no installed provider can provide a keyType of algorithm

getExemptionMechanism

public final ExemptionMechanism getExemptionMechanism()

Returns the ExemptionMechanism in use with this Cipher

Returns:

ExemptionMechanism ExemptionMechanism in use with this Cipher

doFinal

public final int doFinal(byte[] input,
                         int start,
                         int end,
                         byte[] output,
                         int outputStart)
                  throws IllegalStateException,
                         ShortBufferException,
                         IllegalBlockSizeException,
                         BadPaddingException

Finishes a multi-part encryption/decryption operation. Processes any buffered data from previous update operations and pads/unpads data if necessary to complete a block for a block cipher.

Parameters:

input - data to be processed in addition to buffered input

start - start offset of input in input buffer

end - end offset of input in input buffer

output - buffer to which output should be written

outputStart - the start offset in the output buffer

Returns:

byte[] processed output

Throws:

IllegalStateException - Cipher state not valid for doFinal operation

IllegalBlockSizeException - No padding has been requested (encryption-mode only) but input is not a multiple of the block size

ShortBufferException - Not enough room available in output buffer to store processed output

BadPaddingException - Failure in processing padding in input during decryption operation

getInstance

public static final Cipher getInstance(String transformation)
                                throws NoSuchAlgorithmException,
                                       NoSuchPaddingException

Returns an instance of Cipher that provides the specified transformation To find a Cipher that implements the specified transformation, the configured providers are searched in the following order: 1) The default provider 2) Other providers in the order of preference (see java.security)

Parameters:

transformation - the transformation that should be supported by the Cipher implementation

Returns:

Cipher an implementation of Cipher that supports the requested transformation

Throws:

NoSuchAlgorithmException - no provider implements the specified algorithm and/or transformation

NoSuchPaddingException - no provider supports the padding algorithm specified in transformation

getIV

public final byte[] getIV()

Returns the initialization vector in use with the Cipher (in a new buffer)

Returns:

byte[] initialization vector in use by Cipher, null if none in use

init

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

Initializes the Cipher to operate in opMode using the given Key. Random data needed (such as for padding) will be created using the highest-preference provider configured (see SecureRandom for info). For encryption, any necessary algorithm parameters that cannot be inferred from the key will be set to provider-specific defaults. In the case of decryption, an InvalidKeyException will be thrown.

Parameters:

opMode - operation of Cipher (ENCRYPT_MODE, DECRYPT_MODE, ... )

key - key to be used with Cipher

Throws:

InvalidKeyException - key not valid for the Cipher or the operation

init

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

Initializes the Cipher to operate in opMode using the given Key. Random data needed (such as for padding) will be created using the highest-preference provider configured (see SecureRandom for info). Parameters will be taken from params. If params is null for ENCRYPT_MODE, provider-specific defaults will be used. If params is null for DECRYPT_MODE, an InvalidAlgorithmParameterException will be thrown.

Parameters:

opMode - operation of Cipher (ENCRYPT_MODE, DECRYPT_MODE, ... )

key - key to be used with Cipher

params - parameters to be used with Cipher

Throws:

InvalidKeyException - key not valid for Cipher or operation

InvalidAlgorithmParameterException - parameters missing, invalid or not applicable to operation

update

public final int update(byte[] input,
                        int start,
                        int end,
                        byte[] output,
                        int outputStart)
                 throws IllegalStateException,
                        ShortBufferException

Continues a multi-part encryption/decryption operation. Returns a new buffer with the processed output. Returns null if Cipher is a block Cipher and data is too short to create a new block or the input length is 0.

Parameters:

input - data to be encrypted

start - start offset of input in plaintext buffer

end - end offset of input in plaintext buffer

output - encrypted data or null if input length is 0 or there is not enough data to fill a block (with block Cipher)

outputStart - start offset of processed output into output buffer

Returns:

int number of bytes written to output

Throws:

IllegalStateException - Cipher is not in a valid state for an update

ShortBufferException - cipherText buffer too short to contain result of the operation