javax.crypto
public class Cipher extends Object
This class implements a cryptographic cipher for transforming data.
Ciphers cannot be instantiated directly; rather one of the
getInstance must be used to instantiate a given
transformation, optionally with a specific provider.
A transformation is of the form:
where algorithm is the base name of a cryptographic cipher (such as "AES"), mode is the abbreviated name of a block cipher mode (such as "CBC" for cipher block chaining mode), and padding is the name of a padding scheme (such as "PKCS5Padding"). If only the algorithm name is supplied, then the provider-specific default mode and padding will be used.
An example transformation is:
Cipher c =
Cipher.getInstance("AES/CBC/PKCS5Padding");Finally, when requesting a block cipher in stream cipher mode
(such as AES
in OFB or CFB mode) the number of bits to be processed
at a time may be specified by appending it to the name of the mode;
e.g. "AES/OFB8/NoPadding". If no such number is
specified a provider-specific default value is used.
See Also: java.security.KeyGenerator SecretKey
| Field Summary | |
|---|---|
| static int | DECRYPT_MODE
The decryption operation mode. |
| static int | ENCRYPT_MODE
The encryption operation mode. |
| static int | PRIVATE_KEY
Constant for when the key to be unwrapped is a private key. |
| static int | PUBLIC_KEY
Constant for when the key to be unwrapped is a public key. |
| static int | SECRET_KEY
Constant for when the key to be unwrapped is a secret key. |
| static int | UNWRAP_MODE
The key unwrapping operation mode. |
| static int | WRAP_MODE
The key wrapping operation mode. |
| Constructor Summary | |
|---|---|
| protected | Cipher(CipherSpi cipherSpi, Provider provider, String transformation)
Create a cipher.
|
| Method Summary | |
|---|---|
| byte[] | doFinal()
Finishes a multi-part transformation, and returns the final
transformed bytes.
|
| byte[] | doFinal(byte[] input)
Finishes a multi-part transformation or does an entire
transformation on the input, and returns the transformed bytes.
|
| byte[] | doFinal(byte[] input, int inputOffset, int inputLength)
Finishes a multi-part transformation or does an entire
transformation on the input, and returns the transformed bytes.
|
| int | doFinal(byte[] output, int outputOffset)
Finishes a multi-part transformation and stores the transformed
bytes into the given array.
|
| int | doFinal(byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset)
Finishes a multi-part transformation or transforms a portion of a
byte array, and stores the result in the given byte array.
|
| int | doFinal(byte[] input, int inputOffset, int inputLength, byte[] output) |
| int | doFinal(ByteBuffer input, ByteBuffer output)
Finishes a multi-part transformation with, or completely
transforms, a byte buffer, and stores the result into the output
buffer.
|
| String | getAlgorithm()
Get the name that this cipher instance was created with; this is
equivalent to the "transformation" argument given to any of the
{@link #getInstance()} methods.
|
| int | getBlockSize()
Return the size of blocks, in bytes, that this cipher processes.
|
| ExemptionMechanism | getExemptionMechanism()
Return the currently-operating {@link ExemptionMechanism}.
|
| static Cipher | getInstance(String transformation)
Creates a new cipher instance for the given transformation.
|
| static Cipher | getInstance(String transformation, String provider)
Creates a new cipher instance for the given transformation and the named
provider.
|
| static Cipher | getInstance(String transformation, Provider provider)
Creates a new cipher instance for a given transformation from a given
provider.
|
| byte[] | getIV()
Return the initialization vector that this instance was
initialized with.
|
| int | getOutputSize(int inputLength)
Returns the size an output buffer needs to be if this cipher is
updated with a number of bytes.
|
| AlgorithmParameters | getParameters()
Return the {@link java.security.AlgorithmParameters} that this
instance was initialized with.
|
| Provider | getProvider()
Return this cipher's provider.
|
| void | init(int opmode, Certificate certificate) Initialize this cipher with the public key from the given certificate. The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
As per the Java 1.4 specification, if If this cipher requires any random bytes (for example for an initilization vector) than the {@link java.security.SecureRandom} with the highest priority is used as the source of these bytes. A call to any of the |
| void | init(int opmode, Key key) Initialize this cipher with the supplied key. The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
If this cipher requires any random bytes (for example for an initilization vector) than the {@link java.security.SecureRandom} with the highest priority is used as the source of these bytes. A call to any of the |
| void | init(int opmode, Certificate certificate, SecureRandom random) Initialize this cipher with the public key from the given certificate and the specified source of randomness. The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
As per the Java 1.4 specification, if If this cipher requires any random bytes (for example for an initilization vector) than the {@link java.security.SecureRandom} with the highest priority is used as the source of these bytes. A call to any of the |
| void | init(int opmode, Key key, SecureRandom random) Initialize this cipher with the supplied key and source of randomness. The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
A call to any of the |
| void | init(int opmode, Key key, AlgorithmParameters params) Initialize this cipher with the supplied key and parameters. The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
If this cipher requires any random bytes (for example for an initilization vector) then the {@link java.security.SecureRandom} with the highest priority is used as the source of these bytes. A call to any of the |
| void | init(int opmode, Key key, AlgorithmParameterSpec params) Initialize this cipher with the supplied key and parameters. The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
If this cipher requires any random bytes (for example for an initilization vector) then the {@link java.security.SecureRandom} with the highest priority is used as the source of these bytes. A call to any of the |
| void | init(int opmode, Key key, AlgorithmParameters params, SecureRandom random) Initialize this cipher with the supplied key, parameters, and source of randomness. The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
A call to any of the |
| void | init(int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random) Initialize this cipher with the supplied key, parameters, and source of randomness. The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
A call to any of the |
| Key | unwrap(byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType)
Unwrap a previously-wrapped key.
|
| byte[] | update(byte[] input)
Continue a multi-part transformation on an entire byte array,
returning the transformed bytes.
|
| byte[] | update(byte[] input, int inputOffset, int inputLength)
Continue a multi-part transformation on part of a byte array,
returning the transformed bytes.
|
| int | update(byte[] input, int inputOffset, int inputLength, byte[] output)
Continue a multi-part transformation on part of a byte array,
placing the transformed bytes into the given array.
|
| int | update(byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset)
Continue a multi-part transformation on part of a byte array,
placing the transformed bytes into the given array.
|
| int | update(ByteBuffer input, ByteBuffer output)
Continue a multi-part transformation on a byte buffer, storing
the transformed bytes into another buffer.
|
| byte[] | wrap(Key key)
Wrap a key.
|
Parameters: cipherSpi The underlying implementation of the cipher. provider The provider of this cipher implementation. transformation The transformation this cipher performs.
Returns: The final transformed bytes.
Throws: java.lang.IllegalStateException If this instance has not been initialized, or if a doFinal call has already been made. javax.crypto.IllegalBlockSizeException If this instance has no padding and the input is not a multiple of this cipher's block size. javax.crypto.BadPaddingException If this instance is decrypting and the padding bytes do not match this instance's padding scheme.
Parameters: input The final input bytes.
Returns: The final transformed bytes.
Throws: java.lang.IllegalStateException If this instance has not been initialized, or if a doFinal call has already been made. javax.crypto.IllegalBlockSizeException If this instance has no padding and the input is not a multiple of this cipher's block size. javax.crypto.BadPaddingException If this instance is decrypting and the padding bytes do not match this instance's padding scheme.
Parameters: input The final input bytes. inputOffset The index in the input bytes to start. inputLength The number of bytes to read from the input.
Returns: The final transformed bytes.
Throws: java.lang.IllegalStateException If this instance has not been initialized, or if a doFinal call has already been made. javax.crypto.IllegalBlockSizeException If this instance has no padding and the input is not a multiple of this cipher's block size. javax.crypto.BadPaddingException If this instance is decrypting and the padding bytes do not match this instance's padding scheme.
Parameters: output The destination for the transformed bytes. outputOffset The offset in output to start storing bytes.
Returns: The number of bytes placed into the output array.
Throws: java.lang.IllegalStateException If this instance has not been initialized, or if a doFinal call has already been made. javax.crypto.IllegalBlockSizeException If this instance has no padding and the input is not a multiple of this cipher's block size. javax.crypto.BadPaddingException If this instance is decrypting and the padding bytes do not match this instance's padding scheme. javax.crypto.ShortBufferException If the output array is not large enough to hold the transformed bytes.
Parameters: input The input bytes. inputOffset The index in input to start. inputLength The number of bytes to transform. output The output buffer. outputOffset The index in output to start.
Returns: The number of bytes placed into the output array.
Throws: java.lang.IllegalStateException If this instance has not been initialized, or if a doFinal call has already been made. javax.crypto.IllegalBlockSizeException If this instance has no padding and the input is not a multiple of this cipher's block size. javax.crypto.BadPaddingException If this instance is decrypting and the padding bytes do not match this instance's padding scheme. javax.crypto.ShortBufferException If the output array is not large enough to hold the transformed bytes.
Parameters: input The input buffer. output The output buffer.
Returns: The number of bytes stored into the output buffer.
Throws: IllegalArgumentException If the input and output buffers are the same object. IllegalStateException If this cipher was not initialized for encryption or decryption. ReadOnlyBufferException If the output buffer is not writable. IllegalBlockSizeException If this cipher requires a total input that is a multiple of its block size to complete this transformation. ShortBufferException If the output buffer is not large enough to hold the transformed bytes. BadPaddingException If the cipher is a block cipher with a padding scheme, and the decrypted bytes do not end with a valid padding.
Since: 1.5
Returns: The cipher name.
Returns: The block size.
Returns: null, currently.
The installed providers are tried in order for an implementation, and the first appropriate instance is returned. If no installed provider can provide the implementation, an appropriate exception is thrown.
Parameters: transformation The transformation to create.
Returns: An appropriate cipher for this transformation.
Throws: NoSuchAlgorithmException If no installed provider can supply the appropriate cipher or mode. NoSuchPaddingException If no installed provider can supply the appropriate padding.
Parameters: transformation The transformation to create. provider The name of the provider to use.
Returns: An appropriate cipher for this transformation.
Throws: NoSuchAlgorithmException If the provider cannot supply the
appropriate cipher or mode. NoSuchProviderException If the named provider is not installed. NoSuchPaddingException If the provider cannot supply the
appropriate padding. IllegalArgumentException if either transformation or
provider is null.
Parameters: transformation The transformation to create. provider The provider to use.
Returns: An appropriate cipher for this transformation.
Throws: NoSuchAlgorithmException If the given provider cannot supply the appropriate cipher or mode. NoSuchPaddingException If the given provider cannot supply the appropriate padding scheme.
Returns: The IV.
Parameters: inputLength The input length.
Returns: The output length given this input length.
Throws: java.lang.IllegalStateException If this instance has not been initialized, or if a doFinal call has already been made.
Returns: The parameters.
Returns: The provider.
Initialize this cipher with the public key from the given certificate.
The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
opmode argument is {@link #ENCRYPT_MODE}, {@link
#DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
respectively.
As per the Java 1.4 specification, if cert is an
instance of an {@link java.security.cert.X509Certificate} and its
key usage extension field is incompatible with
opmode then an {@link
java.security.InvalidKeyException} is thrown.
If this cipher requires any random bytes (for example for an initilization vector) than the {@link java.security.SecureRandom} with the highest priority is used as the source of these bytes.
A call to any of the init methods overrides the
state of the instance, and is equivalent to creating a new instance
and calling its init method.
Parameters: opmode The operation mode to use. certificate The certificate.
Throws: java.security.InvalidKeyException If the underlying cipher instance rejects the certificate's public key, or if the public key cannot be used as described above.
Initialize this cipher with the supplied key.
The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
opmode argument is {@link #ENCRYPT_MODE}, {@link
#DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
respectively.
If this cipher requires any random bytes (for example for an initilization vector) than the {@link java.security.SecureRandom} with the highest priority is used as the source of these bytes.
A call to any of the init methods overrides the
state of the instance, and is equivalent to creating a new instance
and calling its init method.
Parameters: opmode The operation mode to use. key The key.
Throws: java.security.InvalidKeyException If the underlying cipher instance rejects the given key.
Initialize this cipher with the public key from the given certificate and the specified source of randomness.
The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
opmode argument is {@link #ENCRYPT_MODE}, {@link
#DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
respectively.
As per the Java 1.4 specification, if cert is an
instance of an {@link java.security.cert.X509Certificate} and its
key usage extension field is incompatible with
opmode then an {@link
java.security.InvalidKeyException} is thrown.
If this cipher requires any random bytes (for example for an initilization vector) than the {@link java.security.SecureRandom} with the highest priority is used as the source of these bytes.
A call to any of the init methods overrides the
state of the instance, and is equivalent to creating a new instance
and calling its init method.
Parameters: opmode The operation mode to use. certificate The certificate. random The source of randomness.
Throws: java.security.InvalidKeyException If the underlying cipher instance rejects the certificate's public key, or if the public key cannot be used as described above.
Initialize this cipher with the supplied key and source of randomness.
The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
opmode argument is {@link #ENCRYPT_MODE}, {@link
#DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
respectively.
A call to any of the init methods overrides the
state of the instance, and is equivalent to creating a new instance
and calling its init method.
Parameters: opmode The operation mode to use. key The key. random The source of randomness to use.
Throws: java.security.InvalidKeyException If the underlying cipher instance rejects the given key.
Initialize this cipher with the supplied key and parameters.
The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
opmode argument is {@link #ENCRYPT_MODE}, {@link
#DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
respectively.
If this cipher requires any random bytes (for example for an initilization vector) then the {@link java.security.SecureRandom} with the highest priority is used as the source of these bytes.
A call to any of the init methods overrides the
state of the instance, and is equivalent to creating a new instance
and calling its init method.
Parameters: opmode The operation mode to use. key The key. params The algorithm parameters to initialize this instance with.
Throws: java.security.InvalidKeyException If the underlying cipher instance rejects the given key. java.security.InvalidAlgorithmParameterException If the supplied parameters are inappropriate for this cipher.
Initialize this cipher with the supplied key and parameters.
The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
opmode argument is {@link #ENCRYPT_MODE}, {@link
#DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
respectively.
If this cipher requires any random bytes (for example for an initilization vector) then the {@link java.security.SecureRandom} with the highest priority is used as the source of these bytes.
A call to any of the init methods overrides the
state of the instance, and is equivalent to creating a new instance
and calling its init method.
Parameters: opmode The operation mode to use. key The key. params The algorithm parameters to initialize this instance with.
Throws: java.security.InvalidKeyException If the underlying cipher instance rejects the given key. java.security.InvalidAlgorithmParameterException If the supplied parameters are inappropriate for this cipher.
Initialize this cipher with the supplied key, parameters, and source of randomness.
The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
opmode argument is {@link #ENCRYPT_MODE}, {@link
#DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
respectively.
A call to any of the init methods overrides the
state of the instance, and is equivalent to creating a new instance
and calling its init method.
Parameters: opmode The operation mode to use. key The key. params The algorithm parameters to initialize this instance with. random The source of randomness to use.
Throws: java.security.InvalidKeyException If the underlying cipher instance rejects the given key. java.security.InvalidAlgorithmParameterException If the supplied parameters are inappropriate for this cipher.
Initialize this cipher with the supplied key, parameters, and source of randomness.
The cipher will be initialized for encryption, decryption, key
wrapping, or key unwrapping, depending upon whether the
opmode argument is {@link #ENCRYPT_MODE}, {@link
#DECRYPT_MODE}, {@link #WRAP_MODE}, or {@link #UNWRAP_MODE},
respectively.
A call to any of the init methods overrides the
state of the instance, and is equivalent to creating a new instance
and calling its init method.
Parameters: opmode The operation mode to use. key The key. params The algorithm parameters to initialize this instance with. random The source of randomness to use.
Throws: java.security.InvalidKeyException If the underlying cipher instance rejects the given key. java.security.InvalidAlgorithmParameterException If the supplied parameters are inappropriate for this cipher.
Parameters: wrappedKey The wrapped key. wrappedKeyAlgorithm The algorithm with which the key was wrapped. wrappedKeyType The type of key (public, private, or secret) that this wrapped key respresents.
Returns: The unwrapped key.
Throws: java.lang.IllegalStateException If this instance has not be
initialized for unwrapping. java.security.InvalidKeyException If wrappedKey
is not a wrapped key, if the algorithm cannot unwrap this
key, or if the unwrapped key's type differs from the
specified type. java.security.NoSuchAlgorithmException If
wrappedKeyAlgorithm is not a valid algorithm
name.
Parameters: input The input bytes.
Returns: The transformed bytes.
Throws: java.lang.IllegalStateException If this cipher was not initialized for encryption or decryption.
Parameters: input The input bytes. inputOffset The index in the input to start. inputLength The number of bytes to transform.
Returns: The transformed bytes.
Throws: java.lang.IllegalStateException If this cipher was not initialized for encryption or decryption.
Parameters: input The input bytes. inputOffset The index in the input to start. inputLength The number of bytes to transform. output The output byte array.
Returns: The number of transformed bytes.
Throws: java.lang.IllegalStateException If this cipher was not initialized for encryption or decryption. javax.security.ShortBufferException If there is not enough room in the output array to hold the transformed bytes.
Parameters: input The input bytes. inputOffset The index in the input to start. inputLength The number of bytes to transform. output The output byte array. outputOffset The index in the output array to start.
Returns: The number of transformed bytes.
Throws: java.lang.IllegalStateException If this cipher was not initialized for encryption or decryption. javax.security.ShortBufferException If there is not enough room in the output array to hold the transformed bytes.
Parameters: input The input buffer. output The output buffer.
Returns: The number of bytes stored in output.
Throws: IllegalArgumentException If the two buffers are the same object. IllegalStateException If this cipher was not initialized for encrypting or decrypting. ReadOnlyBufferException If the output buffer is not writable. ShortBufferException If the output buffer does not have enough available space for the transformed bytes.
Since: 1.5
Parameters: key The key to wrap.
Returns: The wrapped key.
Throws: java.lang.IllegalStateException If this instance was not initialized for key wrapping. javax.crypto.IllegalBlockSizeException If this instance has no padding and the key is not a multiple of the block size. java.security.InvalidKeyException If this instance cannot wrap this key.