|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.crypto.CipherSpi
This class defines the Service Provider Interface (SPI)
for the 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.
KeyGenerator
,
SecretKey
Constructor Summary | |
CipherSpi()
|
Method Summary | |
protected abstract byte[] |
engineDoFinal(byte[] input,
int inputOffset,
int inputLen)
Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation. |
protected abstract 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. |
protected abstract int |
engineGetBlockSize()
Returns the block size (in bytes). |
protected abstract byte[] |
engineGetIV()
Returns the initialization vector (IV) in a new buffer. |
protected abstract 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). |
protected abstract java.security.AlgorithmParameters |
engineGetParameters()
Returns the parameters used with this cipher. |
protected abstract 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. |
protected abstract 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. |
protected abstract void |
engineInit(int opmode,
java.security.Key key,
java.security.SecureRandom random)
Initializes this cipher with a key and a source of randomness. |
protected abstract void |
engineSetMode(java.lang.String mode)
Sets the mode of this cipher. |
protected abstract void |
engineSetPadding(java.lang.String padding)
Sets the padding mechanism of this cipher. |
protected abstract 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. |
protected abstract 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,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Constructor Detail |
public CipherSpi()
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 a combination of default and random parameter values used by the underlying cipher implementation if this cipher requires algorithm parameters but was not initialized with any.
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 any algorithm parameters that cannot be
derived from the given key
, the underlying cipher
implementation is supposed to generate the required parameters itself
(using provider-specific default or random values) if it is being
initialized for encryption, and raise an
InvalidKeyException
if it is being
initialized for decryption.
The generated parameters can be retrieved using
engineGetParameters or
engineGetIV (if the parameter is an IV).
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes (e.g., for parameter generation), it will get
them from random
.
Note that when a Cipher object is initialized, it loses all previously-acquired state. In other words, initializing a Cipher is equivalent to creating a new instance of that Cipher and initializing it.
opmode
- the operation mode of this cipher (this is either
ENCRYPT_MODE
or DECRYPT_MODE
)key
- the encryption keyrandom
- 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 requires any algorithm parameters and
params
is null, the underlying cipher implementation is
supposed to generate the required parameters itself (using
provider-specific default or random values) if it is being
initialized for encryption, and raise an
InvalidAlgorithmParameterException
if it is being
initialized for decryption.
The generated parameters can be retrieved using
engineGetParameters or
engineGetIV (if the parameter is an IV).
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes (e.g., for parameter generation), it will get
them from random
.
Note that when a Cipher object is initialized, it loses all previously-acquired state. In other words, initializing a Cipher is equivalent to creating a new instance of that Cipher and initializing it.
opmode
- the operation mode of this cipher (this is either
ENCRYPT_MODE
or DECRYPT_MODE
)key
- the encryption keyparams
- the algorithm parametersrandom
- the source of randomnessparams
is null.protected 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 requires any algorithm parameters and
params
is null, the underlying cipher implementation is
supposed to generate the required parameters itself (using
provider-specific default or random values) if it is being
initialized for encryption, and raise an
InvalidAlgorithmParameterException
if it is being
initialized for decryption.
The generated parameters can be retrieved using
engineGetParameters or
engineGetIV (if the parameter is an IV).
If this cipher (including its underlying feedback or padding scheme)
requires any random bytes (e.g., for parameter generation), it will get
them from random
.
Note that when a Cipher object is initialized, it loses all previously-acquired state. In other words, initializing a Cipher is equivalent to creating a new instance of that Cipher and initializing it.
opmode
- the operation mode of this cipher (this is either
ENCRYPT_MODE
or DECRYPT_MODE
)key
- the encryption keyparams
- the algorithm parametersrandom
- the source of randomnessparams
is null.protected abstract byte[] engineUpdate(byte[] input, int inputOffset, int inputLen)
The first inputLen
bytes in the input
buffer, starting at inputOffset
inclusive, are processed,
and the result is stored in a new buffer.
input
- the input bufferinputOffset
- the offset in input
where the input
startsinputLen
- 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
inclusive, are processed,
and the result is stored in the output
buffer, starting at
outputOffset
inclusive.
If the output
buffer is too small to hold the result,
a ShortBufferException
is thrown.
input
- the input bufferinputOffset
- the offset in input
where the input
startsinputLen
- the input lengthoutput
- the buffer for the resultoutputOffset
- 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
inclusive, and any input
bytes that may have been buffered during a previous update
operation, are processed, with padding (if requested) being applied.
The result is stored in a new buffer.
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 bufferinputOffset
- the offset in input
where the input
startsinputLen
- 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
inclusive, and any input
bytes that may have been buffered during a previous update
operation, are processed, with padding (if requested) being applied.
The result is stored in the output
buffer, starting at
outputOffset
inclusive.
If the output
buffer is too small to hold the result,
a ShortBufferException
is thrown.
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 bufferinputOffset
- the offset in input
where the input
startsinputLen
- the input lengthoutput
- the buffer for the resultoutputOffset
- the offset in output
where the result
is storedoutput
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |