javax.crypto
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 {@link java.security.Provider}.
CipherSpi objects are instantiated along with {@link Cipher}s when the {@link 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 {@link java.security.Provider} class may be:
Cipher.algorithmCipher.algorithm/modeCipher.algorithm//paddingCipher.algorithm/mode/paddingWhen any {@link 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 {@link
java.security.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 {@link
#engineSetPadding(java.lang.String)} for the padding name, and return
it. Otherwise go to step 3.CipherSpi subclass for
"algorithm//padding", instatiate it, call {@link
#engineSetMode(java.lang.String)} for the mode name, and return
it. Otherwise go to step 4.CipherSpi subclass for
"algorithm", instatiate it, call {@link
#engineSetMode(java.lang.String)} for the mode name, call {@link
#engineSetPadding(java.lang.String)} for the padding name, and return
it. Otherwise throw a {@link java.security.NoSuchAlgorithmException}.Since: 1.4
| Constructor Summary | |
|---|---|
| CipherSpi()
Create a new CipherSpi. | |
| Method Summary | |
|---|---|
| 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. For compatibility this method is not declared
|
| protected abstract int | engineGetOutputSize(int inputLength) Returns the size, in bytes, an output buffer must be for a call to {@link #engineUpdate(byte[],int,int,byte[],int)} or {@link #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. |
| protected abstract AlgorithmParameters | engineGetParameters()
Returns the parameters that this cipher is using. |
| 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 | 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, AlgorithmParameterSpec params, SecureRandom random)
Initializes this cipher with an operation mode, key, parameters,
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. For compatibility this method is not declared
|
| 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. For compatibility this method is not declared
|
Parameters: input The input bytes. inputOffset The index in the input at which to start. inputLength The number of bytes to transform.
Returns: The transformed bytes in a new array.
Throws: javax.crypto.IllegalBlockSizeException If this instance has no padding and the input size is not a multiple of the block size. javax.crypto.BadPaddingException If this instance is being used for decryption and the padding is not appropriate for this instance's padding scheme.
Parameters: 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.
Returns: The number of transformed bytes stored in the output array.
Throws: javax.crypto.IllegalBlockSizeException If this instance has no padding and the input size is not a multiple of the block size. javax.crypto.BadPaddingException If this instance is being used for decryption and the padding is not appropriate for this instance's padding scheme. javax.crypto.ShortBufferException If there is not enough space in the output array for the transformed bytes.
Since: 1.5
Returns: The block size.
Returns: The IV, or null if this cipher uses no IV or if this instance has not been initialized yet.
Return the length of the given key in bits.
For compatibility this method is not declared
abstract, and the default implementation will throw an
{@link java.lang.UnsupportedOperationException}. Concrete
subclasses should override this method to return the correct
value.
Parameters: key The key to get the size for.
Returns: The size of the key, in bits.
Throws: java.security.InvalidKeyException If the key's length cannot be determined by this implementation.
Returns the size, in bytes, an output buffer must be for a call to {@link #engineUpdate(byte[],int,int,byte[],int)} or {@link #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.
Parameters: inputLength The input length, in bytes.
Returns: The size an output buffer must be.
Returns: This cipher's parameters, or null if this
cipher does not use parameters.
Parameters: opmode The operation mode, one of {@link Cipher#DECRYPT_MODE}, {@link Cipher#ENCRYPT_MODE}, {@link Cipher#UNWRAP_MODE}, or {@link Cipher#WRAP_MODE}. key The key to initialize this cipher with. random The source of random bytes to use.
Throws: java.security.InvalidKeyException If the given key is not acceptable for this implementation.
Parameters: opmode The operation mode, one of {@link Cipher#DECRYPT_MODE}, {@link Cipher#ENCRYPT_MODE}, {@link Cipher#UNWRAP_MODE}, or {@link 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.
Throws: java.security.InvalidAlgorithmParameterException If the given parameters are not appropriate for this implementation. java.security.InvalidKeyException If the given key is not acceptable for this implementation.
Parameters: opmode The operation mode, one of {@link Cipher#DECRYPT_MODE}, {@link Cipher#ENCRYPT_MODE}, {@link Cipher#UNWRAP_MODE}, or {@link 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.
Throws: java.security.InvalidAlgorithmParameterException If the given parameters are not appropriate for this implementation. java.security.InvalidKeyException If the given key is not acceptable for this implementation.
Parameters: mode The name of the mode to use.
Throws: java.security.NoSuchAlgorithmException If the mode is not supported by this cipher's provider.
Parameters: padding The name of the padding to use.
Throws: javax.crypto.NoSuchPaddingException If the padding is not supported by this cipher's provider.
Unwraps a previously-wrapped key.
For compatibility this method is not declared
abstract, and the default implementation will throw an
{@link java.lang.UnsupportedOperationException}.
Parameters: wrappedKey The wrapped key. wrappedKeyAlgorithm The name of the algorithm used to wrap this key. wrappedKeyType The type of wrapped key; one of {@link Cipher#PRIVATE_KEY}, {@link Cipher#PUBLIC_KEY}, or {@link Cipher#SECRET_KEY}.
Returns: The unwrapped key.
Throws: java.security.InvalidKeyException If the key cannot be
unwrapped, or if wrappedKeyType is an
inappropriate type for the unwrapped key. java.security.NoSuchAlgorithmException If the
wrappedKeyAlgorithm is unknown.
Parameters: input The next input bytes. inputOffset The index in the input array from which to start. inputLength The number of bytes to input.
Returns: The transformed bytes.
Parameters: 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.
Returns: The transformed bytes.
Throws: javax.crypto.ShortBufferException If there is not enough space in the output array to store the transformed bytes.
Since: 1.5
Wrap a key.
For compatibility this method is not declared
abstract, and the default implementation will throw an
{@link java.lang.UnsupportedOperationException}.
Parameters: key The key to wrap.
Returns: The wrapped key.
Throws: java.security.InvalidKeyException If the key cannot be wrapped.