javax.crypto
Class CipherSpi

java.lang.Object
  |
  +--javax.crypto.CipherSpi
Direct Known Subclasses:
iaik.security.cipher.BufferedCipher, RSACipher

public abstract class CipherSpi
extends Object

Service Provider Interface (SPI) for the Cipher class.


Attention:  This is not a SUN implementation!

This class has been developed by IAIK according to the documentation publically available.
For SUNīs documentation of this class see http://java.sun.com/security/JCE1.2/spec/apidoc/index.html


This class represents the super SPI abstract class for cipher handling and has to be implemented by a data en/decryption supporting provider for registering with the Java Security framework. Within the IAIK provider environment this class is extended by the iaik.security.cipher.BufferedCipher class for providing an automatical buffering mechanism.

This class contains a set of abstract engine methods which have to be implemented by a provider and are called by their appertaining Cipher equivalents for accessing provider specific implementations.

Any application dealing en/decryption, uses the getInstance method of the Cipher class for creating a cipher object.

Version:
File Revision 18
See Also:
KeyGenerator, SecretKey, AlgorithmParameters, AlgorithmParameterSpec, BufferedCipher, Cipher

Constructor Summary
CipherSpi()
          Constructor used for dynamic instantiation.
 
Method Summary
protected abstract  byte[] engineDoFinal(byte[] input, int inputOffset, int inputLen)
          Returns the result of the last step of a multi-step en/decryption operation or the result of a single-step en/decryption operation by processing the given input data and any remaining buffered data.
protected abstract  int engineDoFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
          Performs the last step of a multi-step en/decryption operation or a single-step en/decryption operation by processing the given input data and any remaining buffered data.
protected abstract  int engineGetBlockSize()
          Returns the block size corresponding to this cipher.
protected abstract  byte[] engineGetIV()
          Returns a byte array containing the initialization vector (IV).
protected  int engineGetKeySize(Key key)
          New method in JCE 1.2.1
protected abstract  int engineGetOutputSize(int inputLen)
          Returns the output buffer size necessary for capturing the data resulting from the next update or doFinal operation including any data currently being buffered.
protected abstract  AlgorithmParameters engineGetParameters()
          Returns the parameters used with this cipher.
protected abstract  void engineInit(int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random)
          Initializes this cipher object with proper key and algorithm parameters, and some random seed.
protected abstract  void engineInit(int opmode, Key key, AlgorithmParameters params, SecureRandom random)
          Initializes this cipher with a key, a set of algorithm parameters, and a source of randomness.
protected abstract  void engineInit(int opmode, Key key, SecureRandom random)
          Initializes this cipher object with a proper key and some random seed.
protected abstract  void engineSetMode(String mode)
          Sets the mode of this cipher.
protected abstract  void engineSetPadding(String padding)
          Sets the padding scheme of this cipher.
protected  Key engineUnwrap(byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType)
          Engine method for key unwrapping.
protected abstract  byte[] engineUpdate(byte[] input, int inputOffset, int inputLen)
          Returns the result of the next step of a multi-step en/decryption operation.
protected abstract  int engineUpdate(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
          Performs the next step of a multi-step en/decryption operation.
protected  byte[] engineWrap(Key key)
          Engine method for key wrapping.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CipherSpi

public CipherSpi()
Constructor used for dynamic instantiation.
Method Detail

engineSetMode

protected abstract void engineSetMode(String mode)
                               throws NoSuchAlgorithmException
Sets the mode of this cipher. If an application creates a cipher object by calling Cipher.getInstance(...) without specifying a particular cipher mode, engineSetMode is supplied with the default "ECB" mode.
Parameters:
mode - the cipher mode
Throws:
NoSuchAlgorithmException - if this cipher mode is not supported
See Also:
BufferedCipher.engineSetMode(java.lang.String)

engineSetPadding

protected abstract void engineSetPadding(String padding)
                                  throws NoSuchPaddingException
Sets the padding scheme of this cipher. If an application creates a cipher object by calling Cipher.getInstance(...) without specifying a particular padding scheme, engineSetMode is supplied with the default "NoPadding" scheme.
Parameters:
padding - the padding scheme
Throws:
NoSuchPaddingException - if this padding scheme is not supported
See Also:
BufferedCipher.engineSetPadding(java.lang.String)

engineGetBlockSize

protected abstract int engineGetBlockSize()
Returns the block size corresponding to this cipher. The block size is returned in bytes. If the implemented algorithm is not a block cipher, 0 is returned.
Returns:
the block size (in bytes) if this cipher is a block cipher, 0 otherwise.
See Also:
Cipher.getBlockSize(), BufferedCipher.engineGetBlockSize()

engineGetOutputSize

protected abstract int engineGetOutputSize(int inputLen)
Returns the output buffer size necessary for capturing the data resulting from the next update or doFinal operation including any data currently being buffered.
Parameters:
inputLen - the number of bytes to process
Returns:
the size of the output buffer (in bytes)
See Also:
Cipher.getOutputSize(int), BufferedCipher.engineGetOutputSize(int)

engineGetIV

protected abstract byte[] engineGetIV()
Returns a byte array containing the initialization vector (IV). If the algorithm corresponding to this cipher object does not use an initialization vector, null is returned.
Returns:
the initialization vector in a byte array if this cipher object operates with an IV and the IV already has been set, null otherwise.
See Also:
Cipher.getIV(), BufferedCipher.engineGetIV()

engineGetParameters

protected abstract AlgorithmParameters engineGetParameters()
Returns the parameters used with this cipher. 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).
Returns:
the parameters used with this cipher, or null if this cipher does not use any parameters

engineInit

protected abstract void engineInit(int opmode,
                                   Key key,
                                   SecureRandom random)
                            throws InvalidKeyException
Initializes this cipher object with a proper key and some random seed. Before a cipher object is ready for data processing, it has to be initialized according to the desired cryptographic operation, which is specified by the opmode parameter (either ENCRYPT_MODE or DECCRYPT_MODE).

e.g. cipher_obj.init(Cipher.ENCRYPT_MODE, key, random_seed);

The Cipher init will call the proper CipherSpi engineInit method.

If this cipher (including its underlying feedback or padding scheme) requires any random bytes, it will get them from random.

Parameters:
opmode - the operation mode for which this cipher is used (ENCRYPT_MODE or DECRYPT_MODE)
key - the key
random - the random seed
Throws:
InvalidKeyException - if the given key cannot be used for initializing this cipher
See Also:
Cipher.init(int, java.security.Key), BufferedCipher.engineInit(int, java.security.Key, java.security.spec.AlgorithmParameterSpec, java.security.SecureRandom)

engineInit

protected abstract void engineInit(int opmode,
                                   Key key,
                                   AlgorithmParameterSpec params,
                                   SecureRandom random)
                            throws InvalidKeyException,
                                   InvalidAlgorithmParameterException
Initializes this cipher object with proper key and algorithm parameters, and some random seed. Before a cipher object is ready for data processing, it has to be initialized according to the desired cryptographic operation, which is specified by the opmode parameter (either ENCRYPT_MODE or DECCRYPT_MODE).

e.g. cipher_obj.init(Cipher.ENCRYPT_MODE, key, alg_params, random_seed);

The Cipher init will call the proper CipherSpi engineInit method.

Parameters:
opmode - the operation mode for which this cipher is used (ENCRYPT_MODE or DECRYPT_MODE)
key - the key
params - the algorithm parameters
random - the random seed
Throws:
InvalidKeyException - if the given key cannot be used for initializing this cipher
InvalidAlgorithmParameterException - if the given algorithm parameters donīt match to this cipher
See Also:
Cipher.init(int, java.security.Key), BufferedCipher.engineInit(int, java.security.Key, java.security.spec.AlgorithmParameterSpec, java.security.SecureRandom)

engineInit

protected abstract void engineInit(int opmode,
                                   Key key,
                                   AlgorithmParameters params,
                                   SecureRandom random)
                            throws InvalidKeyException,
                                   InvalidAlgorithmParameterException
Initializes this cipher with a key, a set of algorithm parameters, and a source of randomness. 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.
Parameters:
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 randomness
Throws:
InvalidKeyException - if the given key is inappropriate for initializing thiscipher
InvalidAlgorithmParameterException - if the given algorithm parameters are inappropriate for this cipher

engineUpdate

protected abstract byte[] engineUpdate(byte[] input,
                                       int inputOffset,
                                       int inputLen)
Returns the result of the next step of a multi-step en/decryption operation. The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted. The result is returned as a byte array.
Parameters:
input - the byte array holding the data to be processed
inputOffset - the offset indicating the start position within the input byte array
inputLen - the number of bytes to be processed
Returns:
the byte array containing the en/decrypted data
See Also:
Cipher.update(byte[]), BufferedCipher.engineUpdate(byte[], int, int)

engineUpdate

protected abstract int engineUpdate(byte[] input,
                                    int inputOffset,
                                    int inputLen,
                                    byte[] output,
                                    int outputOffset)
                             throws ShortBufferException
Performs the next step of a multi-step en/decryption operation. The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted. The result is stored in the given output byte array, beginning at outputOffset. The number of bytes stored in this output byte array are returned.
Parameters:
input - the byte array holding the data to be processed
inputOffset - the offset indicating the start position within the input byte array
inputLen - the number of bytes to be processed
output - the byte array for holding the result
outputOffset - the offset indicating the start position within the output byte array to which the en/decrypted data is written
Returns:
the number of bytes that are stored in the output byte array
Throws:
ShortBufferException - if the given output buffer is too small for holding the result
See Also:
Cipher.update(byte[]), BufferedCipher.engineUpdate(byte[], int, int)

engineDoFinal

protected abstract byte[] engineDoFinal(byte[] input,
                                        int inputOffset,
                                        int inputLen)
                                 throws IllegalBlockSizeException,
                                        BadPaddingException
Returns the result of the last step of a multi-step en/decryption operation or the result of a single-step en/decryption operation by processing the given input data and any remaining buffered data. The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted, including any buffered bytes of a previous update operation. If necessary, padding is performed. The result is returned as a output byte array.
Parameters:
input - the byte array holding the data to be processed
inputOffset - the offset indicating the start position within the input byte array
inputLen - the number of bytes to be processed
Returns:
the byte array containing the en/decrypted data
Throws:
IllegalBlockSizeException - if the total length of the processed data is not a multiple of the block size for a (no padding performing) block cipher
BadPaddingException - if the decrypted data is not bounded by the proper padding bytes after data decryption including (un)padding
See Also:
Cipher.doFinal()

engineDoFinal

protected abstract int engineDoFinal(byte[] input,
                                     int inputOffset,
                                     int inputLen,
                                     byte[] output,
                                     int outputOffset)
                              throws ShortBufferException,
                                     IllegalBlockSizeException,
                                     BadPaddingException
Performs the last step of a multi-step en/decryption operation or a single-step en/decryption operation by processing the given input data and any remaining buffered data. The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted, including any buffered bytes of a previous update operation. If necessary, padding is performed. The result is stored in the given output byte array, beginning at outputOffset. The number of bytes stored in this byte array are returned.
Parameters:
input - the byte array holding the data to be processed
inputOffset - the offset indicating the start position within the input byte array
inputLen - the number of bytes to be processed
output - the byte array for holding the result
outputOffset - the offset indicating the start position within the output byte array to which the en/decrypted data is written
Returns:
the number of bytes stored in the output byte array
Throws:
ShortBufferException - if the given output buffer is too small for holding the result
IllegalBlockSizeException - if the total length of the processed data is not a multiple of the block size for a (no padding performing) block cipher
BadPaddingException - if the decrypted data is not bounded by the proper padding bytes after data decryption including (un)padding
See Also:
Cipher.doFinal()

engineGetKeySize

protected int engineGetKeySize(Key key)
                        throws InvalidKeyException
New method in JCE 1.2.1

engineWrap

protected byte[] engineWrap(Key key)
                     throws IllegalBlockSizeException,
                            InvalidKeyException
Engine method for key wrapping. Since JCE 1.2.1

engineUnwrap

protected Key engineUnwrap(byte[] wrappedKey,
                           String wrappedKeyAlgorithm,
                           int wrappedKeyType)
                    throws InvalidKeyException,
                           NoSuchAlgorithmException
Engine method for key unwrapping. Since JCE 1.2.1

This Javadoc may contain text parts from Internet Standard specifications (RFC 2459, 3280, 3039, 2560, 1521, 821, 822, 2253, 1319, 1321, ,2630, 2631, 2268, 3058, 2984, 2104, 2144, 2040, 2311, 2279, see copyright note) and RSA Data Security Public-Key Cryptography Standards (PKCS#1,3,5,7,8,9,10,12, see copyright note).

IAIK-JCE 3.1 with IAIK-JCE CC Core 3.1, (c) 1997-2004 IAIK