Overview | Package | Class | Tree | Deprecated | Index | Help | |||
PREV CLASS | NEXT CLASS | FRAMES | NO FRAMES | ||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.crypto.CipherSpi
Cipher
class.
All the abstract methods in this class must be implemented by each
cryptographic service provider who wishes to supply the implementation
of a particular cipher algorithm.
In order to create an instance of Cipher
, which
encapsulates an instance of this CipherSpi
class, an
application calls one of the
getInstance
factory methods of the
Cipher engine class and specifies the requested
transformation.
Optionally, the application may also specify the name of a provider.
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:
(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");
A provider may supply a separate class for each combination
of algorithm/mode/padding, or may decide to provide more generic
classes representing sub-transformations corresponding to
algorithm or algorithm/mode or algorithm//padding
(note the double slashes),
in which case the requested mode and/or padding are set automatically by
the getInstance
methods of Cipher
, which invoke
the engineSetMode and
engineSetPadding
methods of the provider's subclass of CipherSpi
.
A Cipher
property in a provider master class may have one of
the following formats:
// provider's subclass of "CipherSpi" implements "algName" with
// pluggable mode and padding
Cipher.
algName
// provider's subclass of "CipherSpi" implements "algName" in the
// specified "mode", with pluggable padding
Cipher.
algName/mode
// provider's subclass of "CipherSpi" implements "algName" with the
// specified "padding", with pluggable mode
Cipher.
algName//padding
// provider's subclass of "CipherSpi" implements "algName" with the
// specified "mode" and "padding"
Cipher.
algName/mode/padding
For example, a provider may supply a subclass of CipherSpi
that implements DES/ECB/PKCS5Padding, one that implements
DES/CBC/PKCS5Padding, one that implements
DES/CFB/PKCS5Padding, and yet another one that implements
DES/OFB/PKCS5Padding. That provider would have the following
Cipher
properties in its master class:
Cipher.
DES/ECB/PKCS5Padding
Cipher.
DES/CBC/PKCS5Padding
Cipher.
DES/CFB/PKCS5Padding
Cipher.
DES/OFB/PKCS5Padding
Another provider may implement a class for each of the above modes
(i.e., one class for ECB, one for CBC, one for CFB,
and one for OFB), one class for PKCS5Padding,
and a generic DES class that subclasses from CipherSpi
.
That provider would have the following
Cipher
properties in its master class:
Cipher.
DES
The getInstance
factory method of the Cipher
engine class follows these rules in order to instantiate a provider's
implementation of CipherSpi
for a
transformation of the form "algorithm":
CipherSpi
for the specified "algorithm".
If the answer is YES, instantiate this class, for whose mode and padding scheme default values (as supplied by the provider) are used.
If the answer is NO, throw a NoSuchAlgorithmException
exception.
The getInstance
factory method of the Cipher
engine class follows these rules in order to instantiate a provider's
implementation of CipherSpi
for a
transformation of the form "algorithm/mode/padding":
CipherSpi
for the specified "algorithm/mode/padding" transformation.
If the answer is YES, instantiate it.
If the answer is NO, go to the next step.
CipherSpi
for the sub-transformation "algorithm/mode".
If the answer is YES, instantiate it, and call
engineSetPadding(padding)
on the new instance.
If the answer is NO, go to the next step.
CipherSpi
for the sub-transformation "algorithm//padding" (note the double
slashes).
If the answer is YES, instantiate it, and call
engineSetMode(mode)
on the new instance.
If the answer is NO, go to the next step.
CipherSpi
for the sub-transformation "algorithm".
If the answer is YES, instantiate it, and call
engineSetMode(mode)
and
engineSetPadding(padding)
on the new instance.
If the answer is NO, throw a NoSuchAlgorithmException
exception.
Method Summary | |
byte[] | engineDoFinal(byte[] input,
int inputOffset,
int inputLen)
Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation. |
int | engineDoFinal(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 | engineGetBlockSize()
Returns the block size (in bytes). |
byte[] | engineGetIV()
Returns the initialization vector (IV) in a new buffer. |
int | engineGetOutputSize(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 | engineGetParameters()
Returns the parameters used with this cipher. |
void | engineInit(int opmode,
java.security.Key key,
java.security.SecureRandom random)
Initializes this cipher with a key and a source of randomness. |
void | engineInit(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 | engineInit(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 | engineSetMode(java.lang.String mode)
Sets the mode of this cipher. |
void | engineSetPadding(java.lang.String padding)
Sets the padding mechanism of this cipher. |
byte[] | engineUpdate(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 | engineUpdate(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. |
Methods inherited from class java.lang.Object | |
clone, equals, finalize, getClass, hashCode, notifyAll, notify, toString, wait, wait, wait |
Method Detail |
protected abstract void engineSetMode(java.lang.String mode) throws java.security.NoSuchAlgorithmException
mode
- the cipher modeprotected abstract void engineSetPadding(java.lang.String padding) throws NoSuchPaddingException
padding
- the padding mechanismprotected abstract int engineGetBlockSize()
protected abstract int engineGetOutputSize(int inputLen)
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.
inputLen
- the input length (in bytes)protected abstract byte[] engineGetIV()
This is useful in the context of password-based encryption or decryption, where the IV is derived from a user-provided passphrase.
protected abstract java.security.AlgorithmParameters engineGetParameters()
The returned parameters may be the same that were used to initialize this cipher, or may contain the default set of parameters or a set of randomly generated parameters used by the underlying cipher implementation (provided that the underlying cipher implementation uses a default set of parameters or creates new parameters if it needs parameters but was not initialized with any).
protected abstract void engineInit(int opmode, java.security.Key key, java.security.SecureRandom random) throws java.security.InvalidKeyException
The cipher is initialized for encryption or decryption, depending on
the value of opmode
.
If this cipher requires an initialization vector (IV), it will get
it from random
. The random IV can be
retrieved using engineGetIV.
This behaviour should only be used in encryption mode, however.
When initializing a cipher that requires an IV for decryption, the IV
(same IV that was used for encryption) must be provided explicitly as a
parameter, in order to get the correct result.
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.
opmode
- the operation mode of this cipher (this is either
ENCRYPT_MODE
or DECRYPT_MODE
)
key
- the encryption key
random
- the source of randomnessprotected abstract void engineInit(int opmode, java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) throws java.security.InvalidKeyException, java.security.InvalidAlgorithmParameterException
The cipher is initialized for encryption or decryption, depending on
the value of opmode
.
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes, 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.
opmode
- the operation mode of this cipher (this is either
ENCRYPT_MODE
or DECRYPT_MODE
)
key
- the encryption key
params
- the algorithm parameters
random
- the source of randomnessprotected abstract void engineInit(int opmode, java.security.Key key, java.security.AlgorithmParameters params, java.security.SecureRandom random) throws java.security.InvalidKeyException, java.security.InvalidAlgorithmParameterException
The cipher is initialized for encryption or decryption, depending on
the value of opmode
.
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes, 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.
opmode
- the operation mode of this cipher (this is either
ENCRYPT_MODE
or DECRYPT_MODE
)
key
- the encryption key
params
- the algorithm parameters
random
- the source of randomnessprotected abstract byte[] engineUpdate(byte[] input, int inputOffset, int inputLen)
The first inputLen
bytes in the input
buffer, starting at inputOffset
, are processed, and the
result is stored in a new buffer.
input
- the input buffer
inputOffset
- the offset in input
where the input
starts
inputLen
- the input lengthprotected abstract int engineUpdate(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) throws ShortBufferException
The first inputLen
bytes in the input
buffer, starting at inputOffset
, are processed, and the
result is stored in the output
buffer, starting at
outputOffset
.
If the output
buffer is too small to hold the result,
a ShortBufferException
is thrown.
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 storedoutput
protected abstract byte[] engineDoFinal(byte[] input, int inputOffset, int inputLen) throws IllegalBlockSizeException, BadPaddingException
The first inputLen
bytes in the input
buffer, starting at inputOffset
, 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.
A call to this method resets this cipher object to the state
it was in when previously initialized via a call to
engineInit
.
That is, the object is reset and available to encrypt or decrypt
(depending on the operation mode that was specified in the call to
engineInit
) more data.
input
- the input buffer
inputOffset
- the offset in input
where the input
starts
inputLen
- the input lengthprotected abstract int engineDoFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) throws ShortBufferException, IllegalBlockSizeException, BadPaddingException
The first inputLen
bytes in the input
buffer, starting at inputOffset
, 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
.
If the output
buffer is too small to hold the result,
a ShortBufferException
is thrown.
A call to this method resets this cipher object to the state
it was in when previously initialized via a call to
engineInit
.
That is, the object is reset and available to encrypt or decrypt
(depending on the operation mode that was specified in the call to
engineInit
) more data.
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 storedoutput
Overview | Package | Class | Tree | Deprecated | Index | Help | |||
PREV CLASS | NEXT CLASS | FRAMES | NO FRAMES | ||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |