public abstract class CipherSpi extends Object
This class represents the Service Provider Interface (SPI) for cryptographic ciphers.
Providers of cryptographic ciphers must subclass this for every
cipher they implement, implementing the abstract methods as
appropriate, then provide an entry that points to the subclass in
their implementation of Provider
.
CipherSpi objects are instantiated along with Cipher
s when
the Cipher.getInstance(java.lang.String)
methods are invoked.
Particular ciphers are referenced by a transformation, which
is a String consisting of the cipher's name or the ciper's name
followed by a mode and a padding. Transformations all follow the
general form:
Cipher names in the master Provider
class
may be:
Cipher.algorithm
Cipher.algorithm/mode
Cipher.algorithm//padding
Cipher.algorithm/mode/padding
When any Cipher.getInstance(java.lang.String)
method is
invoked, the following happens if the transformation is simply
algorithm:
CipherSpi
implementation
for "algorithm", return it. Otherwise throw a NoSuchAlgorithmException
.If the transformation is of the form algorithm/mode/padding:
CipherSpi
subclass for
"algorithm/mode/padding", return it. Otherwise
go to step 2.CipherSpi
subclass for
"algorithm/mode", instatiate it, call engineSetPadding(java.lang.String)
for the padding name, and return
it. Otherwise go to step 3.CipherSpi
subclass for
"algorithm//padding", instatiate it, call engineSetMode(java.lang.String)
for the mode name, and return
it. Otherwise go to step 4.CipherSpi
subclass for
"algorithm", instatiate it, call engineSetMode(java.lang.String)
for the mode name, call engineSetPadding(java.lang.String)
for the padding name, and return
it. Otherwise throw a NoSuchAlgorithmException
.Constructor and Description |
---|
CipherSpi()
Create a new CipherSpi.
|
Modifier and Type | Method and Description |
---|---|
protected abstract byte[] |
engineDoFinal(byte[] input,
int inputOffset,
int inputLength)
Finishes a multi-part transformation or transforms a portion of a
byte array, and returns the transformed bytes.
|
protected abstract int |
engineDoFinal(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 transformed bytes in the supplied array.
|
protected int |
engineDoFinal(ByteBuffer input,
ByteBuffer output) |
protected abstract int |
engineGetBlockSize()
Returns the block size of the underlying cipher.
|
protected abstract byte[] |
engineGetIV()
Returns the initializaiton vector this cipher was initialized with,
if any.
|
protected int |
engineGetKeySize(Key key)
Return the length of the given key in bits.
|
protected abstract int |
engineGetOutputSize(int inputLength)
Returns the size, in bytes, an output buffer must be for a call
to
engineUpdate(byte[],int,int,byte[],int) or engineDoFinal(byte[],int,int,byte[],int) to succeed. |
protected abstract AlgorithmParameters |
engineGetParameters()
Returns the parameters that this cipher is using.
|
protected abstract void |
engineInit(int opmode,
Key key,
AlgorithmParameterSpec params,
SecureRandom random)
Initializes this cipher with an operation mode, key, parameters,
and source of randomness.
|
protected abstract void |
engineInit(int opmode,
Key key,
AlgorithmParameters params,
SecureRandom random)
Initializes this cipher with an operation mode, key, parameters,
and source of randomness.
|
protected abstract void |
engineInit(int opmode,
Key key,
SecureRandom random)
Initializes this cipher with an operation mode, key, and source of
randomness.
|
protected abstract void |
engineSetMode(String mode)
Set the mode in which this cipher is to run.
|
protected abstract void |
engineSetPadding(String padding)
Set the method with which the input is to be padded.
|
protected Key |
engineUnwrap(byte[] wrappedKey,
String wrappedKeyAlgorithm,
int wrappedKeyType)
Unwraps a previously-wrapped key.
|
protected abstract byte[] |
engineUpdate(byte[] input,
int inputOffset,
int inputLength)
Continue with a multi-part transformation, returning a new array of
the transformed bytes.
|
protected abstract int |
engineUpdate(byte[] input,
int inputOffset,
int inputLength,
byte[] output,
int outputOffset)
Continue with a multi-part transformation, storing the transformed
bytes into the specified array.
|
protected int |
engineUpdate(ByteBuffer input,
ByteBuffer output) |
protected byte[] |
engineWrap(Key key)
Wrap a key.
|
public CipherSpi()
protected abstract byte[] engineDoFinal(byte[] input, int inputOffset, int inputLength) throws IllegalBlockSizeException, BadPaddingException
input
- The input bytes.inputOffset
- The index in the input at which to start.inputLength
- The number of bytes to transform.IllegalBlockSizeException
- If this instance has
no padding and the input size is not a multiple of the
block size.BadPaddingException
- If this instance is being
used for decryption and the padding is not appropriate for
this instance's padding scheme.protected abstract int engineDoFinal(byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset) throws IllegalBlockSizeException, BadPaddingException, ShortBufferException
input
- The input bytes.inputOffset
- The index in the input at which to start.inputLength
- The number of bytes to transform.output
- The output byte array.outputOffset
- The index in the output array at which to start.IllegalBlockSizeException
- If this instance has
no padding and the input size is not a multiple of the
block size.BadPaddingException
- If this instance is being
used for decryption and the padding is not appropriate for
this instance's padding scheme.ShortBufferException
- If there is not enough
space in the output array for the transformed bytes.protected int engineDoFinal(ByteBuffer input, ByteBuffer output) throws BadPaddingException, IllegalBlockSizeException, ShortBufferException
BadPaddingException
IllegalBlockSizeException
ShortBufferException
protected abstract int engineGetBlockSize()
protected abstract byte[] engineGetIV()
protected int engineGetKeySize(Key key) throws InvalidKeyException
Return the length of the given key in bits.
For compatibility this method is not declared
abstract
, and the default implementation will throw an
UnsupportedOperationException
. Concrete
subclasses should override this method to return the correct
value.
key
- The key to get the size for.InvalidKeyException
- If the key's length
cannot be determined by this implementation.protected abstract int engineGetOutputSize(int inputLength)
Returns the size, in bytes, an output buffer must be for a call
to engineUpdate(byte[],int,int,byte[],int)
or engineDoFinal(byte[],int,int,byte[],int)
to succeed.
The actual output length may be smaller than the value returned by this method, as it considers the padding length as well. The length considered is the argument plus the length of any buffered, unprocessed bytes.
inputLength
- The input length, in bytes.protected abstract AlgorithmParameters engineGetParameters()
null
if this
cipher does not use parameters.protected abstract void engineInit(int opmode, Key key, SecureRandom random) throws InvalidKeyException
opmode
- The operation mode, one of Cipher.DECRYPT_MODE
, Cipher.ENCRYPT_MODE
, Cipher.UNWRAP_MODE
, or Cipher.WRAP_MODE
.key
- The key to initialize this cipher with.random
- The source of random bytes to use.InvalidKeyException
- If the given key is not
acceptable for this implementation.protected abstract void engineInit(int opmode, Key key, AlgorithmParameters params, SecureRandom random) throws InvalidAlgorithmParameterException, InvalidKeyException
opmode
- The operation mode, one of Cipher.DECRYPT_MODE
, Cipher.ENCRYPT_MODE
, Cipher.UNWRAP_MODE
, or Cipher.WRAP_MODE
.key
- The key to initialize this cipher with.params
- The algorithm parameters to initialize with.random
- The source of random bytes to use.InvalidAlgorithmParameterException
- If the
given parameters are not appropriate for this
implementation.InvalidKeyException
- If the given key is not
acceptable for this implementation.protected abstract void engineInit(int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random) throws InvalidAlgorithmParameterException, InvalidKeyException
opmode
- The operation mode, one of Cipher.DECRYPT_MODE
, Cipher.ENCRYPT_MODE
, Cipher.UNWRAP_MODE
, or Cipher.WRAP_MODE
.key
- The key to initialize this cipher with.params
- The algorithm parameters to initialize with.random
- The source of random bytes to use.InvalidAlgorithmParameterException
- If the
given parameters are not appropriate for this
implementation.InvalidKeyException
- If the given key is not
acceptable for this implementation.protected abstract void engineSetMode(String mode) throws NoSuchAlgorithmException
mode
- The name of the mode to use.NoSuchAlgorithmException
- If the mode is
not supported by this cipher's provider.protected abstract void engineSetPadding(String padding) throws NoSuchPaddingException
padding
- The name of the padding to use.NoSuchPaddingException
- If the padding is not
supported by this cipher's provider.protected Key engineUnwrap(byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType) throws InvalidKeyException, NoSuchAlgorithmException
Unwraps a previously-wrapped key.
For compatibility this method is not declared
abstract
, and the default implementation will throw an
UnsupportedOperationException
.
wrappedKey
- The wrapped key.wrappedKeyAlgorithm
- The name of the algorithm used to wrap
this key.wrappedKeyType
- The type of wrapped key; one of
Cipher.PRIVATE_KEY
,
Cipher.PUBLIC_KEY
, or
Cipher.SECRET_KEY
.InvalidKeyException
- If the key cannot be
unwrapped, or if wrappedKeyType
is an
inappropriate type for the unwrapped key.NoSuchAlgorithmException
- If the
wrappedKeyAlgorithm
is unknown.protected abstract byte[] engineUpdate(byte[] input, int inputOffset, int inputLength)
input
- The next input bytes.inputOffset
- The index in the input array from which to start.inputLength
- The number of bytes to input.protected abstract int engineUpdate(byte[] input, int inputOffset, int inputLength, byte[] output, int outputOffset) throws ShortBufferException
input
- The next input bytes.inputOffset
- The index in the input from which to start.inputLength
- The number of bytes to input.output
- The output buffer.outputOffset
- The index in the output array from which to start.ShortBufferException
- If there is not enough
space in the output array to store the transformed bytes.protected int engineUpdate(ByteBuffer input, ByteBuffer output) throws ShortBufferException
ShortBufferException
protected byte[] engineWrap(Key key) throws InvalidKeyException, IllegalBlockSizeException
Wrap a key.
For compatibility this method is not declared
abstract
, and the default implementation will throw an
UnsupportedOperationException
.
key
- The key to wrap.InvalidKeyException
- If the key cannot be
wrapped.IllegalBlockSizeException