javax.crypto
Class Cipher
- java.lang.Object
javax.crypto.Cipher
- public class Cipher
- extends java.lang.Object
In order to create a Cipher object, the application calls the
Cipher's getInstance
method, and passes the name of the
requested transformation to it. Optionally, the name of a provider
may be specified.
A transformation is a string that describes the operation (or set of operations) to be performed on the given input, to produce some output. A transformation always includes the name of a cryptographic algorithm (e.g., DES), and may be followed by a feedback mode and padding scheme.
A transformation is of the form:
- "algorithm/mode/padding" or
- "algorithm"
(in the latter case, provider-specific default values for the mode and padding scheme are used). For example, the following is a valid transformation:
Cipher c = Cipher.getInstance("DES/CBC/PKCS5Padding");Using modes such as
CFB
and OFB, block
ciphers can encrypt data in units smaller than the cipher's actual
block size. When requesting such a mode, you may optionally specify
the number of bits to be processed at a time by appending this number
to the mode name as shown in the "DES/CFB8/NoPadding
" and
"DES/OFB32/PKCS5Padding
" transformations. If no such
number is specified, a provider-specific default is used. (For
example, the IBMJCE provider uses a default of 64 bits for DES.)
Thus, block ciphers can be turned into byte-oriented stream ciphers by
using an 8 bit mode such as CFB8 or OFB8.
Since:
1.4
Version:
1.123, 03/31/04
Author:
Jan Luehe
See Also:
Field Summary
Modifier and Type
Field and Description
- static
- int
DECRYPT_MODE
Constant used to initialize cipher to decryption mode.
- static
- int
ENCRYPT_MODE
Constant used to initialize cipher to encryption mode.
- static
- int
PRIVATE_KEY
Constant used to indicate the to-be-unwrapped key is a "private key".
- static
- int
PUBLIC_KEY
Constant used to indicate the to-be-unwrapped key is a "public key".
- static
- int
SECRET_KEY
Constant used to indicate the to-be-unwrapped key is a "secret key".
- static
- int
UNWRAP_MODE
Constant used to initialize cipher to key-unwrapping mode.
- static
- int
WRAP_MODE
Constant used to initialize cipher to key-wrapping mode.
Constructor Summary
Modifier
Constructor and Description
- protected
Cipher(CipherSpi cipherSpi,java.security.Provider provider,java.lang.String transformation)
Creates a Cipher object.
Method Summary
Modifier and Type
Method and Description
- byte[]
doFinal()
Finishes a multiple-part encryption or decryption operation, depending
on how this cipher was initialized.
- byte[]
doFinal(byte[] input)
Encrypts or decrypts data in a single-part operation, or finishes a
multiple-part operation.
- int
doFinal(byte[] output,int outputOffset)
Finishes a multiple-part encryption or decryption operation, depending
on how this cipher was initialized.
- byte[]
doFinal(byte[] input,int inputOffset,int inputLen)
Encrypts or decrypts data in a single-part operation, or finishes a
multiple-part operation.
- int
doFinal(byte[] input,int inputOffset,int inputLen,byte[] output)
Encrypts or decrypts data in a single-part operation, or finishes a
multiple-part operation.
- int
doFinal(byte[] input,int inputOffset,int inputLen,byte[] output,int outputOffset)
Encrypts or decrypts data in a single-part operation, or finishes a
multiple-part operation.
- int
doFinal(java.nio.ByteBuffer input,java.nio.ByteBuffer output)
Encrypts or decrypts data in a single-part operation, or finishes a
multiple-part operation.
- java.lang.String
getAlgorithm()
Returns the algorithm name of this Cipher
object.
- int
getBlockSize()
Returns the block size (in bytes).
getExemptionMechanism()
Returns the exemption mechanism object used with this cipher.
- static
- Cipher
getInstance(java.lang.String transformation)
Returns a Cipher
object that implements the specified
transformation.
- static
- Cipher
getInstance(java.lang.String transformation,java.security.Provider provider)
Returns a Cipher
object that implements the specified
transformation.
- static
- Cipher
getInstance(java.lang.String transformation,java.lang.String provider)
Returns a Cipher
object that implements the specified
transformation.
- byte[]
getIV()
Returns the initialization vector (IV) in a new buffer.
- static
- int
getMaxAllowedKeyLength(java.lang.String transformation)
Returns the maximum key length for the specified transformation
according to the installed JCE jurisdiction policy files.
- static
- java.security.spec.AlgorithmParameterSpec
getMaxAllowedParameterSpec(java.lang.String transformation)
Returns an AlgorithmParameterSpec object which contains
the maximum cipher parameter value according to the
jurisdiction policy file.
- int
getOutputSize(int inputLen)
Returns the length in bytes that an output buffer would need to be in
order to hold the result of the next update
or
doFinal
operation, given the input length
inputLen
(in bytes).
- java.security.AlgorithmParameters
getParameters()
Returns the parameters used with this cipher.
- java.security.Provider
getProvider()
Returns the provider of this Cipher
object.
- void
init(int opmode,java.security.cert.Certificate certificate)
Initializes this cipher with the public key from the given certificate.
- void
init(int opmode,java.security.cert.Certificate certificate,java.security.SecureRandom random)
Initializes this cipher with the public key from the given certificate
and
a source of randomness.
- void
init(int opmode,java.security.Key key)
Initializes this cipher with a key.
- void
init(int opmode,java.security.Key key,java.security.AlgorithmParameters params)
Initializes this cipher with a key and a set of algorithm
parameters.
- void
init(int opmode,java.security.Key key,java.security.spec.AlgorithmParameterSpec params)
Initializes this cipher with a key and a set of algorithm
parameters.
- void
init(int opmode,java.security.Key key,java.security.spec.AlgorithmParameterSpec params,java.security.SecureRandom random)
Initializes this cipher with a key, a set of algorithm
parameters, and a source of randomness.
- void
init(int opmode,java.security.Key key,java.security.AlgorithmParameters params,java.security.SecureRandom random)
Initializes this cipher with a key, a set of algorithm
parameters, and a source of randomness.
- void
init(int opmode,java.security.Key key,java.security.SecureRandom random)
Initializes this cipher with a key and a source of randomness.
- java.security.Key
unwrap(byte[] wrappedKey,java.lang.String wrappedKeyAlgorithm,int wrappedKeyType)
Unwrap a previously wrapped key.
- byte[]
update(byte[] input)
Continues a multiple-part encryption or decryption operation
(depending on how this cipher was initialized), processing another data
part.
- byte[]
update(byte[] input,int inputOffset,int inputLen)
Continues a multiple-part encryption or decryption operation
(depending on how this cipher was initialized), processing another data
part.
- int
update(byte[] input,int inputOffset,int inputLen,byte[] output)
Continues a multiple-part encryption or decryption operation
(depending on how this cipher was initialized), processing another data
part.
- int
update(byte[] input,int inputOffset,int inputLen,byte[] output,int outputOffset)
Continues a multiple-part encryption or decryption operation
(depending on how this cipher was initialized), processing another data
part.
- int
update(java.nio.ByteBuffer input,java.nio.ByteBuffer output)
Continues a multiple-part encryption or decryption operation
(depending on how this cipher was initialized), processing another data
part.
- byte[]
wrap(java.security.Key key)
Wrap 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 used to initialize cipher to encryption mode.
See Also:
DECRYPT_MODE
- public static final int DECRYPT_MODE
Constant used to initialize cipher to decryption mode.
See Also:
WRAP_MODE
- public static final int WRAP_MODE
Constant used to initialize cipher to key-wrapping mode.
See Also:
UNWRAP_MODE
- public static final int UNWRAP_MODE
Constant used to initialize cipher to key-unwrapping mode.
See Also:
PUBLIC_KEY
- public static final int PUBLIC_KEY
Constant used to indicate the to-be-unwrapped key is a "public key".
See Also:
PRIVATE_KEY
- public static final int PRIVATE_KEY
Constant used to indicate the to-be-unwrapped key is a "private key".
See Also:
SECRET_KEY
- public static final int SECRET_KEY
Constant used to indicate the to-be-unwrapped key is a "secret key".
See Also:
Constructor Detail
Cipher
- protected Cipher(CipherSpi cipherSpi,
- java.security.Provider provider,
- java.lang.String transformation)
Creates a Cipher object.
Parameters:
cipherSpi
- the delegate
provider
- the provider
transformation
- the transformation
Method Detail
getInstance
- public static final Cipher getInstance(
java.lang.String transformation)
- throws java.security.NoSuchAlgorithmException
- NoSuchPaddingException
Returns a Cipher
object that implements the specified
transformation.
This method traverses the list of registered security Providers,
starting with the most preferred Provider.
A new Cipher object encapsulating the
CipherSpi implementation from the first
Provider that supports the specified algorithm is returned.
Note that the list of registered providers may be retrieved via
the Security.getProviders()
method.
Parameters:
transformation
- the name of the transformation, e.g.,
DES/CBC/PKCS5Padding.
See Appendix A in the
Java Cryptography Extension Reference Guide
for information about standard transformation names.
Returns:
a cipher that implements the requested transformation.
Throws:
java.security.NoSuchAlgorithmException
- if transformation
is null, empty, in an invalid format,
or if no Provider supports a CipherSpi implementation for the
specified algorithm.
NoSuchPaddingException
- if transformation
contains a padding scheme that is not available.
See Also:
Provider
getInstance
- public static final Cipher getInstance(
java.lang.String transformation,
- java.lang.String provider)
- throws java.security.NoSuchAlgorithmException
- java.security.NoSuchProviderException
- NoSuchPaddingException
Returns a Cipher
object that implements the specified
transformation.
A new Cipher object encapsulating the
CipherSpi implementation from the specified provider
is returned. The specified provider must be registered
in the security provider list.
Note that the list of registered providers may be retrieved via
the Security.getProviders()
method.
Parameters:
transformation
- the name of the transformation,
e.g., DES/CBC/PKCS5Padding.
See Appendix A in the
Java Cryptography Extension Reference Guide
for information about standard transformation names.
provider
- the name of the provider.
Returns:
a cipher that implements the requested transformation.
Throws:
java.security.NoSuchAlgorithmException
- if transformation
is null, empty, in an invalid format,
or if a CipherSpi implementation for the specified algorithm
is not available from the specified provider.
java.security.NoSuchProviderException
- if the specified provider is not
registered in the security provider list.
NoSuchPaddingException
- if transformation
contains a padding scheme that is not available.
java.lang.IllegalArgumentException
- if the provider
is null or empty.
See Also:
Provider
getInstance
- public static final Cipher getInstance(
java.lang.String transformation,
- java.security.Provider provider)
- throws java.security.NoSuchAlgorithmException
- NoSuchPaddingException
Returns a Cipher
object that implements the specified
transformation.
A new Cipher object encapsulating the
CipherSpi implementation from the specified Provider
object is returned. Note that the specified Provider object
does not have to be registered in the provider list.
Parameters:
transformation
- the name of the transformation,
e.g., DES/CBC/PKCS5Padding.
See Appendix A in the
Java Cryptography Extension Reference Guide
for information about standard transformation names.
provider
- the provider.
Returns:
a cipher that implements the requested transformation.
Throws:
java.security.NoSuchAlgorithmException
- if transformation
is null, empty, in an invalid format,
or if a CipherSpi implementation for the specified algorithm
is not available from the specified Provider object.
NoSuchPaddingException
- if transformation
contains a padding scheme that is not available.
java.lang.IllegalArgumentException
- if the provider
is null.
See Also:
Provider
getProvider
- public final java.security.Provider getProvider(
)
Returns the provider of this Cipher
object.
Returns:
the provider of this Cipher
object
getAlgorithm
- public final java.lang.String getAlgorithm(
)
Returns the algorithm name of this Cipher
object.
This is the same name that was specified in one of the
getInstance
calls that created this Cipher
object..
Returns:
the algorithm name of this Cipher
object.
getBlockSize
- public final int getBlockSize()
Returns the block size (in bytes).
Returns:
the block size (in bytes), or 0 if the underlying algorithm is
not a block cipher
getOutputSize
- public final int getOutputSize(
int inputLen)
Returns the length in bytes that an output buffer would need to be in
order to hold the result of the next update
or
doFinal
operation, given the input length
inputLen
(in bytes).
This call takes into account any unprocessed (buffered) data from a
previous update
call, and padding.
The actual output length of the next update
or
doFinal
call may be smaller than the length returned by
this method.
Parameters:
inputLen
- the input length (in bytes)
Returns:
the required output buffer size (in bytes)
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not yet been initialized)
getIV
- public final byte[] getIV()
Returns the initialization vector (IV) in a new buffer.
This is useful in the case where a random IV was created,
or in the context of password-based encryption or
decryption, where the IV is derived from a user-supplied password.
Returns:
the initialization vector in a new buffer, or null if the
underlying algorithm does not use an IV, or if the IV has not yet
been set.
getParameters
- public final java.security.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 a combination of default and random
parameter values used by the underlying cipher implementation if this
cipher requires algorithm parameters but was not initialized with any.
Returns:
the parameters used with this cipher, or null if this cipher
does not use any parameters.
getExemptionMechanism
- public final ExemptionMechanism getExemptionMechanism(
)
Returns the exemption mechanism object used with this cipher.
Returns:
the exemption mechanism object used with this cipher, or
null if this cipher does not use any exemption mechanism.
init
- public final void init(int opmode,
- java.security.Key key)
- throws java.security.InvalidKeyException
Initializes this cipher with a key.
The cipher is initialized for one of the following four operations:
encryption, decryption, key wrapping or key unwrapping, depending
on the value of opmode
.
If this cipher requires any algorithm parameters that cannot be
derived from the given key
, the underlying cipher
implementation is supposed to generate the required parameters itself
(using provider-specific default or random values) if it is being
initialized for encryption or key wrapping, and raise an
InvalidKeyException
if it is being
initialized for decryption or key unwrapping.
The generated parameters can be retrieved using
getParameters
or
getIV
(if the parameter is an IV).
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes (e.g., for parameter generation), it will get
them using the SecureRandom
implementation of the highest-priority
installed provider as the source of randomness.
(If none of the installed providers supply an implementation of
SecureRandom, a system-provided source of randomness will be used.)
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 one of
the following:
ENCRYPT_MODE
, DECRYPT_MODE
,
WRAP_MODE
or UNWRAP_MODE
)
key
- the key
Throws:
java.security.InvalidKeyException
- if the given key is inappropriate for
initializing this cipher, or if this cipher is being initialized for
decryption and requires algorithm parameters that cannot be
determined from the given key, or if the given key has a keysize that
exceeds the maximum allowable keysize (as determined from the
configured jurisdiction policy files).
init
- public final void init(int opmode,
- java.security.Key key,
- java.security.SecureRandom random)
- throws java.security.InvalidKeyException
Initializes this cipher with a key and a source of randomness.
The cipher is initialized for one of the following four operations:
encryption, decryption, key wrapping or key unwrapping, depending
on the value of opmode
.
If this cipher requires any algorithm parameters that cannot be
derived from the given key
, the underlying cipher
implementation is supposed to generate the required parameters itself
(using provider-specific default or random values) if it is being
initialized for encryption or key wrapping, and raise an
InvalidKeyException
if it is being
initialized for decryption or key unwrapping.
The generated parameters can be retrieved using
getParameters
or
getIV
(if the parameter is an IV).
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes (e.g., for parameter generation), 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 one of the
following:
ENCRYPT_MODE
, DECRYPT_MODE
,
WRAP_MODE
or UNWRAP_MODE
)
key
- the encryption key
random
- the source of randomness
Throws:
java.security.InvalidKeyException
- if the given key is inappropriate for
initializing this cipher, or if this cipher is being initialized for
decryption and requires algorithm parameters that cannot be
determined from the given key, or if the given key has a keysize that
exceeds the maximum allowable keysize (as determined from the
configured jurisdiction policy files).
init
- public final void init(int opmode,
- java.security.Key key,
- java.security.spec.AlgorithmParameterSpec params)
- throws java.security.InvalidKeyException
- java.security.InvalidAlgorithmParameterException
Initializes this cipher with a key and a set of algorithm
parameters.
The cipher is initialized for one of the following four operations:
encryption, decryption, key wrapping or key unwrapping, depending
on the value of opmode
.
If this cipher requires any algorithm parameters and
params
is null, the underlying cipher implementation is
supposed to generate the required parameters itself (using
provider-specific default or random values) if it is being
initialized for encryption or key wrapping, and raise an
InvalidAlgorithmParameterException
if it is being
initialized for decryption or key unwrapping.
The generated parameters can be retrieved using
getParameters
or
getIV
(if the parameter is an IV).
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes (e.g., for parameter generation), it will get
them using the SecureRandom
implementation of the highest-priority
installed provider as the source of randomness.
(If none of the installed providers supply an implementation of
SecureRandom, a system-provided source of randomness will be used.)
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 one of the
following:
ENCRYPT_MODE
, DECRYPT_MODE
,
WRAP_MODE
or UNWRAP_MODE
)
key
- the encryption key
params
- the algorithm parameters
Throws:
java.security.InvalidKeyException
- if the given key is inappropriate for
initializing this cipher, or its keysize exceeds the maximum allowable
keysize (as determined from the configured jurisdiction policy files).
java.security.InvalidAlgorithmParameterException
- if the given algorithm
parameters are inappropriate for this cipher,
or this cipher is being initialized for decryption and requires
algorithm parameters and params
is null, or the given
algorithm parameters imply a cryptographic strength that would exceed
the legal limits (as determined from the configured jurisdiction
policy files).
init
- public final void init(int opmode,
- java.security.Key key,
- java.security.spec.AlgorithmParameterSpec params,
- java.security.SecureRandom random)
- throws java.security.InvalidKeyException
- java.security.InvalidAlgorithmParameterException
Initializes this cipher with a key, a set of algorithm
parameters, and a source of randomness.
The cipher is initialized for one of the following four operations:
encryption, decryption, key wrapping or key unwrapping, depending
on the value of opmode
.
If this cipher requires any algorithm parameters and
params
is null, the underlying cipher implementation is
supposed to generate the required parameters itself (using
provider-specific default or random values) if it is being
initialized for encryption or key wrapping, and raise an
InvalidAlgorithmParameterException
if it is being
initialized for decryption or key unwrapping.
The generated parameters can be retrieved using
getParameters
or
getIV
(if the parameter is an IV).
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes (e.g., for parameter generation), 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 one of the
following:
ENCRYPT_MODE
, DECRYPT_MODE
,
WRAP_MODE
or UNWRAP_MODE
)
key
- the encryption key
params
- the algorithm parameters
random
- the source of randomness
Throws:
java.security.InvalidKeyException
- if the given key is inappropriate for
initializing this cipher, or its keysize exceeds the maximum allowable
keysize (as determined from the configured jurisdiction policy files).
java.security.InvalidAlgorithmParameterException
- if the given algorithm
parameters are inappropriate for this cipher,
or this cipher is being initialized for decryption and requires
algorithm parameters and params
is null, or the given
algorithm parameters imply a cryptographic strength that would exceed
the legal limits (as determined from the configured jurisdiction
policy files).
init
- public final void init(int opmode,
- java.security.Key key,
- java.security.AlgorithmParameters params)
- throws java.security.InvalidKeyException
- java.security.InvalidAlgorithmParameterException
Initializes this cipher with a key and a set of algorithm
parameters.
The cipher is initialized for one of the following four operations:
encryption, decryption, key wrapping or key unwrapping, depending
on the value of opmode
.
If this cipher requires any algorithm parameters and
params
is null, the underlying cipher implementation is
supposed to generate the required parameters itself (using
provider-specific default or random values) if it is being
initialized for encryption or key wrapping, and raise an
InvalidAlgorithmParameterException
if it is being
initialized for decryption or key unwrapping.
The generated parameters can be retrieved using
getParameters
or
getIV
(if the parameter is an IV).
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes (e.g., for parameter generation), it will get
them using the SecureRandom
implementation of the highest-priority
installed provider as the source of randomness.
(If none of the installed providers supply an implementation of
SecureRandom, a system-provided source of randomness will be used.)
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 one of the
following: ENCRYPT_MODE
,
DECRYPT_MODE
, WRAP_MODE
or UNWRAP_MODE
)
key
- the encryption key
params
- the algorithm parameters
Throws:
java.security.InvalidKeyException
- if the given key is inappropriate for
initializing this cipher, or its keysize exceeds the maximum allowable
keysize (as determined from the configured jurisdiction policy files).
java.security.InvalidAlgorithmParameterException
- if the given algorithm
parameters are inappropriate for this cipher,
or this cipher is being initialized for decryption and requires
algorithm parameters and params
is null, or the given
algorithm parameters imply a cryptographic strength that would exceed
the legal limits (as determined from the configured jurisdiction
policy files).
init
- public final void init(int opmode,
- java.security.Key key,
- java.security.AlgorithmParameters params,
- java.security.SecureRandom random)
- throws java.security.InvalidKeyException
- java.security.InvalidAlgorithmParameterException
Initializes this cipher with a key, a set of algorithm
parameters, and a source of randomness.
The cipher is initialized for one of the following four operations:
encryption, decryption, key wrapping or key unwrapping, depending
on the value of opmode
.
If this cipher requires any algorithm parameters and
params
is null, the underlying cipher implementation is
supposed to generate the required parameters itself (using
provider-specific default or random values) if it is being
initialized for encryption or key wrapping, and raise an
InvalidAlgorithmParameterException
if it is being
initialized for decryption or key unwrapping.
The generated parameters can be retrieved using
getParameters
or
getIV
(if the parameter is an IV).
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes (e.g., for parameter generation), 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 one of the
following: ENCRYPT_MODE
,
DECRYPT_MODE
, WRAP_MODE
or UNWRAP_MODE
)
key
- the encryption key
params
- the algorithm parameters
random
- the source of randomness
Throws:
java.security.InvalidKeyException
- if the given key is inappropriate for
initializing this cipher, or its keysize exceeds the maximum allowable
keysize (as determined from the configured jurisdiction policy files).
java.security.InvalidAlgorithmParameterException
- if the given algorithm
parameters are inappropriate for this cipher,
or this cipher is being initialized for decryption and requires
algorithm parameters and params
is null, or the given
algorithm parameters imply a cryptographic strength that would exceed
the legal limits (as determined from the configured jurisdiction
policy files).
init
- public final void init(int opmode,
- java.security.cert.Certificate certificate)
- throws java.security.InvalidKeyException
Initializes this cipher with the public key from the given certificate.
The cipher is initialized for one of the following four operations:
encryption, decryption, key wrapping or key unwrapping, depending
on the value of opmode
.
If the certificate is of type X.509 and has a key usage
extension field marked as critical, and the value of the key usage
extension field implies that the public key in
the certificate and its corresponding private key are not
supposed to be used for the operation represented by the value
of opmode
,
an InvalidKeyException
is thrown.
If this cipher requires any algorithm parameters that cannot be
derived from the public key in the given certificate, the underlying
cipher
implementation is supposed to generate the required parameters itself
(using provider-specific default or ramdom values) if it is being
initialized for encryption or key wrapping, and raise an
InvalidKeyException
if it is being initialized for decryption or
key unwrapping.
The generated parameters can be retrieved using
getParameters
or
getIV
(if the parameter is an IV).
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes (e.g., for parameter generation), it will get
them using the
SecureRandom
implementation of the highest-priority
installed provider as the source of randomness.
(If none of the installed providers supply an implementation of
SecureRandom, a system-provided source of randomness will be used.)
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 one of the
following:
ENCRYPT_MODE
, DECRYPT_MODE
,
WRAP_MODE
or UNWRAP_MODE
)
certificate
- the certificate
Throws:
java.security.InvalidKeyException
- if the public key in the given
certificate is inappropriate for initializing this cipher, or this
cipher is being initialized for decryption or unwrapping keys and
requires algorithm parameters that cannot be determined from the
public key in the given certificate, or the keysize of the public key
in the given certificate has a keysize that exceeds the maximum
allowable keysize (as determined by the configured jurisdiction policy
files).
init
- public final void init(int opmode,
- java.security.cert.Certificate certificate,
- java.security.SecureRandom random)
- throws java.security.InvalidKeyException
Initializes this cipher with the public key from the given certificate
and
a source of randomness.
The cipher is initialized for one of the following four operations:
encryption, decryption, key wrapping
or key unwrapping, depending on
the value of opmode
.
If the certificate is of type X.509 and has a key usage
extension field marked as critical, and the value of the key usage
extension field implies that the public key in
the certificate and its corresponding private key are not
supposed to be used for the operation represented by the value of
opmode
,
an InvalidKeyException
is thrown.
If this cipher requires any algorithm parameters that cannot be
derived from the public key in the given certificate
,
the underlying cipher
implementation is supposed to generate the required parameters itself
(using provider-specific default or random values) if it is being
initialized for encryption or key wrapping, and raise an
InvalidKeyException
if it is being
initialized for decryption or key unwrapping.
The generated parameters can be retrieved using
getParameters
or
getIV
(if the parameter is an IV).
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes (e.g., for parameter generation), 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 one of the
following:
ENCRYPT_MODE
, DECRYPT_MODE
,
WRAP_MODE
or UNWRAP_MODE
)
certificate
- the certificate
random
- the source of randomness
Throws:
java.security.InvalidKeyException
- if the public key in the given
certificate is inappropriate for initializing this cipher, or this
cipher is being initialized for decryption or unwrapping keys and
requires algorithm parameters that cannot be determined from the
public key in the given certificate, or the keysize of the public key
in the given certificate has a keysize that exceeds the maximum
allowable keysize (as determined by the configured jurisdiction policy
files).
update
- public final byte[] update(byte[] input)
Continues a multiple-part encryption or decryption operation
(depending on how this cipher was initialized), processing another data
part.
The bytes in the input
buffer are processed, and the
result is stored in a new buffer.
If input
has a length of zero, this method returns
null
.
Parameters:
input
- the input buffer
Returns:
the new buffer with the result, or null if the underlying
cipher is a block cipher and the input data is too short to result in a
new block.
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized)
update
- public final byte[] update(byte[] input,
- int inputOffset,
- int inputLen)
Continues a multiple-part encryption or decryption operation
(depending on how this cipher was initialized), processing another data
part.
The first inputLen
bytes in the input
buffer, starting at inputOffset
inclusive, are processed,
and the result is stored in a new buffer.
If inputLen
is zero, this method returns
null
.
Parameters:
input
- the input buffer
inputOffset
- the offset in input
where the input
starts
inputLen
- the input length
Returns:
the new buffer with the result, or null if the underlying
cipher is a block cipher and the input data is too short to result in a
new block.
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized)
update
- public final int update(byte[] input,
- int inputOffset,
- int inputLen,
- byte[] output)
- throws ShortBufferException
Continues a multiple-part encryption or decryption operation
(depending on how this cipher was initialized), processing another data
part.
The first inputLen
bytes in the input
buffer, starting at inputOffset
inclusive, are processed,
and the result is stored in the output
buffer.
If the output
buffer is too small to hold the result,
a ShortBufferException
is thrown. In this case, repeat this
call with a larger output buffer. Use
getOutputSize
to determine how big
the output buffer should be.
If inputLen
is zero, this method returns
a length of zero.
Note: this method should be copy-safe, which means the
input
and output
buffers can reference
the same byte array and no unprocessed input data is overwritten
when the result is copied into the output buffer.
Parameters:
input
- the input buffer
inputOffset
- the offset in input
where the input
starts
inputLen
- the input length
output
- the buffer for the result
Returns:
the number of bytes stored in output
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized)
ShortBufferException
- if the given output buffer is too small
to hold the result
update
- public final int update(byte[] input,
- int inputOffset,
- int inputLen,
- byte[] output,
- int outputOffset)
- throws ShortBufferException
Continues a multiple-part encryption or decryption operation
(depending on how this cipher was initialized), processing another data
part.
The first inputLen
bytes in the input
buffer, starting at inputOffset
inclusive, are processed,
and the result is stored in the output
buffer, starting at
outputOffset
inclusive.
If the output
buffer is too small to hold the result,
a ShortBufferException
is thrown. In this case, repeat this
call with a larger output buffer. Use
getOutputSize
to determine how big
the output buffer should be.
If inputLen
is zero, this method returns
a length of zero.
Note: this method should be copy-safe, which means the
input
and output
buffers can reference
the same byte array and no unprocessed input data is overwritten
when the result is copied into the output buffer.
Parameters:
input
- the input buffer
inputOffset
- the offset in input
where the input
starts
inputLen
- the input length
output
- the buffer for the result
outputOffset
- the offset in output
where the result
is stored
Returns:
the number of bytes stored in output
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized)
ShortBufferException
- if the given output buffer is too small
to hold the result
update
- public final int update(java.nio.ByteBuffer input,
- java.nio.ByteBuffer output)
- throws ShortBufferException
Continues a multiple-part encryption or decryption operation
(depending on how this cipher was initialized), processing another data
part.
All input.remaining()
bytes starting at
input.position()
are processed. The result is stored
in the output buffer.
Upon return, the input buffer's position will be equal
to its limit; its limit will not have changed. The output buffer's
position will have advanced by n, where n is the value returned
by this method; the output buffer's limit will not have changed.
If output.remaining()
bytes are insufficient to
hold the result, a ShortBufferException
is thrown.
In this case, repeat this call with a larger output buffer. Use
getOutputSize
to determine how big
the output buffer should be.
Note: this method should be copy-safe, which means the
input
and output
buffers can reference
the same block of memory and no unprocessed input data is overwritten
when the result is copied into the output buffer.
Parameters:
input
- the input ByteBuffer
output
- the output ByteByffer
Returns:
the number of bytes stored in output
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized)
java.lang.IllegalArgumentException
- if input and output are the
same object
java.nio.ReadOnlyBufferException
- if the output buffer is read-only
ShortBufferException
- if there is insufficient space in the
output buffer
Since:
1.5
doFinal
- public final byte[] doFinal()
- throws IllegalBlockSizeException
- BadPaddingException
Finishes a multiple-part encryption or decryption operation, depending
on how this cipher was initialized.
Input data that may have been buffered during a previous
update
operation is processed, with padding (if requested)
being applied.
The result is stored in a new buffer.
Upon finishing, this method resets this cipher object to the state
it was in when previously initialized via a call to init
.
That is, the object is reset and available to encrypt or decrypt
(depending on the operation mode that was specified in the call to
init
) more data.
Note: if any exception is thrown, this cipher object may need to
be reset before it can be used again.
Returns:
the new buffer with the result
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized)
IllegalBlockSizeException
- if this cipher is a block cipher,
no padding has been requested (only in encryption mode), and the total
input length of the data processed by this cipher is not a multiple of
block size; or if this encryption algorithm is unable to
process the input data provided.
BadPaddingException
- if this cipher is in decryption mode,
and (un)padding has been requested, but the decrypted data is not
bounded by the appropriate padding bytes
doFinal
- public final int doFinal(byte[] output,
- int outputOffset)
- throws IllegalBlockSizeException
- ShortBufferException
- BadPaddingException
Finishes a multiple-part encryption or decryption operation, depending
on how this cipher was initialized.
Input data that may have been buffered during a previous
update
operation is processed, with padding (if requested)
being applied.
The result is stored in the output
buffer, starting at
outputOffset
inclusive.
If the output
buffer is too small to hold the result,
a ShortBufferException
is thrown. In this case, repeat this
call with a larger output buffer. Use
getOutputSize
to determine how big
the output buffer should be.
Upon finishing, this method resets this cipher object to the state
it was in when previously initialized via a call to init
.
That is, the object is reset and available to encrypt or decrypt
(depending on the operation mode that was specified in the call to
init
) more data.
Note: if any exception is thrown, this cipher object may need to
be reset before it can be used again.
Parameters:
output
- the buffer for the result
outputOffset
- the offset in output
where the result
is stored
Returns:
the number of bytes stored in output
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized)
IllegalBlockSizeException
- if this cipher is a block cipher,
no padding has been requested (only in encryption mode), and the total
input length of the data processed by this cipher is not a multiple of
block size; or if this encryption algorithm is unable to
process the input data provided.
ShortBufferException
- if the given output buffer is too small
to hold the result
BadPaddingException
- if this cipher is in decryption mode,
and (un)padding has been requested, but the decrypted data is not
bounded by the appropriate padding bytes
doFinal
- public final byte[] doFinal(byte[] input)
- throws IllegalBlockSizeException
- BadPaddingException
Encrypts or decrypts data in a single-part operation, or finishes a
multiple-part operation. The data is encrypted or decrypted,
depending on how this cipher was initialized.
The bytes in the input
buffer, and any input bytes that
may have been buffered during a previous update
operation,
are processed, with padding (if requested) being applied.
The result is stored in a new buffer.
Upon finishing, this method resets this cipher object to the state
it was in when previously initialized via a call to init
.
That is, the object is reset and available to encrypt or decrypt
(depending on the operation mode that was specified in the call to
init
) more data.
Note: if any exception is thrown, this cipher object may need to
be reset before it can be used again.
Parameters:
input
- the input buffer
Returns:
the new buffer with the result
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized)
IllegalBlockSizeException
- if this cipher is a block cipher,
no padding has been requested (only in encryption mode), and the total
input length of the data processed by this cipher is not a multiple of
block size; or if this encryption algorithm is unable to
process the input data provided.
BadPaddingException
- if this cipher is in decryption mode,
and (un)padding has been requested, but the decrypted data is not
bounded by the appropriate padding bytes
doFinal
- public final byte[] doFinal(byte[] input,
- int inputOffset,
- int inputLen)
- throws IllegalBlockSizeException
- BadPaddingException
Encrypts or decrypts data in a single-part operation, or finishes a
multiple-part operation. The data is encrypted or decrypted,
depending on how this cipher was initialized.
The first inputLen
bytes in the input
buffer, starting at inputOffset
inclusive, and any input
bytes that may have been buffered during a previous update
operation, are processed, with padding (if requested) being applied.
The result is stored in a new buffer.
Upon finishing, this method resets this cipher object to the state
it was in when previously initialized via a call to init
.
That is, the object is reset and available to encrypt or decrypt
(depending on the operation mode that was specified in the call to
init
) more data.
Note: if any exception is thrown, this cipher object may need to
be reset before it can be used again.
Parameters:
input
- the input buffer
inputOffset
- the offset in input
where the input
starts
inputLen
- the input length
Returns:
the new buffer with the result
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized)
IllegalBlockSizeException
- if this cipher is a block cipher,
no padding has been requested (only in encryption mode), and the total
input length of the data processed by this cipher is not a multiple of
block size; or if this encryption algorithm is unable to
process the input data provided.
BadPaddingException
- if this cipher is in decryption mode,
and (un)padding has been requested, but the decrypted data is not
bounded by the appropriate padding bytes
doFinal
- public final int doFinal(byte[] input,
- int inputOffset,
- int inputLen,
- byte[] output)
- throws ShortBufferException
- IllegalBlockSizeException
- BadPaddingException
Encrypts or decrypts data in a single-part operation, or finishes a
multiple-part operation. The data is encrypted or decrypted,
depending on how this cipher was initialized.
The first inputLen
bytes in the input
buffer, starting at inputOffset
inclusive, and any input
bytes that may have been buffered during a previous update
operation, are processed, with padding (if requested) being applied.
The result is stored in the output
buffer.
If the output
buffer is too small to hold the result,
a ShortBufferException
is thrown. In this case, repeat this
call with a larger output buffer. Use
getOutputSize
to determine how big
the output buffer should be.
Upon finishing, this method resets this cipher object to the state
it was in when previously initialized via a call to init
.
That is, the object is reset and available to encrypt or decrypt
(depending on the operation mode that was specified in the call to
init
) more data.
Note: if any exception is thrown, this cipher object may need to
be reset before it can be used again.
Note: this method should be copy-safe, which means the
input
and output
buffers can reference
the same byte array and no unprocessed input data is overwritten
when the result is copied into the output buffer.
Parameters:
input
- the input buffer
inputOffset
- the offset in input
where the input
starts
inputLen
- the input length
output
- the buffer for the result
Returns:
the number of bytes stored in output
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized)
IllegalBlockSizeException
- if this cipher is a block cipher,
no padding has been requested (only in encryption mode), and the total
input length of the data processed by this cipher is not a multiple of
block size; or if this encryption algorithm is unable to
process the input data provided.
ShortBufferException
- if the given output buffer is too small
to hold the result
BadPaddingException
- if this cipher is in decryption mode,
and (un)padding has been requested, but the decrypted data is not
bounded by the appropriate padding bytes
doFinal
- public final int doFinal(byte[] input,
- int inputOffset,
- int inputLen,
- byte[] output,
- int outputOffset)
- throws ShortBufferException
- IllegalBlockSizeException
- BadPaddingException
Encrypts or decrypts data in a single-part operation, or finishes a
multiple-part operation. The data is encrypted or decrypted,
depending on how this cipher was initialized.
The first inputLen
bytes in the input
buffer, starting at inputOffset
inclusive, and any input
bytes that may have been buffered during a previous
update
operation, are processed, with padding
(if requested) being applied.
The result is stored in the output
buffer, starting at
outputOffset
inclusive.
If the output
buffer is too small to hold the result,
a ShortBufferException
is thrown. In this case, repeat this
call with a larger output buffer. Use
getOutputSize
to determine how big
the output buffer should be.
Upon finishing, this method resets this cipher object to the state
it was in when previously initialized via a call to init
.
That is, the object is reset and available to encrypt or decrypt
(depending on the operation mode that was specified in the call to
init
) more data.
Note: if any exception is thrown, this cipher object may need to
be reset before it can be used again.
Note: this method should be copy-safe, which means the
input
and output
buffers can reference
the same byte array and no unprocessed input data is overwritten
when the result is copied into the output buffer.
Parameters:
input
- the input buffer
inputOffset
- the offset in input
where the input
starts
inputLen
- the input length
output
- the buffer for the result
outputOffset
- the offset in output
where the result
is stored
Returns:
the number of bytes stored in output
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized)
IllegalBlockSizeException
- if this cipher is a block cipher,
no padding has been requested (only in encryption mode), and the total
input length of the data processed by this cipher is not a multiple of
block size; or if this encryption algorithm is unable to
process the input data provided.
ShortBufferException
- if the given output buffer is too small
to hold the result
BadPaddingException
- if this cipher is in decryption mode,
and (un)padding has been requested, but the decrypted data is not
bounded by the appropriate padding bytes
doFinal
- public final int doFinal(java.nio.ByteBuffer input,
- java.nio.ByteBuffer output)
- throws ShortBufferException
- IllegalBlockSizeException
- BadPaddingException
Encrypts or decrypts data in a single-part operation, or finishes a
multiple-part operation. The data is encrypted or decrypted,
depending on how this cipher was initialized.
All input.remaining()
bytes starting at
input.position()
are processed. The result is stored
in the output buffer.
Upon return, the input buffer's position will be equal
to its limit; its limit will not have changed. The output buffer's
position will have advanced by n, where n is the value returned
by this method; the output buffer's limit will not have changed.
If output.remaining()
bytes are insufficient to
hold the result, a ShortBufferException
is thrown.
In this case, repeat this call with a larger output buffer. Use
getOutputSize
to determine how big
the output buffer should be.
Upon finishing, this method resets this cipher object to the state
it was in when previously initialized via a call to init
.
That is, the object is reset and available to encrypt or decrypt
(depending on the operation mode that was specified in the call to
init
) more data.
Note: if any exception is thrown, this cipher object may need to
be reset before it can be used again.
Note: this method should be copy-safe, which means the
input
and output
buffers can reference
the same byte array and no unprocessed input data is overwritten
when the result is copied into the output buffer.
Parameters:
input
- the input ByteBuffer
output
- the output ByteBuffer
Returns:
the number of bytes stored in output
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized)
java.lang.IllegalArgumentException
- if input and output are the
same object
java.nio.ReadOnlyBufferException
- if the output buffer is read-only
IllegalBlockSizeException
- if this cipher is a block cipher,
no padding has been requested (only in encryption mode), and the total
input length of the data processed by this cipher is not a multiple of
block size; or if this encryption algorithm is unable to
process the input data provided.
ShortBufferException
- if there is insufficient space in the
output buffer
BadPaddingException
- if this cipher is in decryption mode,
and (un)padding has been requested, but the decrypted data is not
bounded by the appropriate padding bytes
Since:
1.5
wrap
- public final byte[] wrap(java.security.Key key)
- throws IllegalBlockSizeException
- java.security.InvalidKeyException
Wrap a key.
Parameters:
key
- the key to be wrapped.
Returns:
the wrapped key.
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong
state (e.g., has not been initialized).
IllegalBlockSizeException
- if this cipher is a block
cipher, no padding has been requested, and the length of the
encoding of the key to be wrapped is not a
multiple of the block size.
java.security.InvalidKeyException
- if it is impossible or unsafe to
wrap the key with this cipher (e.g., a hardware protected key is
being passed to a software-only cipher).
unwrap
- public final java.security.Key unwrap(
byte[] wrappedKey,
- java.lang.String wrappedKeyAlgorithm,
- int wrappedKeyType)
- throws java.security.InvalidKeyException
- java.security.NoSuchAlgorithmException
Unwrap a previously wrapped key.
Parameters:
wrappedKey
- the key to be unwrapped.
wrappedKeyAlgorithm
- the algorithm associated with the wrapped
key.
wrappedKeyType
- the type of the wrapped key. This must be one of
SECRET_KEY
, PRIVATE_KEY
, or
PUBLIC_KEY
.
Returns:
the unwrapped key.
Throws:
java.lang.IllegalStateException
- if this cipher is in a wrong state
(e.g., has not been initialized).
java.security.NoSuchAlgorithmException
- if no installed providers
can create keys of type wrappedKeyType
for the
wrappedKeyAlgorithm
.
java.security.InvalidKeyException
- if wrappedKey
does not
represent a wrapped key of type wrappedKeyType
for
the wrappedKeyAlgorithm
.
getMaxAllowedKeyLength
- public static final int getMaxAllowedKeyLength(
java.lang.String transformation)
- throws java.security.NoSuchAlgorithmException
Returns the maximum key length for the specified transformation
according to the installed JCE jurisdiction policy files. If
JCE unlimited strength jurisdiction policy files are installed,
Integer.MAX_VALUE will be returned.
For more information on default key size in JCE jurisdiction
policy files, please see appendix E in
JCE Reference Guide.
Parameters:
transformation
- the cipher transformation.
Returns:
the maximum key length in bits or Integer.MAX_VALUE.
Throws:
java.lang.NullPointerException
- if transformation
is null.
java.security.NoSuchAlgorithmException
- if transformation
is not a valid transformation, i.e. in the form of "algorithm" or
"algorithm/mode/padding".
Since:
1.5
getMaxAllowedParameterSpec
- public static final java.security.spec.AlgorithmParameterSpec getMaxAllowedParameterSpec(
java.lang.String transformation)
- throws java.security.NoSuchAlgorithmException
Returns an AlgorithmParameterSpec object which contains
the maximum cipher parameter value according to the
jurisdiction policy file. If JCE unlimited strength jurisdiction
policy files are installed or there is no maximum limit on the
parameters for the specified transformation in the policy file,
null will be returned.
Parameters:
transformation
- the cipher transformation.
Returns:
an AlgorithmParameterSpec which holds the maximum
value or null.
Throws:
java.lang.NullPointerException
- if transformation
is null.
java.security.NoSuchAlgorithmException
- if transformation
is not a valid transformation, i.e. in the form of "algorithm" or
"algorithm/mode/padding".
Since:
1.5