All Packages Class Hierarchy This Package Previous Next Index
Class java.security.Cipher
java.lang.Object
|
+----java.security.IJCE_Traceable
|
+----java.security.Cipher
- public abstract class Cipher
- extends IJCE_Traceable
- implements Parameterized
This class is used to provide the functionality of a general purpose
encryption algorithm, such as DES or RSA. Encryption is used to ensure
confidentiality of digital data.
This class follows the general algorithm architecture found elsewhere
in the security API: the base class provides an algorithm-independent
interface to basic encryption functionality, with provider implementation
subclassing a subset of the behaviours.
Like other algorithm-based classes in Java Security, the Cipher
class is separated between application and provider interfaces:
- Cipher API (Application Programming Interface)
- This is the interface of methods called by applications
needing encryption services. The API consists of all public
methods.
- Cipher SPI (Service Provider Interface)
- This is the interface implemented by providers that supply
specific algorithms. It consists of all methods whose names
are prefixed by
engine
. Each such method is
usually called by a correspondingly-named public API method.
For example, the engineInitEncrypt
method is
called by the initEncrypt
method.
Ciphers represented by this class satisfy the following constraints:
- At any point in time the cipher has a plaintext block size, and
a ciphertext block size, both expressed in bytes. These sizes may
change when initEncrypt or initDecrypt are called, and they may
be invalid before the cipher is initialized, but they do not
change at other times.
- A plaintext block encrypts to exactly one ciphertext block, and
a ciphertext block decrypts to exactly one plaintext block.
Byte-oriented stream ciphers (or ciphers in CFB and OFB modes, for
example) have plaintext and ciphertext block sizes of 1 byte. For
public key ciphers, it is common for the block sizes to be dependent
on the length of some parameter of the public key.
A block cipher implementation may either implement its own buffering
(by passing implBuffering == true
to the constructor), or leave
it to the Cipher superclass (implBuffering
== false). When
the implementation handles buffering, data passed to update
is
passed directly on to engineUpdate
, and data passed to
crypt
is passed to engineUpdate
, followed
immediately by a call to engineCrypt
.
When the Cipher superclass handles buffering, up to one block is buffered,
in order to ensure that the length of data passed to engineUpdate
is always a multiple of the block size. In this case the engineCrypt
method is not used.
Cipher implementations are not required or expected to be threadsafe.
If methods of a single Cipher object are called simultaneously by more
than one thread, the result will be unpredictable.
Copyright © 1997
Systemics Ltd on behalf of the
Cryptix Development Team.
All rights reserved.
$Revision: 1.8 $
- Author:
- David Hopwood, Raif S. Naffah
-
DECRYPT
- The state of the cipher when it is ready to decrypt, that is,
the state it is in right after a call to
initDecrypt
.
-
ENCRYPT
- The state of the cipher when it is ready to encrypt, that is,
the state it is in right after a call to
initEncrypt
.
-
UNINITIALIZED
- The state of the cipher object when it is uninitialized,
that is, the state it is in right after it has been created.
-
Cipher()
- The JCE docs say: "Constructor used for dynamic instantiation."
I don't understand why this is needed.
Deprecated.
-
Cipher(boolean, boolean, String)
- Constructor for a Cipher.
-
Cipher(boolean, String, String)
- This constructor is identical to the previous one (with arguments
boolean, boolean, String), except that it does not have the redundant
implPadding parameter, and also allows the algorithm name
to be specified.
-
blockSize()
- Returns the length of a block for this cipher.
-
clone()
- Returns a clone of this cipher.
-
crypt(byte[])
- Encrypts or decrypts the specified array of data, which will be
automatically padded/unpadded as necessary.
-
crypt(byte[], int, int)
- Encrypts or decrypts the specified array of data, which will be
automatically padded/unpadded as necessary.
-
crypt(byte[], int, int, byte[], int)
- Encrypts or decrypts the specified subarray of data, pads or unpads
it as necessary, and places the result in the specified output buffer.
-
doFinal(byte[])
- Equivalent to
crypt(in)
.
-
doFinal(byte[], int, int)
- Equivalent to
crypt(in, offset, length)
.
-
doFinal(byte[], int, int, byte[])
- Equivalent to
crypt(in, inOffset, inLen, out, 0)
.
-
doFinal(byte[], int, int, byte[], int)
- Equivalent to
crypt(in, inOffset, inLen, out, outOffset)
.
-
engineBlockSize()
- SPI: Returns the length of a block, in bytes.
-
engineCiphertextBlockSize()
- SPI: Returns the length of a ciphertext block, in bytes.
-
engineCrypt(byte[], int)
- SPI: Process data buffered by this cipher implementation.
-
engineGetParameter(String)
- SPI: Gets the value of the specified algorithm parameter.
-
engineInBufferSize(int, boolean)
- SPI: Returns the minimum number of bytes of input, that
will cause an output of outLen bytes from a call to
engineUpdate
(when isFinal is false), or
successive calls to both engineUpdate
and
engineCrypt
(when isFinal is true).
-
engineInitDecrypt(Key)
- SPI: Initializes this cipher for decryption, using the
specified key.
-
engineInitEncrypt(Key)
- SPI: Initializes this cipher for encryption, using the
specified key.
-
engineOutBufferSize(int, boolean)
- SPI: Returns the length of output buffer required for a given
length of input, in bytes.
-
enginePlaintextBlockSize()
- SPI: Returns the length of a plaintext block, in bytes.
-
engineSetPaddingScheme(PaddingScheme)
- SPI: Sets the object that will implement padding for this cipher.
-
engineSetParameter(String, Object)
- SPI: Sets the specified algorithm parameter to the specified
value.
-
engineUpdate(byte[], int, int, byte[], int)
- SPI: This is the main engine method for updating data.
-
getAlgorithm()
- Returns this algorithm's standard cipher name (not including
mode and padding).
-
getAlgorithms()
- Gets the standard names of all Ciphers implemented by any
installed provider.
-
getAlgorithms(Provider)
- Gets the standard names of all Ciphers implemented by a provider.
-
getCiphertextBlockSize()
- Returns the length of a ciphertext block, in bytes.
-
getInputBlockSize()
- Returns the length of an input block, in bytes.
-
getInstance(Cipher, Mode, PaddingScheme)
- Generates a new Cipher object by composing the given Cipher, Mode and
PaddingScheme objects.
-
getInstance(String)
- Generates a Cipher object that implements the given algorithm.
-
getInstance(String, String)
- Generates a Cipher object that implements the given cipher, from
the given provider.
-
getMode()
- Returns this algorithm's standard mode name.
-
getOutputBlockSize()
- Returns the length of an output block, in bytes.
-
getPadding()
- Returns this algorithm's standard padding scheme name.
-
getPaddingScheme()
- Returns the object implementing padding for this cipher, or null if
there is no such object.
-
getParameter(String)
- Gets the value of the specified algorithm parameter.
-
getPlaintextBlockSize()
- Returns the length of a plaintext block, in bytes.
-
getProvider()
- Returns the name of the provider of this cipher.
-
getState()
- Returns the state of this Cipher object.
-
inBufferSize(int)
- Returns the minimum number of bytes of input, that will cause an
output of outLen bytes from a call to
update
(i.e.
-
inBufferSizeFinal(int)
- Returns the minimum number of bytes of input, that will cause an
output of outLen bytes from a call to
crypt
(including padding for the final block of the stream, if applicable).
-
initDecrypt(Key)
- Initializes this cipher for decryption, using the specified
key.
-
initEncrypt(Key)
- Initializes this cipher for encryption, using the specified
key.
-
isPaddingBlockCipher()
- Returns true if this cipher is a padding block cipher.
-
outBufferSize(int)
- Returns the size of the buffer necessary to hold the output
resulting from a call to
update
(i.e.
-
outBufferSizeFinal(int)
- Returns the size of the buffer necessary to hold the output
resulting from a call to
crypt
(including padding
for the final block of the stream, if applicable).
-
setParameter(String, Object)
- Sets the specified algorithm parameter to the specified value.
-
toString()
-
-
update(byte[])
- Encrypts or decrypts the specified array of data, which is not the
final data in this stream.
-
update(byte[], int, int)
- Encrypts or decrypts the specified subarray of data, which is not the
final data in this stream.
-
update(byte[], int, int, byte[])
- Encrypts or decrypts the specified subarray of data, which is not the
final data in this stream, and places the result in the specified
output buffer (starting at offset 0).
-
update(byte[], int, int, byte[], int)
- Encrypts or decrypts the specified subarray of data, which is not the
final data in this stream, and places the result in the specified
output buffer.
UNINITIALIZED
public static final int UNINITIALIZED
- The state of the cipher object when it is uninitialized,
that is, the state it is in right after it has been created.
ENCRYPT
public static final int ENCRYPT
- The state of the cipher when it is ready to encrypt, that is,
the state it is in right after a call to
initEncrypt
.
- See Also:
- initEncrypt
DECRYPT
public static final int DECRYPT
- The state of the cipher when it is ready to decrypt, that is,
the state it is in right after a call to
initDecrypt
.
- See Also:
- initDecrypt
Cipher
protected Cipher()
- Note: Cipher() is deprecated.
- The JCE docs say: "Constructor used for dynamic instantiation."
I don't understand why this is needed. --DJH
Cipher
protected Cipher(boolean implBuffering,
boolean implPadding,
String provider)
- Constructor for a Cipher. This constructor is only for use
by subclasses, which should pass the correct arguments to convey
their behaviour to the superclass. Applications cannot call this
constructor directly.
For byte-oriented stream ciphers (where the input block size is 1),
buffering is not needed, and the implBuffering parameter has
no effect.
In this version
of IJCE, implPadding must be false. If it is true, an
IllegalArgumentException is thrown.
- Parameters:
- implBuffering - if true, this argument indicates that data
will always be passed from update/crypt to
engineUpdate/engineCrypt without modification.
- implPadding - must be false.
- provider - the name of the provider of the underlying
cryptographic engine.
Cipher
protected Cipher(boolean implBuffering,
String provider,
String algorithm)
- This constructor is identical to the previous one (with arguments
boolean, boolean, String), except that it does not have the redundant
implPadding parameter, and also allows the algorithm name
to be specified.
This constructor
is not supported in JavaSoft's version of JCE.
- Parameters:
- implBuffering - if true, this argument indicates that data
will always be passed from update/crypt to
engineUpdate/engineCrypt without modification.
- provider - the name of the provider of the underlying
cryptographic engine.
- algorithm - the name of this algorithm (optionally with
mode and padding, separated by '/'), as it is
configured in the properties file.
getPaddingScheme
protected final PaddingScheme getPaddingScheme()
- Returns the object implementing padding for this cipher, or null if
there is no such object.
getInstance
public static Cipher getInstance(String algorithm) throws NoSuchAlgorithmException
- Generates a Cipher object that implements the given algorithm. If the
default provider package contains a class implementing the algorithm,
an instance of that class is returned. If it is not available in the
default package, other packages are searched.
Any of the following formats can be used for the algorithm name:
- cipher "/" mode "/" padding
- all algorithm components - cipher, mode, and padding -
are specified (these may be aliases).
- cipher "/" mode
- the padding is assumed to be "NONE".
- cipher
- the mode is assumed to be "ECB", and the padding to be "NONE".
See
International JCE Standard Algorithm Names for a list
of Cipher algorithm names.
- Parameters:
- algorithm - the algorithm name, as described above.
- Returns:
- the new Cipher object, in the UNINITIALIZED state.
- Throws: NoSuchAlgorithmException
- if the algorithm is
not available from any provider.
getInstance
public static Cipher getInstance(String algorithm,
String provider) throws NoSuchAlgorithmException, NoSuchProviderException
- Generates a Cipher object that implements the given cipher, from
the given provider. The format of the cipher specification is as
described for
getInstance(String algorithm)
.
If the algorithm is implemented using more than one component
(cipher, mode, and padding scheme), all of them must come from the
given provider. More flexibility can be obtained by using the
getInstance(Cipher, Mode, PaddingScheme)
factory method.
For example, to request "DES" from the SUN provider, "CBC" from the
Cryptix provider, and "PKCS#5" from any provider, use:
Cipher.getInstance(
Cipher.getInstance("DES", "SUN"),
Mode.getInstance("CBC", "Cryptix"),
PaddingScheme.getInstance("PKCS#5")
)
See
International JCE Standard Algorithm Names for a list
of Cipher algorithm names.
- Parameters:
- algorithm - the cipher specification.
- Returns:
- the new Cipher object, in the UNINITIALIZED state.
- Throws: NoSuchAlgorithmException
- if the algorithm is not
available from the provider.
- Throws: NoSuchProviderException
- if the provider is not
available in the environment.
getInstance
public static Cipher getInstance(Cipher cipher,
Mode mode,
PaddingScheme padding)
- Generates a new Cipher object by composing the given Cipher, Mode and
PaddingScheme objects. mode may be null (indicating ECB),
and padding may be null (indicating NONE).
This method
is not supported in JavaSoft's version of JCE.
- Throws: NullPointerException
- if cipher == null
getState
public final int getState()
- Returns the state of this Cipher object. Possible states are:
- UNINITIALIZED
- The cipher has not been initialized.
- ENCRYPT
- The cipher has been initialized for encryption. It may be
used for encryption only.
- DECRYPT
- The cipher has been initialized for decryption. It may be
used for decryption only.
- Returns:
- the state of this cipher object.
- See Also:
- UNINITIALIZED, ENCRYPT, DECRYPT
getAlgorithm
public final String getAlgorithm()
- Returns this algorithm's standard cipher name (not including
mode and padding).
See
International JCE Standard Algorithm Names for a list
of Cipher algorithm names.
- Returns:
- the standard cipher name (such as "DES").
getMode
public final String getMode()
- Returns this algorithm's standard mode name.
See
International JCE Standard Algorithm Names for a list
of Mode algorithm names.
- Returns:
- the algorithm's standard mode name (such as "CBC")
getPadding
public final String getPadding()
- Returns this algorithm's standard padding scheme name.
See
International JCE Standard Algorithm Names for a list
of PaddingScheme algorithm names.
- Returns:
- the algorithm's standard padding scheme name (such as
"PKCS#7" or "NONE")
getProvider
public final String getProvider()
- Returns the name of the provider of this cipher.
- Returns:
- the provider name (such as "SUN" or "Cryptix")
isPaddingBlockCipher
public final boolean isPaddingBlockCipher()
- Returns true if this cipher is a padding block cipher.
A cipher is a padding block cipher iff getPlaintextBlockSize() > 1
&& getPaddingScheme() != null
.
If getPlaintextBlockSize throws an exception, so will this method.
This method is needed because
CipherInputStream and
CipherOutputStream
use a different buffering algorithm for padding block ciphers.
This method
is not supported in JavaSoft's version of JCE.
outBufferSize
public final int outBufferSize(int inLen)
- Returns the size of the buffer necessary to hold the output
resulting from a call to
update
(i.e. not including
padding). This call takes into account any incomplete block
currently being buffered.
- Parameters:
- inLen - the number of bytes to process.
- Throws: IllegalArgumentException
- if inLen < 0
outBufferSizeFinal
public final int outBufferSizeFinal(int inLen)
- Returns the size of the buffer necessary to hold the output
resulting from a call to
crypt
(including padding
for the final block of the stream, if applicable). This call takes
into account any incomplete block currently being buffered.
This method
is not supported in JavaSoft's version of JCE.
- Parameters:
- inLen - the number of bytes to process.
- Throws: IllegalArgumentException
- if inLen < 0
inBufferSize
public final int inBufferSize(int outLen)
- Returns the minimum number of bytes of input, that will cause an
output of outLen bytes from a call to
update
(i.e.
not including padding). This call takes into account any incomplete
block currently being buffered.
This is used by CipherInputStream, for example, to
calculate how much data must be read from its underlying stream before
encryption or decryption.
This method
is not supported in JavaSoft's version of JCE.
- Parameters:
- outLen - the number of bytes of output required.
- Throws: IllegalArgumentException
- if outLen < 0
inBufferSizeFinal
public final int inBufferSizeFinal(int outLen)
- Returns the minimum number of bytes of input, that will cause an
output of outLen bytes from a call to
crypt
(including padding for the final block of the stream, if applicable).
This call takes into account any incomplete block currently being
buffered.
This method
is not supported in JavaSoft's version of JCE.
- Parameters:
- outLen - the number of bytes of output required.
- Throws: IllegalArgumentException
- if outLen < 0
blockSize
public final int blockSize()
- Returns the length of a block for this cipher. If plaintext and
ciphertext blocks are different lengths, this method throws an
IllegalBlockSizeException.
- Returns:
- the length in bytes of a block.
- Throws: IllegalBlockSizeException
- if getPlaintextBlockSize() !=
getCiphertextBlockSize()
getInputBlockSize
public final int getInputBlockSize()
- Returns the length of an input block, in bytes. When the cipher is
in encryption mode, this is the length of a plaintext block. When in
decryption mode, it is the length of a ciphertext block.
This method
is not supported in JavaSoft's version of JCE.
- Returns:
- the length in bytes of an input block for this cipher.
- Throws: Error
- if the cipher is uninitialized.
getOutputBlockSize
public final int getOutputBlockSize()
- Returns the length of an output block, in bytes. When the cipher is
in encryption mode, this is the length of a ciphertext block. When in
decryption mode, it is the length of a plaintext block.
This method
is not supported in JavaSoft's version of JCE.
- Returns:
- the length in bytes of an output block for this cipher.
- Throws: Error
- if the cipher is uninitialized.
getPlaintextBlockSize
public final int getPlaintextBlockSize()
- Returns the length of a plaintext block, in bytes.
For byte-oriented stream ciphers, this method returns 1.
This method
is not supported in JavaSoft's version of JCE.
- Returns:
- the length in bytes of a plaintext block for this cipher.
getCiphertextBlockSize
public final int getCiphertextBlockSize()
- Returns the length of a ciphertext block, in bytes.
For byte-oriented stream ciphers, this method returns 1.
This method
is not supported in JavaSoft's version of JCE.
- Returns:
- the length in bytes of a ciphertext block for this cipher.
initEncrypt
public final void initEncrypt(Key key) throws KeyException
- Initializes this cipher for encryption, using the specified
key. A successful call to this method puts the cipher in the
ENCRYPT state. This method may be called on a cipher in any
state. Any state information (key, feedback buffer, ...) is
lost and reset.
- Parameters:
- key - the key to use for encryption.
- Throws: NullPointerException
- if key == null
- Throws: KeyException
- if the key is invalid.
initDecrypt
public final void initDecrypt(Key key) throws KeyException
- Initializes this cipher for decryption, using the specified
key. A successful call to this method puts the cipher in the
DECRYPT state. This method may be called on a cipher in any
state. Any state information (key, feedback buffer, ...) is
lost and reset.
- Parameters:
- key - the key to use for decryption.
- Throws: NullPointerException
- if key == null
- Throws: KeyException
- if the key is invalid.
update
public final byte[] update(byte in[])
- Encrypts or decrypts the specified array of data, which is not the
final data in this stream. For block ciphers, if the last block so
far is incomplete, it will be buffered and processed in subsequent
calls to
update
or crypt
.
Whether the data is encrypted or decrypted depends on the cipher's
initialization state. This method will automatically allocate
an output buffer of the right size.
This method
is not supported in JavaSoft's version of JCE. However,
an equivalent method is declared in the JCE 1.2 preview documentation
for javax.crypto.Cipher.
- Parameters:
- in - the input data.
- Returns:
- the encryption or decryption result.
- Throws: NullPointerException
- if in == null
update
public final byte[] update(byte in[],
int offset,
int length)
- Encrypts or decrypts the specified subarray of data, which is not the
final data in this stream. For block ciphers, if the last block so
far is incomplete, it will be buffered and processed in subsequent
calls to
update
or crypt
.
Whether the data is encrypted or decrypted depends on the cipher's
initialization state. This method will automatically allocate
an output buffer of the right size.
This method
is not supported in JavaSoft's version of JCE. However,
an equivalent method is declared in the JCE 1.2 preview documentation
for javax.crypto.Cipher.
- Parameters:
- in - the input data.
- offset - the offset indicating where the subarray starts in the
in array.
- length - the length of the subarray.
- Returns:
- the encryption or decryption result.
- Throws: NullPointerException
- if in == null
- Throws: IllegalArgumentException
- if length < 0
- Throws: ArrayIndexOutOfBoundsException
- if offset < 0 ||
(long) offset + length > in.length
update
public final int update(byte in[],
int inOffset,
int inLen,
byte out[])
- Encrypts or decrypts the specified subarray of data, which is not the
final data in this stream, and places the result in the specified
output buffer (starting at offset 0). For block ciphers, if the last
block so far is incomplete, it will be buffered and processed in
subsequent calls to
update
or crypt
.
Whether the data is encrypted or decrypted depends on the cipher's
initialization state. out.length
must be at least
outBufferSize(inLen)
, otherwise an
ArrayIndexOutOfBoundsException will be thrown (in this case it is
not specified how much, if any, of the output will have been written).
This method
is not supported in JavaSoft's version of JCE. However,
an equivalent method is declared in the JCE 1.2 preview documentation
for javax.crypto.Cipher.
- Parameters:
- in - the input data.
- inOffset - the offset indicating where the subarray starts in
the in array.
- inLen - the length of the subarray.
- out - the output buffer.
- Returns:
- the number of bytes written.
- Throws: NullPointerException
- if in == null || out == null
- Throws: IllegalArgumentException
- if inLen < 0
- Throws: ArrayIndexOutOfBoundsException
- if inOffset < 0 ||
outOffset < 0 || (long) inOffset + inLen > in.length ||
outBufferSize(inLen) > out.length
update
public final int update(byte in[],
int inOffset,
int inLen,
byte out[],
int outOffset)
- Encrypts or decrypts the specified subarray of data, which is not the
final data in this stream, and places the result in the specified
output buffer. For block ciphers, if the last block so far is
incomplete, it will be buffered and processed in subsequent calls to
update
or crypt
.
Whether the data is encrypted or decrypted depends on the cipher's
initialization state. out.length
must be at least
(long) outOffset + outBufferSize(inLen)
, otherwise an
ArrayIndexOutOfBoundsException will be thrown (in this case it is
not specified how much, if any, of the output will have been written).
This method
is not supported in JavaSoft's version of JCE. However,
an equivalent method is declared in the JCE 1.2 preview documentation
for javax.crypto.Cipher.
- Parameters:
- in - the input data.
- inOffset - the offset indicating where the subarray starts in
the in array.
- inLen - the length of the subarray.
- out - the output buffer.
- outOffset - the offset indicating where to start writing the
result into the output buffer.
- Returns:
- the number of bytes written.
- Throws: NullPointerException
- if in == null || out == null
- Throws: IllegalArgumentException
- if inLen < 0
- Throws: ArrayIndexOutOfBoundsException
- if inOffset < 0 ||
outOffset < 0 || (long) inOffset + inLen > in.length ||
(long) outOffset + outBufferSize(inLen) > out.length
crypt
public final byte[] crypt(byte in[]) throws IllegalBlockSizeException
- Encrypts or decrypts the specified array of data, which will be
automatically padded/unpadded as necessary.
Whether the data is encrypted or decrypted depends on the cipher's
initialization state. This method will automatically allocate
an output buffer of the right size.
If the final block is incomplete, the cipher must have a padding scheme
other than "NONE", and it must be in the ENCRYPT state. If this is not
the case, an IllegalBlockSizeException will be thrown.
If the cipher is in the DECRYPT state and padding is being used,
at least one full ciphertext block should be passed to crypt
.
This is necessary because the last block contains information needed to
determine the length of the original plaintext.
- Parameters:
- in - the input data.
- Returns:
- the encryption or decryption result.
- Throws: NullPointerException
- if in == null
- Throws: IllegalBlockSizeException
- if the final block cannot be
padded or unpadded.
crypt
public final byte[] crypt(byte in[],
int offset,
int length) throws IllegalBlockSizeException
- Encrypts or decrypts the specified array of data, which will be
automatically padded/unpadded as necessary.
Whether the data is encrypted or decrypted depends on the cipher's
initialization state. This method will automatically allocate
an output buffer of the right size.
If the final block is incomplete, the cipher must have a padding scheme
other than "NONE", and it must be in the ENCRYPT state. If this is not
the case, an IllegalBlockSizeException will be thrown.
If the cipher is in the DECRYPT state and padding is being used,
at least one full ciphertext block should be passed to crypt
.
This is necessary because the last block contains information needed to
determine the length of the original plaintext.
- Parameters:
- in - the input data.
- offset - the offset indicating where the subarray starts in the
in array.
- length - the length of the subarray.
- Returns:
- the encryption or decryption result.
- Throws: NullPointerException
- if in == null
- Throws: IllegalArgumentException
- if length < 0
- Throws: ArrayIndexOutOfBoundsException
- if offset < 0 ||
(long) offset + length > in.length
- Throws: IllegalBlockSizeException
- if the final block cannot be padded
or unpadded.
crypt
public final int crypt(byte in[],
int inOffset,
int inLen,
byte out[],
int outOffset) throws IllegalBlockSizeException
- Encrypts or decrypts the specified subarray of data, pads or unpads
it as necessary, and places the result in the specified output buffer.
Whether the data is encrypted or decrypted depends on the cipher's
initialization state.
If the final block is incomplete, the cipher must have a padding scheme
other than "NONE", and it must be in the ENCRYPT state. If this is not
the case, an IllegalBlockSizeException will be thrown.
If the cipher is in the DECRYPT state and padding is being used,
at least one full ciphertext block should be passed to crypt
.
This is necessary because the last block contains information needed to
determine the length of the original plaintext.
- Parameters:
- in - the input data.
- inOffset - the offset indicating where the subarray starts in
the in array.
- inLen - the length of the subarray.
- out - the output buffer.
- outOffset - the offset indicating where to start writing the
result into the output buffer.
- Returns:
- the number of bytes written.
- Throws: NullPointerException
- if in == null || out == null
- Throws: IllegalArgumentException
- if inLen < 0
- Throws: ArrayIndexOutOfBoundsException
- if inOffset < 0 ||
outOffset < 0 || (long) inOffset + inLen > in.length ||
(long) outOffset + outBufferSize(inLen) > out.length
doFinal
public final byte[] doFinal(byte in[]) throws IllegalBlockSizeException
- Equivalent to
crypt(in)
.
This method
is not supported in JavaSoft's version of JCE. However,
an equivalent method is declared in the JCE 1.2 preview documentation
for javax.crypto.Cipher.
doFinal
public final byte[] doFinal(byte in[],
int offset,
int length) throws IllegalBlockSizeException
- Equivalent to
crypt(in, offset, length)
.
This method
is not supported in JavaSoft's version of JCE. However,
an equivalent method is declared in the JCE 1.2 preview documentation
for javax.crypto.Cipher.
doFinal
public final int doFinal(byte in[],
int inOffset,
int inLen,
byte out[]) throws IllegalBlockSizeException
- Equivalent to
crypt(in, inOffset, inLen, out, 0)
.
This method
is not supported in JavaSoft's version of JCE. However,
an equivalent method is declared in the JCE 1.2 preview documentation
for javax.crypto.Cipher.
doFinal
public final int doFinal(byte in[],
int inOffset,
int inLen,
byte out[],
int outOffset) throws IllegalBlockSizeException
- Equivalent to
crypt(in, inOffset, inLen, out, outOffset)
.
This method
is not supported in JavaSoft's version of JCE. However,
an equivalent method is declared in the JCE 1.2 preview documentation
for javax.crypto.Cipher.
setParameter
public void setParameter(String param,
Object value) throws NoSuchParameterException, InvalidParameterException, InvalidParameterTypeException
- Sets the specified algorithm parameter to the specified value.
This method supplies a general-purpose mechanism through which it is
possible to set the various parameters of this object. A parameter may
be any settable parameter for the algorithm, such as block size,
a source of random bits for IV generation (if appropriate), or an
indication of whether or not to perform a specific but optional
computation. A uniform algorithm-specific naming scheme for each
parameter is desirable but left unspecified at this time.
This method
is not supported in JavaSoft's version of JCE.
- Parameters:
- param - the string identifier of the parameter.
- value - the parameter value.
- Throws: NullPointerException
- if param == null
- Throws: NoSuchParameterException
- if there is no parameter with name
param for this cipher implementation.
- Throws: InvalidParameterException
- if the parameter exists but cannot
be set (for example because the cipher is in the
wrong state).
- Throws: InvalidParameterTypeException
- if value is the wrong type
for this parameter.
getParameter
public Object getParameter(String param) throws NoSuchParameterException, InvalidParameterException
- Gets the value of the specified algorithm parameter.
This method supplies a general-purpose mechanism through which it
is possible to get the various parameters of this object. A parameter
may be any settable parameter for the algorithm, such as block size,
a source of random bits for IV generation (if appropriate), or an
indication of whether or not to perform a specific but optional
computation. A uniform algorithm-specific naming scheme for each
parameter is desirable but left unspecified at this time.
This method
is not supported in JavaSoft's version of JCE.
- Parameters:
- param - the string name of the parameter.
- Returns:
- the object that represents the parameter value.
- Throws: NullPointerException
- if param == null
- Throws: NoSuchParameterException
- if there is no parameter with name
param for this cipher implementation.
- Throws: InvalidParameterException
- if the parameter exists but cannot
be read.
clone
public Object clone() throws CloneNotSupportedException
- Returns a clone of this cipher.
Note: In JavaSoft's version of JCE, Cipher.clone()
is
protected. This is not very useful, since then an application (as opposed
to the cipher implementation itself) is not able to call it.
- Throws: CloneNotSupportedException
- if the cipher is not cloneable.
- Overrides:
- clone in class Object
toString
public String toString()
- Overrides:
- toString in class Object
engineSetPaddingScheme
protected void engineSetPaddingScheme(PaddingScheme padding)
- SPI: Sets the object that will implement padding for this cipher.
Cipher implementations may override this method in order to be notified
when the padding scheme is set (in this case they should always call
super.engineSetPaddingScheme(padding)
). Normally, overriding
this method is not required.
- Throws: IllegalStateException
- if the cipher is already initialized.
engineBlockSize
protected int engineBlockSize()
- SPI: Returns the length of a block, in bytes. Ciphers for
which plaintext and ciphertext blocks are the same size may override
this method. Otherwise, both enginePlaintextBlockSize and
engineCiphertextBlockSize should be overridden.
The value may change when initEncrypt
or
initDecrypt
is called, but it should not change at
other times.
- Returns:
- the length in bytes of a block for this cipher.
enginePlaintextBlockSize
protected int enginePlaintextBlockSize()
- SPI: Returns the length of a plaintext block, in bytes.
For byte-oriented stream ciphers, this method should return 1.
The value may change when initEncrypt
or
initDecrypt
is called, but it should not change at
other times.
The default implementation returns engineBlockSize()
.
- Returns:
- the length in bytes of a plaintext block for this cipher.
engineCiphertextBlockSize
protected int engineCiphertextBlockSize()
- SPI: Returns the length of a ciphertext block, in bytes.
For byte-oriented stream ciphers, this method should return 1.
The value may change when initEncrypt
or
initDecrypt
is called, but it should not change at
other times.
The default implementation returns engineBlockSize()
.
- Returns:
- the length in bytes of a ciphertext block for this cipher.
engineOutBufferSize
protected int engineOutBufferSize(int inLen,
boolean isFinal)
- SPI: Returns the length of output buffer required for a given
length of input, in bytes.
isFinal
is true when this
is the final block of input.
If implBuffering
is false, the inLen
parameter already takes into account the length of any required
padding, and buffered data. In this case inLen
will be
a multiple of the input block size (this may only be true for IJCE,
not for other implementations of JCE).
The default implementation assumes that the output will have the
same number of blocks as the input (i.e. the result is
inLen / getInputBlockSize() * getOutputBlockSize()
).
You will need to override this method if the cipher handles its
own buffering.
- Parameters:
- inLen - the number of bytes of input
- isFinal - whether the last block is to be padded
- Returns:
- the length in bytes of the output block
engineInBufferSize
protected int engineInBufferSize(int outLen,
boolean isFinal)
- SPI: Returns the minimum number of bytes of input, that
will cause an output of outLen bytes from a call to
engineUpdate
(when isFinal is false), or
successive calls to both engineUpdate
and
engineCrypt
(when isFinal is true).
If implBuffering
is false, this method need not take
into account padding or buffered data when calculating the result.
In this case outLen
will be a multiple of the output
block size (this may only be true for IJCE, not for other
implementations of JCE).
The default implementation assumes that the output will have the
same number of blocks as the input (i.e. the result is
outLen / getOutputBlockSize() * getInputBlockSize()
).
You will need to override this method if the cipher handles its
own buffering.
- Parameters:
- outLen - the number of bytes of output
- isFinal - whether the input includes the last block
- Returns:
- the length in bytes of the output block
engineInitEncrypt
protected abstract void engineInitEncrypt(Key key) throws KeyException
- SPI: Initializes this cipher for encryption, using the
specified key.
After a call to this method, the cipher's state is set to ENCRYPT.
- Parameters:
- key - the key to use for encryption.
- Throws: KeyException
- if the key is invalid.
engineInitDecrypt
protected abstract void engineInitDecrypt(Key key) throws KeyException
- SPI: Initializes this cipher for decryption, using the
specified key.
After a call to this method, the cipher's state is set to DECRYPT.
- Parameters:
- key - the key to use for decryption.
- Throws: KeyException
- if the key is invalid.
engineUpdate
protected abstract int engineUpdate(byte in[],
int inOffset,
int inLen,
byte out[],
int outOffset)
- SPI: This is the main engine method for updating data.
When implBuffering
is true, this method will be called
with the same data that is passed to update
or
crypt
(i.e. there will be exactly one call to
engineUpdate
for each call to update
or
crypt
).
When implBuffering
is false, the Cipher superclass will
ensure that when it calls this method, inLen is a non-negative
multiple of getInputBlockSize()
.
in and out may be the same array, and the input and
output regions may overlap. A cipher implementation should
not use any part of in or out as working storage
for intermediate steps of the algorithm. It should copy only the final
result into the out array.
SECURITY: if array arguments are passed to native code, the
implementation must ensure that a buffer overflow or illegal memory
access cannot occur, regardless of the arguments passed to
this method. I.e. the native library should not be called if:
in == null || out == null || inLen < 0 || inLen % (block size) != 0 ||
inOffset < 0 || (long)inOffset + inLen > in.length ||
outOffset < 0 || (long)outOffset + (number of bytes to be written) > out.length
Note that the (long)
casts are essential, because
inOffset or outOffset could be close to
Integer.MAX_VALUE
. The native method being called
should be private. This is important because untrusted code could
subclass the cipher implementation, and call this method directly
with any arguments.
- Parameters:
- in - the input data.
- inOffset - the offset into in specifying where the
data starts.
- inLen - the length of the subarray.
- out - the output array.
- outOffset - the offset indicating where to start writing into
the out array.
- Returns:
- the number of bytes written.
engineCrypt
protected int engineCrypt(byte out[],
int outOffset)
- SPI: Process data buffered by this cipher implementation.
This method is overriden by ciphers that handle their own buffering
(i.e. implBuffering == true
). It should flush the internal
buffer, and process any remaining data. By default, this method
returns 0.
Ciphers that pass implBuffering == false
to the superclass
constructor need not override this method.
SECURITY: if array arguments are passed to native code, the
implementation must ensure that a buffer overflow or illegal memory
access cannot occur, regardless of the arguments passed to
this method. I.e. the native library should not be called if:
out == null || outOffset < 0 ||
(long)outOffset + (number of bytes to be written) > out.length
Note that the (long)
cast is essential, because
outOffset could be close to Integer.MAX_VALUE
.
The native method being called should be private. This is important
because untrusted code could subclass the cipher implementation, and
call this method directly with any arguments.
- Parameters:
- out - the output buffer into which to write the result.
- Returns:
- the number of bytes written.
engineSetParameter
protected void engineSetParameter(String param,
Object value) throws NoSuchParameterException, InvalidParameterException, InvalidParameterTypeException
- SPI: Sets the specified algorithm parameter to the specified
value.
This method supplies a general-purpose mechanism through which it is
possible to set the various parameters of this object. A parameter may
be any settable parameter for the algorithm, such as block size,
a source of random bits for IV generation (if appropriate), or an
indication of whether or not to perform a specific but optional
computation. A uniform algorithm-specific naming scheme for each
parameter is desirable but left unspecified at this time.
The default implementation always throws a NoSuchParameterException.
This method
is not supported in JavaSoft's version of JCE.
- Parameters:
- param - the string name of the parameter.
- value - the parameter value.
- Throws: NoSuchParameterException
- if there is no parameter with name
param for this cipher implementation.
- Throws: InvalidParameterException
- if the parameter exists but cannot
be set (for example because the cipher is in the
wrong state).
- Throws: InvalidParameterTypeException
- if value is the wrong type
for this parameter.
engineGetParameter
protected Object engineGetParameter(String param) throws NoSuchParameterException, InvalidParameterException
- SPI: Gets the value of the specified algorithm parameter.
This method supplies a general-purpose mechanism through which it is
possible to get the various parameters of this object. A parameter may
be any settable parameter for the algorithm, such as block size, a source
of random bits for IV generation (if appropriate), or an indication of
whether or not to perform a specific but optional computation. A
uniform algorithm-specific naming scheme for each parameter is desirable
but left unspecified at this time.
The default implementation always throws a NoSuchParameterException.
This method
is not supported in JavaSoft's version of JCE.
- Parameters:
- param - the string name of the parameter.
- Returns:
- the object that represents the parameter value.
- Throws: NoSuchParameterException
- if there is no parameter with name
param for this cipher implementation.
- Throws: InvalidParameterException
- if the parameter exists but cannot
be read.
getAlgorithms
public static String[] getAlgorithms(Provider provider)
- Gets the standard names of all Ciphers implemented by a provider.
This method
is not supported in JavaSoft's version of JCE.
For compatibility you may wish to use
IJCE.getAlgorithms(provider, "Cipher")
instead.
getAlgorithms
public static String[] getAlgorithms()
- Gets the standard names of all Ciphers implemented by any
installed provider. Algorithm names are not duplicated if
they are supported by more than one provider (but specialized
cipher/mode implementations are treated as distinct, for
example "DES/CBC" is different from "DES").
This method
is not supported in JavaSoft's version of JCE.
For compatibility you may wish to use
IJCE.getAlgorithms("Cipher")
instead.
All Packages Class Hierarchy This Package Previous Next Index