Overview Package Class Use Source Tree Index Deprecated About
Prev Class | Next ClassFrames | No Frames
Summary: Nested | Field | Method | ConstrDetail: Nested | Field | Method | Constr

javax.crypto

Class CipherSpi

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 Ciphers when the Cipher.getInstance(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:

  1. The algorithm's name, which uses a pluggable mode and padding: Cipher.algorithm
  2. The algorithm's name and the mode, which uses pluggable padding: Cipher.algorithm/mode
  3. The algorithm's name and the padding, which uses a pluggable mode: Cipher.algorithm//padding
  4. The algorihtm's name, the mode, and the padding: Cipher.algorithm/mode/padding

When any Cipher.getInstance(String) method is invoked, the following happens if the transformation is simply algorithm:

  1. If the provider defines a CipherSpi implementation for "algorithm", return it. Otherwise throw a NoSuchAlgorithmException.

If the transformation is of the form algorithm/mode/padding:

  1. If the provider defines a CipherSpi subclass for "algorithm/mode/padding", return it. Otherwise go to step 2.
  2. If the provider defines a CipherSpi subclass for "algorithm/mode", instatiate it, call engineSetPadding(String) for the padding name, and return it. Otherwise go to step 3.
  3. If the provider defines a CipherSpi subclass for "algorithm//padding", instatiate it, call engineSetMode(String) for the mode name, and return it. Otherwise go to step 4.
  4. If the provider defines a CipherSpi subclass for "algorithm", instatiate it, call engineSetMode(String) for the mode name, call engineSetPadding(String) for the padding name, and return it. Otherwise throw a 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 abstract, and the default implementation will throw an UnsupportedOperationException.

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.

protected abstract AlgorithmParameters
engineGetParameters()
Returns the parameters that this cipher is using.
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
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 abstract, and the default implementation will throw an UnsupportedOperationException.

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 abstract, and the default implementation will throw an UnsupportedOperationException.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

CipherSpi

public CipherSpi()
Create a new CipherSpi.

Method Details

engineDoFinal

protected abstract byte[] engineDoFinal(byte[] input,
                                        int inputOffset,
                                        int inputLength)
            throws IllegalBlockSizeException,
                   BadPaddingException
Finishes a multi-part transformation or transforms a portion of a byte array, and returns the transformed bytes.
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:
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.

engineDoFinal

protected abstract int engineDoFinal(byte[] input,
                                     int inputOffset,
                                     int inputLength,
                                     byte[] output,
                                     int outputOffset)
            throws IllegalBlockSizeException,
                   BadPaddingException,
                   ShortBufferException
Finishes a multi-part transformation or transforms a portion of a byte array, and stores the transformed bytes in the supplied array.
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:
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.

engineDoFinal

protected int engineDoFinal(ByteBuffer input,
                            ByteBuffer output)
            throws BadPaddingException,
                   IllegalBlockSizeException,
                   ShortBufferException
Since:
1.5

engineGetBlockSize

protected abstract int engineGetBlockSize()
Returns the block size of the underlying cipher.
Returns:
The block size.

engineGetIV

protected abstract byte[] engineGetIV()
Returns the initializaiton vector this cipher was initialized with, if any.
Returns:
The IV, or null if this cipher uses no IV or if this instance has not been initialized yet.

engineGetKeySize

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.

Parameters:
key - The key to get the size for.
Returns:
The size of the key, in bits.
Throws:
InvalidKeyException - If the key's length cannot be determined by this implementation.

engineGetOutputSize

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.

Parameters:
inputLength - The input length, in bytes.
Returns:
The size an output buffer must be.

engineGetParameters

protected abstract AlgorithmParameters engineGetParameters()
Returns the parameters that this cipher is using. This may be the parameters used to initialize this cipher, or it may be parameters that have been initialized with random values.
Returns:
This cipher's parameters, or null if this cipher does not use parameters.

engineInit

protected abstract void engineInit(int opmode,
                                   Key key,
                                   AlgorithmParameters params,
                                   SecureRandom random)
            throws InvalidAlgorithmParameterException,
                   InvalidKeyException
Initializes this cipher with an operation mode, key, parameters, and source of randomness. If this cipher requires any other initializing data, for example an initialization vector, then it should generate it from the provided source of randomness.
Parameters:
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.
Throws:
InvalidAlgorithmParameterException - If the given parameters are not appropriate for this implementation.
InvalidKeyException - If the given key is not acceptable for this implementation.

engineInit

protected abstract void engineInit(int opmode,
                                   Key key,
                                   SecureRandom random)
            throws InvalidKeyException
Initializes this cipher with an operation mode, key, and source of randomness. If this cipher requires any other initializing data, for example an initialization vector, then it should generate it from the provided source of randomness.
Parameters:
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.
Throws:
InvalidKeyException - If the given key is not acceptable for this implementation.

engineInit

protected abstract void engineInit(int opmode,
                                   Key key,
                                   AlgorithmParameterSpec params,
                                   SecureRandom random)
            throws InvalidAlgorithmParameterException,
                   InvalidKeyException
Initializes this cipher with an operation mode, key, parameters, and source of randomness. If this cipher requires any other initializing data, for example an initialization vector, then it should generate it from the provided source of randomness.
Parameters:
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.
Throws:
InvalidAlgorithmParameterException - If the given parameters are not appropriate for this implementation.
InvalidKeyException - If the given key is not acceptable for this implementation.

engineSetMode

protected abstract void engineSetMode(String mode)
            throws NoSuchAlgorithmException
Set the mode in which this cipher is to run.
Parameters:
mode - The name of the mode to use.
Throws:
NoSuchAlgorithmException - If the mode is not supported by this cipher's provider.

engineSetPadding

protected abstract void engineSetPadding(String padding)
            throws NoSuchPaddingException
Set the method with which the input is to be padded.
Parameters:
padding - The name of the padding to use.
Throws:
NoSuchPaddingException - If the padding is not supported by this cipher's provider.

engineUnwrap

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.

Parameters:
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.
Returns:
The unwrapped key.
Throws:
InvalidKeyException - If the key cannot be unwrapped, or if wrappedKeyType is an inappropriate type for the unwrapped key.
NoSuchAlgorithmException - If the wrappedKeyAlgorithm is unknown.

engineUpdate

protected abstract byte[] engineUpdate(byte[] input,
                                       int inputOffset,
                                       int inputLength)
Continue with a multi-part transformation, returning a new array of the transformed bytes.
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.

engineUpdate

protected abstract int engineUpdate(byte[] input,
                                    int inputOffset,
                                    int inputLength,
                                    byte[] output,
                                    int outputOffset)
            throws ShortBufferException
Continue with a multi-part transformation, storing the transformed bytes into the specified array.
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:
ShortBufferException - If there is not enough space in the output array to store the transformed bytes.

engineUpdate

protected int engineUpdate(ByteBuffer input,
                           ByteBuffer output)
            throws ShortBufferException
Since:
1.5

engineWrap

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.

Parameters:
key - The key to wrap.
Returns:
The wrapped key.
Throws:
InvalidKeyException - If the key cannot be wrapped.
CipherSpi.java -- The cipher service provider interface. Copyright (C) 2004, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

Overview Package Class Use Source Tree Index Deprecated About