Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)
Android APIs
public abstract class

CipherSpi

extends Object
java.lang.Object
   ↳ javax.crypto.CipherSpi

Class Overview

This class defines the Service Provider Interface ( SPI ) for cryptographic ciphers.

Implementers of cryptographic ciphers must implement all the abstract methods for every cipher they implement. CipherSpi instances are created along with ciphers when the getInstance(String) method is called. A Cipher is referenced by a transformation , which is a string that describes the operation (or set of operations), always consisting of the cipher's name and optionally followed by a mode and a padding, in the form:

  • "algorithm"
    • or
  • "algorithm/mode/padding"
The following behavior should be implemented for obtaining Cipher instances.

When one of the getInstance(String) factory methods is called with a transformation that is only an algorithm , check if the provider defines a CipherSpi for "algorithm", if so: return it, otherwise throw a NoSuchAlgorithmException .

The following rules apply when a transformation is of the form "algorithm/mode/padding":

    1. The Provider has a CipherSpi subclass registered for "algorithm/mode/padding": return it, otherwise go to step 2.
    2. The Provider has a CipherSpi subclass registered for "algorithm/mode": instantiate it, call engineSetPadding(String) for the padding name and return it, otherwise go to step 3.
    3. The Provider has a CipherSpi subclass registered for "algorithm//padding": instantiate it, call engineSetMode(String) for the mode name and return it, otherwise go to step 4.

See Also

Summary

Public Constructors
CipherSpi ()
Creates a new CipherSpi instance.
Protected Methods
abstract byte[] engineDoFinal (byte[] input, int inputOffset, int inputLen)
Finishes a multi-part transformation (encryption or decryption).
int engineDoFinal ( ByteBuffer input, ByteBuffer output)
Finishes a multi-part transformation (encryption or decryption).
abstract int engineDoFinal (byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
Finishes a multi-part transformation (encryption or decryption).
abstract int engineGetBlockSize ()
Returns the block size of this cipher (in bytes)
abstract byte[] engineGetIV ()
Returns the Initialization Vector (IV) that was used to initialize this cipher or null if none was used.
int engineGetKeySize ( Key key)
Returns the size of a specified key object in bits.
abstract int engineGetOutputSize (int inputLen)
Returns the size for a buffer (in bytes), that the next call to update of doFinal would return, taking into account any buffered data from previous update calls and padding.
abstract AlgorithmParameters engineGetParameters ()
Returns the parameters that where used to create this cipher instance.
abstract void engineInit (int opmode, Key key, AlgorithmParameters params, SecureRandom random)
Initializes this cipher instance with the specified key, algorithm parameters and a source of randomness.
abstract void engineInit (int opmode, Key key, SecureRandom random)
Initializes this cipher instance with the specified key and a source of randomness.
abstract void engineInit (int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random)
Initializes this cipher instance with the specified key, algorithm parameters and a source of randomness.
abstract void engineSetMode ( String mode)
Sets the mode for this cipher.
abstract void engineSetPadding ( String padding)
Sets the padding method for this cipher.
Key engineUnwrap (byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType)
Unwraps a key using this cipher instance.
int engineUpdate ( ByteBuffer input, ByteBuffer output)
Continues a multi-part transformation (encryption or decryption).
abstract int engineUpdate (byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
Continues a multi-part transformation (encryption or decryption).
abstract byte[] engineUpdate (byte[] input, int inputOffset, int inputLen)
Continues a multi-part transformation (encryption or decryption).
void engineUpdateAAD (byte[] input, int inputOffset, int inputLen)
Continues a multi-part transformation (encryption or decryption) with Authenticated Additional Data (AAD).
void engineUpdateAAD ( ByteBuffer input)
Continues a multi-part transformation (encryption or decryption).
byte[] engineWrap ( Key key)
Wraps a key using this cipher instance.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public CipherSpi ()

Added in API level 1

Creates a new CipherSpi instance.

Protected Methods

protected abstract byte[] engineDoFinal (byte[] input, int inputOffset, int inputLen)

Added in API level 1

Finishes a multi-part transformation (encryption or decryption).

Processes the inputLen bytes in input buffer at inputOffset , and any bytes that have been buffered in previous update calls.

Parameters
input the input buffer.
inputOffset the offset in the input buffer.
inputLen the length of the input.
Returns
  • the final bytes from the transformation.
Throws
IllegalBlockSizeException if the size of the resulting bytes is not a multiple of the cipher block size.
BadPaddingException if the padding of the data does not match the padding scheme.

protected int engineDoFinal ( ByteBuffer input, ByteBuffer output)

Added in API level 1

Finishes a multi-part transformation (encryption or decryption).

Processes the input.remaining() bytes in input buffer at input.position() , and any bytes that have been buffered in previous update calls. The transformed bytes are placed into output buffer.

Parameters
input the input buffer.
output the output buffer.
Returns
  • the number of bytes placed into the output buffer.
Throws
ShortBufferException if the size of the output buffer is too small.
IllegalBlockSizeException if the size of the resulting bytes is not a multiple of the cipher block size.
BadPaddingException if the padding of the data does not match the padding scheme.
IllegalArgumentException if the input buffer and the output buffer are the same object.
IllegalStateException if this cipher instance is not initialized for encryption or decryption.

protected abstract int engineDoFinal (byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)

Added in API level 1

Finishes a multi-part transformation (encryption or decryption).

Processes the inputLen bytes in input buffer at inputOffset , and any bytes that have been buffered in previous update calls.

Parameters
input the input buffer.
inputOffset the offset in the input buffer.
inputLen the length of the input.
output the output buffer for the transformed bytes.
outputOffset the offset in the output buffer.
Returns
  • the number of bytes placed in the output buffer.
Throws
ShortBufferException if the size of the output buffer is too small.
IllegalBlockSizeException if the size of the resulting bytes is not a multiple of the cipher block size.
BadPaddingException if the padding of the data does not match the padding scheme.

protected abstract int engineGetBlockSize ()

Added in API level 1

Returns the block size of this cipher (in bytes)

Returns
  • the block size of this cipher, or zero if this cipher is not a block cipher.

protected abstract byte[] engineGetIV ()

Added in API level 1

Returns the Initialization Vector (IV) that was used to initialize this cipher or null if none was used.

Returns
  • the Initialization Vector (IV), or null if none was used.

protected int engineGetKeySize ( Key key)

Added in API level 1

Returns the size of a specified key object in bits. This method has been added to this class (for backwards compatibility, it cannot be abstract). If this method is not overridden, it throws an UnsupportedOperationException .

Parameters
key the key to get the size for.
Returns
  • the size of a specified key object in bits.
Throws
InvalidKeyException if the size of the key cannot be determined by this implementation.

protected abstract int engineGetOutputSize (int inputLen)

Added in API level 1

Returns the size for a buffer (in bytes), that the next call to update of doFinal would return, taking into account any buffered data from previous update calls and padding.

The actual output length of the next call to update or doFinal may be smaller than the length returned by this method.

Parameters
inputLen the length of the input (in bytes).
Returns
  • the size for a buffer (in bytes).

protected abstract AlgorithmParameters engineGetParameters ()

Added in API level 1

Returns the parameters that where used to create this cipher instance.

These may be a the same parameters that were used to create this cipher instance, or may be a combination of default and random parameters, depending on the underlying cipher implementation.

Returns
  • the parameters that where used to create this cipher instance, or null if this cipher instance does not have any parameters at all.

protected abstract void engineInit (int opmode, Key key, AlgorithmParameters params, SecureRandom random)

Added in API level 1

Initializes this cipher instance with the specified key, algorithm parameters and a source of randomness.

The cipher will be initialized for the specified operation (one of: encryption, decryption, key wrapping or key unwrapping) depending on opmode .

If this cipher instance needs any algorithm parameters and params is null , the underlying implementation of this cipher is supposed to generate the required parameters (using its provider or random values). Random values are generated using random .

When a cipher instance is initialized by a call to any of the init methods, the state of the instance is overridden, means it is equivalent to creating a new instance and calling it init method.

Parameters
opmode the operation this cipher instance should be initialized for (one of: ENCRYPT_MODE , DECRYPT_MODE , WRAP_MODE or UNWRAP_MODE ).
key the input key for the operation.
params the algorithm parameters.
random the source of randomness to use.
Throws
InvalidKeyException if the specified key cannot be used to initialize this cipher instance.
InvalidAlgorithmParameterException if the specified parameters are inappropriate for this cipher.

protected abstract void engineInit (int opmode, Key key, SecureRandom random)

Added in API level 1

Initializes this cipher instance with the specified key and a source of randomness.

The cipher will be initialized for the specified operation (one of: encryption, decryption, key wrapping or key unwrapping) depending on opmode .

If this cipher instance needs any algorithm parameters or random values that the specified key cannot provide, the underlying implementation of this cipher is supposed to generate the required parameters (using its provider or random values). Random values will be generated using random ;

When a cipher instance is initialized by a call to any of the init methods, the state of the instance is overridden, means it is equivalent to creating a new instance and calling it init method.

Parameters
opmode the operation this cipher instance should be initialized for (one of: ENCRYPT_MODE , DECRYPT_MODE , WRAP_MODE or UNWRAP_MODE ).
key the input key for the operation.
random the source of randomness to use.
Throws
InvalidKeyException if the specified key cannot be used to initialize this cipher instance.

protected abstract void engineInit (int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random)

Added in API level 1

Initializes this cipher instance with the specified key, algorithm parameters and a source of randomness.

The cipher will be initialized for the specified operation (one of: encryption, decryption, key wrapping or key unwrapping) depending on opmode .

If this cipher instance needs any algorithm parameters and params is null , the underlying implementation of this cipher is supposed to generate the required parameters (using its provider or random values). Random values are generated using random .

When a cipher instance is initialized by a call to any of the init methods, the state of the instance is overridden, means it is equivalent to creating a new instance and calling it init method.

Parameters
opmode the operation this cipher instance should be initialized for (one of: ENCRYPT_MODE , DECRYPT_MODE , WRAP_MODE or UNWRAP_MODE ).
key the input key for the operation.
params the algorithm parameters.
random the source of randomness to use.
Throws
InvalidKeyException if the specified key cannot be used to initialize this cipher instance.
InvalidAlgorithmParameterException it the specified parameters are inappropriate for this cipher.

protected abstract void engineSetMode ( String mode)

Added in API level 1

Sets the mode for this cipher.

Parameters
mode the name of the cipher mode.
Throws
NoSuchAlgorithmException if the specified cipher mode is not supported by this provider.

protected abstract void engineSetPadding ( String padding)

Added in API level 1

Sets the padding method for this cipher.

Parameters
padding the name of the padding method.
Throws
NoSuchPaddingException if the specified padding method is not supported by this cipher.

protected Key engineUnwrap (byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType)

Added in API level 1

Unwraps a key using this cipher instance.

This method has been added to this class (for backwards compatibility, it cannot be abstract). If this method is not overridden, it throws an UnsupportedOperationException .

Parameters
wrappedKey the wrapped key to unwrap.
wrappedKeyAlgorithm the algorithm for the wrapped key.
wrappedKeyType the type of the wrapped key (one of: SECRET_KEY , PRIVATE_KEY or PUBLIC_KEY )
Returns
  • the unwrapped key.
Throws
InvalidKeyException if the wrappedKey cannot be unwrapped to a key of type wrappedKeyType for the wrappedKeyAlgorithm .
NoSuchAlgorithmException if no provider can be found that can create a key of type wrappedKeyType for the wrappedKeyAlgorithm .

protected int engineUpdate ( ByteBuffer input, ByteBuffer output)

Added in API level 1

Continues a multi-part transformation (encryption or decryption). The input.remaining() bytes starting at input.position() are transformed and stored in the output buffer.

If the output.remaining() is too small to hold the transformed bytes a ShortBufferException is thrown. Use getOutputSize to check for the size of the output buffer.

Parameters
input the input buffer to transform.
output the output buffer to store the result within.
Returns
  • the number of bytes stored in the output buffer.
Throws
ShortBufferException if the size of the output buffer is too small.

protected abstract int engineUpdate (byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)

Added in API level 1

Continues a multi-part transformation (encryption or decryption). The transformed bytes are stored in the output buffer.

If the size of the output buffer is too small to hold the result, a ShortBufferException is thrown. Use getOutputSize to check for the size of the output buffer.

Parameters
input the input bytes to transform.
inputOffset the offset in the input to start.
inputLen the length of the input to transform.
output the output buffer.
outputOffset the offset in the output buffer.
Returns
  • the number of bytes placed in output.
Throws
ShortBufferException if the size of the output buffer is too small.

protected abstract byte[] engineUpdate (byte[] input, int inputOffset, int inputLen)

Added in API level 1

Continues a multi-part transformation (encryption or decryption). The transformed bytes are returned.

Parameters
input the input bytes to transform.
inputOffset the offset in the input to start.
inputLen the length of the input to transform.
Returns
  • the transformed bytes in a new buffer, or null if the input has zero length.
Throws
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
IllegalArgumentException if the input is null, or if inputOffset and inputLen do not specify a valid chunk in the input buffer.

protected void engineUpdateAAD (byte[] input, int inputOffset, int inputLen)

Continues a multi-part transformation (encryption or decryption) with Authenticated Additional Data (AAD). AAD may only be added after the Cipher is initialized and before any data is passed to the instance.

This is only usable with cipher modes that support Authenticated Encryption with Additional Data (AEAD) such as Galois/Counter Mode (GCM).

Parameters
input bytes of AAD to use with the cipher
inputOffset offset within bytes of additional data to add to cipher
inputLen length of bytes of additional data to add to cipher
Throws
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
IllegalArgumentException if input is null , or if inputOffset and inputLen do not specify a valid chunk in the input buffer.
UnsupportedOperationException if the cipher does not support AEAD

protected void engineUpdateAAD ( ByteBuffer input)

Continues a multi-part transformation (encryption or decryption). The input.remaining() bytes starting at input.position() are used for the Additional Authenticated Data (AAD). AAD may only be added after the Cipher is initialized and before any data is passed to the instance.

This is only usable with cipher modes that support Authenticated Encryption with Additional Data (AEAD) such as Galois/Counter Mode (GCM).

Parameters
input the input buffer to transform.

protected byte[] engineWrap ( Key key)

Added in API level 1

Wraps a key using this cipher instance. This method has been added to this class (for backwards compatibility, it cannot be abstract). If this method is not overridden, it throws an UnsupportedOperationException .

Parameters
key the key to wrap.
Returns
  • the wrapped key
Throws
IllegalBlockSizeException if the size of the resulting bytes is not a multiple of the cipher block size.
InvalidKeyException if this cipher instance cannot wrap this key.