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:
- algorithm/mode/padding, or
- algorithm
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.
doFinal
public final byte[] doFinal(byte[] input,
int inputOffset,
int inputLength)
throws IllegalStateException,
IllegalBlockSizeException,
BadPaddingException
Finishes a multi-part transformation or does an entire
transformation on the input, and returns the transformed bytes.
input
- The final input bytes.inputOffset
- The index in the input bytes to start.inputLength
- The number of bytes to read from the input.
- The final transformed 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.
doFinal
public final int doFinal(byte[] input,
int inputOffset,
int inputLength,
byte[] output,
int outputOffset)
throws IllegalStateException,
IllegalBlockSizeException,
BadPaddingException,
ShortBufferException
Finishes a multi-part transformation or transforms a portion of a
byte array, and stores the result in the given byte array.
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.
- The number of bytes placed into the output array.
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.
getAlgorithm
public final 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.
getBlockSize
public final int getBlockSize()
Return the size of blocks, in bytes, that this cipher processes.
getIV
public final byte[] getIV()
Return the initialization vector that this instance was
initialized with.
getInstance
public static final Cipher getInstance(String transformation)
throws NoSuchAlgorithmException,
NoSuchPaddingException
Creates a new cipher instance for the given transformation.
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.
- An appropriate cipher for this transformation.
getOutputSize
public final int getOutputSize(int inputLength)
throws IllegalStateException
Returns the size an output buffer needs to be if this cipher is
updated with a number of bytes.
inputLength
- The input length.
- The output length given this input length.
IllegalStateException
- If this instance has not
been initialized, or if a doFinal call has already
been made.
init
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.
init
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.
init
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.
init
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.
init
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.
init
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.
init
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.
init
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.
unwrap
public final Key unwrap(byte[] wrappedKey,
String wrappedKeyAlgorithm,
int wrappedKeyType)
throws IllegalStateException,
InvalidKeyException,
NoSuchAlgorithmException
Unwrap a previously-wrapped key.
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.
update
public final byte[] update(byte[] input)
throws IllegalStateException
Continue a multi-part transformation on an entire byte array,
returning the transformed bytes.
update
public final byte[] update(byte[] input,
int inputOffset,
int inputLength)
throws IllegalStateException
Continue a multi-part transformation on part of a byte array,
returning the transformed bytes.
input
- The input bytes.inputOffset
- The index in the input to start.inputLength
- The number of bytes to transform.
update
public final int update(byte[] input,
int inputOffset,
int inputLength,
byte[] output)
throws IllegalStateException,
ShortBufferException
Continue a multi-part transformation on part of a byte array,
placing the transformed bytes into the given array.
input
- The input bytes.inputOffset
- The index in the input to start.inputLength
- The number of bytes to transform.output
- The output byte array.
- The number of transformed bytes.
update
public final int update(byte[] input,
int inputOffset,
int inputLength,
byte[] output,
int outputOffset)
throws IllegalStateException,
ShortBufferException
Continue a multi-part transformation on part of a byte array,
placing the transformed bytes into the given array.
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.
- The number of transformed bytes.
Cipher.java -- Interface to a cryptographic cipher.
Copyright (C) 2004, 2006 Free Software Foundation, Inc.
This file is part of GNU Classpath.
GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.
Linking this library statically or dynamically with other modules is
making a combined work based on this library. Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.
As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module. An independent module is a module which is not derived from
or based on this library. If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so. If you do not wish to do so, delete this
exception statement from your version.