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.
java.security.KeyGenerator
,
SecretKey
Modifier and Type | Field and Description |
---|---|
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.
|
Modifier | Constructor and Description |
---|---|
protected |
Cipher(CipherSpi cipherSpi,
Provider provider,
String transformation)
Create a cipher.
|
Modifier and Type | Method and Description |
---|---|
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.
|
int |
doFinal(byte[] output,
int outputOffset)
Finishes a multi-part transformation and stores the transformed
bytes into the given array.
|
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[] input,
int inputOffset,
int inputLength,
byte[] output) |
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(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
#getInstance() methods. |
int |
getBlockSize()
Return the size of blocks, in bytes, that this cipher processes.
|
ExemptionMechanism |
getExemptionMechanism()
Return the currently-operating
ExemptionMechanism . |
static Cipher |
getInstance(String transformation)
Creates a new cipher instance for the given transformation.
|
static Cipher |
getInstance(String transformation,
Provider provider)
Creates a new cipher instance for a given transformation from a given
provider.
|
static Cipher |
getInstance(String transformation,
String provider)
Creates a new cipher instance for the given transformation and the named
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
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.
|
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.
|
void |
init(int opmode,
Key key)
Initialize this cipher with the supplied key.
|
void |
init(int opmode,
Key key,
AlgorithmParameters params)
Initialize this cipher with the supplied key and parameters.
|
void |
init(int opmode,
Key key,
AlgorithmParameterSpec params)
Initialize this cipher with the supplied key and parameters.
|
void |
init(int opmode,
Key key,
AlgorithmParameterSpec params,
SecureRandom random)
Initialize this cipher with the supplied key, parameters, and
source of randomness.
|
void |
init(int opmode,
Key key,
AlgorithmParameters params,
SecureRandom random)
Initialize this cipher with the supplied key, parameters, and
source of randomness.
|
void |
init(int opmode,
Key key,
SecureRandom random)
Initialize this cipher with the supplied key and source of
randomness.
|
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.
|
public static final int DECRYPT_MODE
public static final int ENCRYPT_MODE
public static final int PRIVATE_KEY
public static final int PUBLIC_KEY
public static final int SECRET_KEY
public static final int UNWRAP_MODE
public static final int WRAP_MODE
public static final Cipher getInstance(String transformation) throws NoSuchAlgorithmException, NoSuchPaddingException
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.
transformation
- The transformation to create.NoSuchAlgorithmException
- If no installed provider can supply the
appropriate cipher or mode.NoSuchPaddingException
- If no installed provider can supply the
appropriate padding.public static final Cipher getInstance(String transformation, String provider) throws NoSuchAlgorithmException, NoSuchProviderException, NoSuchPaddingException
transformation
- The transformation to create.provider
- The name of the provider to use.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
.public static final Cipher getInstance(String transformation, Provider provider) throws NoSuchAlgorithmException, NoSuchPaddingException
transformation
- The transformation to create.provider
- The provider to use.NoSuchAlgorithmException
- If the given provider cannot supply the
appropriate cipher or mode.NoSuchPaddingException
- If the given provider cannot supply the
appropriate padding scheme.public final String getAlgorithm()
#getInstance()
methods.public final int getBlockSize()
public final ExemptionMechanism getExemptionMechanism()
ExemptionMechanism
.public final byte[] getIV()
public final AlgorithmParameters getParameters()
AlgorithmParameters
that this
instance was initialized with.public final Provider getProvider()
public final byte[] doFinal() throws IllegalStateException, IllegalBlockSizeException, BadPaddingException
IllegalStateException
- If this instance has not
been initialized, or if a doFinal call has already
been made.IllegalBlockSizeException
- If this instance has
no padding and the input is not a multiple of this cipher's
block size.BadPaddingException
- If this instance is
decrypting and the padding bytes do not match this
instance's padding scheme.public final byte[] doFinal(byte[] input) throws IllegalStateException, IllegalBlockSizeException, BadPaddingException
input
- The final input bytes.IllegalStateException
- If this instance has not
been initialized, or if a doFinal call has already
been made.IllegalBlockSizeException
- If this instance has
no padding and the input is not a multiple of this cipher's
block size.BadPaddingException
- If this instance is
decrypting and the padding bytes do not match this
instance's padding scheme.public final byte[] doFinal(byte[] input, int inputOffset, int inputLength) throws IllegalStateException, IllegalBlockSizeException, BadPaddingException
input
- The final input bytes.inputOffset
- The index in the input bytes to start.inputLength
- The number of bytes to read from the input.IllegalStateException
- If this instance has not
been initialized, or if a doFinal call has already
been made.IllegalBlockSizeException
- If this instance has
no padding and the input is not a multiple of this cipher's
block size.BadPaddingException
- If this instance is
decrypting and the padding bytes do not match this
instance's padding scheme.public final int doFinal(byte[] output, int outputOffset) throws IllegalStateException, IllegalBlockSizeException, BadPaddingException, ShortBufferException
output
- The destination for the transformed bytes.outputOffset
- The offset in output to start storing
bytes.IllegalStateException
- If this instance has not
been initialized, or if a doFinal call has already
been made.IllegalBlockSizeException
- If this instance has
no padding and the input is not a multiple of this cipher's
block size.BadPaddingException
- If this instance is
decrypting and the padding bytes do not match this
instance's padding scheme.ShortBufferException
- If the output array is
not large enough to hold the transformed bytes.public final int doFinal(byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset) throws IllegalStateException, IllegalBlockSizeException, BadPaddingException, ShortBufferException
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.IllegalStateException
- If this instance has not
been initialized, or if a doFinal call has already
been made.IllegalBlockSizeException
- If this instance has
no padding and the input is not a multiple of this cipher's
block size.BadPaddingException
- If this instance is
decrypting and the padding bytes do not match this
instance's padding scheme.ShortBufferException
- If the output array is
not large enough to hold the transformed bytes.public final int doFinal(byte[] input, int inputOffset, int inputLength, byte[] output) throws IllegalStateException, IllegalBlockSizeException, BadPaddingException, ShortBufferException
public final int doFinal(ByteBuffer input, ByteBuffer output) throws ReadOnlyBufferException, ShortBufferException, BadPaddingException, IllegalBlockSizeException
input
- The input buffer.output
- The output buffer.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.public final int getOutputSize(int inputLength) throws IllegalStateException
inputLength
- The input length.IllegalStateException
- If this instance has not
been initialized, or if a doFinal call has already
been made.public final void init(int opmode, Certificate certificate) throws InvalidKeyException
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 ENCRYPT_MODE
, DECRYPT_MODE
, WRAP_MODE
, or UNWRAP_MODE
,
respectively.
As per the Java 1.4 specification, if cert
is an
instance of an X509Certificate
and its
key usage extension field is incompatible with
opmode
then an InvalidKeyException
is thrown.
If this cipher requires any random bytes (for example for an
initilization vector) than the 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.
opmode
- The operation mode to use.certificate
- The certificate.InvalidKeyException
- If the underlying cipher
instance rejects the certificate's public key, or if the
public key cannot be used as described above.public final void init(int opmode, Key key) throws InvalidKeyException
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 ENCRYPT_MODE
, DECRYPT_MODE
, WRAP_MODE
, or UNWRAP_MODE
,
respectively.
If this cipher requires any random bytes (for example for an
initilization vector) than the 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.
opmode
- The operation mode to use.key
- The key.InvalidKeyException
- If the underlying cipher
instance rejects the given key.public final void init(int opmode, Certificate certificate, SecureRandom random) throws InvalidKeyException
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 ENCRYPT_MODE
, DECRYPT_MODE
, WRAP_MODE
, or UNWRAP_MODE
,
respectively.
As per the Java 1.4 specification, if cert
is an
instance of an X509Certificate
and its
key usage extension field is incompatible with
opmode
then an InvalidKeyException
is thrown.
If this cipher requires any random bytes (for example for an
initilization vector) than the 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.
opmode
- The operation mode to use.certificate
- The certificate.random
- The source of randomness.InvalidKeyException
- If the underlying cipher
instance rejects the certificate's public key, or if the
public key cannot be used as described above.public final void init(int opmode, Key key, SecureRandom random) throws InvalidKeyException
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 ENCRYPT_MODE
, DECRYPT_MODE
, WRAP_MODE
, or 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.
opmode
- The operation mode to use.key
- The key.random
- The source of randomness to use.InvalidKeyException
- If the underlying cipher
instance rejects the given key.public final void init(int opmode, Key key, AlgorithmParameters params) throws InvalidKeyException, InvalidAlgorithmParameterException
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 ENCRYPT_MODE
, DECRYPT_MODE
, WRAP_MODE
, or UNWRAP_MODE
,
respectively.
If this cipher requires any random bytes (for example for an
initilization vector) then the 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.
opmode
- The operation mode to use.key
- The key.params
- The algorithm parameters to initialize this instance
with.InvalidKeyException
- If the underlying cipher
instance rejects the given key.InvalidAlgorithmParameterException
- If the
supplied parameters are inappropriate for this cipher.public final void init(int opmode, Key key, AlgorithmParameterSpec params) throws InvalidKeyException, InvalidAlgorithmParameterException
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 ENCRYPT_MODE
, DECRYPT_MODE
, WRAP_MODE
, or UNWRAP_MODE
,
respectively.
If this cipher requires any random bytes (for example for an
initilization vector) then the 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.
opmode
- The operation mode to use.key
- The key.params
- The algorithm parameters to initialize this instance
with.InvalidKeyException
- If the underlying cipher
instance rejects the given key.InvalidAlgorithmParameterException
- If the
supplied parameters are inappropriate for this cipher.public final void init(int opmode, Key key, AlgorithmParameters params, SecureRandom random) throws InvalidKeyException, InvalidAlgorithmParameterException
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 ENCRYPT_MODE
, DECRYPT_MODE
, WRAP_MODE
, or 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.
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.InvalidKeyException
- If the underlying cipher
instance rejects the given key.InvalidAlgorithmParameterException
- If the
supplied parameters are inappropriate for this cipher.public final void init(int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random) throws InvalidKeyException, InvalidAlgorithmParameterException
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 ENCRYPT_MODE
, DECRYPT_MODE
, WRAP_MODE
, or 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.
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.InvalidKeyException
- If the underlying cipher
instance rejects the given key.InvalidAlgorithmParameterException
- If the
supplied parameters are inappropriate for this cipher.public final Key unwrap(byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType) throws IllegalStateException, InvalidKeyException, NoSuchAlgorithmException
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.IllegalStateException
- If this instance has not be
initialized for unwrapping.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.NoSuchAlgorithmException
- If
wrappedKeyAlgorithm
is not a valid algorithm
name.public final byte[] update(byte[] input) throws IllegalStateException
input
- The input bytes.IllegalStateException
- If this cipher was not
initialized for encryption or decryption.public final byte[] update(byte[] input, int inputOffset, int inputLength) throws IllegalStateException
input
- The input bytes.inputOffset
- The index in the input to start.inputLength
- The number of bytes to transform.IllegalStateException
- If this cipher was not
initialized for encryption or decryption.public final int update(byte[] input, int inputOffset, int inputLength, byte[] output) throws IllegalStateException, ShortBufferException
input
- The input bytes.inputOffset
- The index in the input to start.inputLength
- The number of bytes to transform.output
- The output byte array.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.ShortBufferException
public final int update(byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset) throws IllegalStateException, ShortBufferException
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.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.ShortBufferException
public final int update(ByteBuffer input, ByteBuffer output) throws ReadOnlyBufferException, ShortBufferException
input
- The input buffer.output
- The output buffer.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.public final byte[] wrap(Key key) throws IllegalStateException, IllegalBlockSizeException, InvalidKeyException
key
- The key to wrap.IllegalStateException
- If this instance was not
initialized for key wrapping.IllegalBlockSizeException
- If this instance has
no padding and the key is not a multiple of the block size.InvalidKeyException
- If this instance cannot
wrap this key.