tribble.crypto
Class CipherSpi

java.lang.Object
  extended byjavax.crypto.CipherSpi
      extended bytribble.crypto.CipherSpi
Direct Known Subclasses:
BlockCipherSpi, StreamCipherSpi

public abstract class CipherSpi
extends javax.crypto.CipherSpi

Cryptographic cipher service provider interface (SPI).

This is the base class for all encryption cipher SPI implementations within this package. Cipher objects (of type javax.crypto.Cipher) are constructed from a combination of a cipher SPI object, which is one of generic cipher algorithm types derived from this class, CipherSpi, and a primitive cipher algorithm, which is a class derived from class AbstractCipher.

Cipher SPI implementations derived from this class are further divided into two types, BlockCipherSpi and StreamCipherSpi. These two base classes implement the encryption cipher service provider interfaces that serve as the foundation upon which the rest of this cryptographic package is built.

The MODE_XXX constants define the various modes that can be supported by the cryptographic cipher classes in this package. Likewise, the PADDING_XXX constants define the various padding schemes for this package.

Since:
JCE 1.2 / JRE 1.4, 2003-04-04
Version:
API 2, $Revision: 1.6 $ $Date: 2005/09/10 23:01:47 $
Author:
David R. Tribble (david@tribble.com).

Copyright ©2003-2005 by David R. Tribble, all rights reserved.
Permission is granted to freely use and distribute this source code provided that the original copyright and authorship notices remain intact.

See Also:
BlockCipherSpi, StreamCipherSpi, AbstractCipher

Field Summary
static short DECRYPT_MODE
          Initialization mode: Decryption.
static short ENCRYPT_MODE
          Initialization mode: Encryption.
static java.lang.String MODE_BC
          Operating mode (block): BC, block chaining.
static java.lang.String MODE_CBC
          Operating mode (block): CBC, cipher block chaining.
static java.lang.String MODE_CFB
          Operating mode (stream): CFB, cipher feedback.
static java.lang.String MODE_CFB8
          Operating mode (stream): CFB-8, cipher feedback.
static java.lang.String MODE_CTR
          Operating mode (stream): CTR, counter mode.
static java.lang.String MODE_CTR8
          Operating mode (stream): CTR-8, counter mode.
static java.lang.String MODE_ECB
          Operating mode (block): ECB, electronic codebook (no chaining).
static java.lang.String MODE_OFB
          Operating mode (stream): OFB, output feedback.
static java.lang.String MODE_OFB8
          Operating mode (stream): OFB-8, output feedback.
static java.lang.String MODE_PBC
          Operating mode (block): PBC, plaintext block chaining.
static java.lang.String MODE_PCBC
          Operating mode (block): PCBC, propagating cipher block chaining.
static java.lang.String MODE_PFB
          Operating mode (stream): PFB, plaintext feedback.
static java.lang.String MODE_PFB8
          Operating mode (stream): PFB-8, plaintext feedback.
static java.lang.String PADDING_CTS
          Padding scheme: Ciphertext stealing in the final partial block.
static java.lang.String PADDING_NONE
          Padding scheme: None.
static java.lang.String PADDING_PKCS5
          Padding scheme: PKCS#5.
static java.lang.String PADDING_ZEROS
          Padding scheme: Pad with zero bytes (nulls).
static int SERIES
          Class series version.
 
Constructor Summary
protected CipherSpi(java.lang.String alg, java.lang.String mode, java.lang.String pad)
          Constructor.
 
Method Summary
protected  void engineClear()
          Clear (wipe) this cipher.
protected  byte[] engineDoFinal(byte[] in, int off, int len)
          Add final input bytes to this cipher.
protected abstract  int engineDoFinal(byte[] in, int inOff, int len, byte[] out, int outOff)
          Add final input bytes to this cipher.
protected  int engineGetBlockSize()
          Retrieve the block size (in bytes) of this cipher.
protected  byte[] engineGetIV()
          Retrieve the initial vector (IV) used by this cipher.
protected  int engineGetKeySize()
          Retrieve the key size (in bytes) of this cipher.
protected  int engineGetKeySize(java.security.Key key)
          Determine the size of a key for this cipher.
protected abstract  int engineGetOutputSize(int n)
          Determine the output buffer size of this cipher.
protected abstract  java.security.AlgorithmParameters engineGetParameters()
          Retrieve algorithm-specific initialization parameters for this cipher.
protected abstract  void engineInit(int mode, java.security.Key key, java.security.spec.AlgorithmParameterSpec parms, java.security.SecureRandom rand)
          Initialize this cipher.
protected abstract  void engineInit(int mode, java.security.Key key, java.security.AlgorithmParameters parms, java.security.SecureRandom rand)
          Initialize this cipher.
protected abstract  void engineInit(int mode, java.security.Key key, java.security.SecureRandom rand)
          Initialize this cipher.
protected  void engineSetIV(byte[] iv)
          Set the initial vector (IV) used by this cipher.
protected abstract  void engineSetMode(java.lang.String mode)
          Set the operating mode of this cipher.
protected abstract  void engineSetPadding(java.lang.String padding)
          Set the padding scheme of this cipher.
protected  java.security.Key engineUnwrap(byte[] wrappedKey, java.lang.String alg, int type)
          Unwrap a cipher key from a raw encoded form.
protected  byte[] engineUpdate(byte[] in, int off, int len)
          Encrypt/decrypt an array of bytes using this cipher.
protected abstract  int engineUpdate(byte[] in, int inOff, int len, byte[] out, int outOff)
          Encrypt/decrypt an array of bytes using this cipher.
protected  byte[] engineWrap(java.security.Key key)
          Wrap a cipher key into a raw encoded form.
protected  void finalize()
          Finalization.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SERIES

public static final int SERIES
Class series version.

See Also:
Constant Field Values

ENCRYPT_MODE

public static final short ENCRYPT_MODE
Initialization mode: Encryption. (Same as Cipher.ENCRYPT_MODE.)

See Also:
Constant Field Values

DECRYPT_MODE

public static final short DECRYPT_MODE
Initialization mode: Decryption. (Same as Cipher.DECRYPT_MODE.)

See Also:
Constant Field Values

MODE_ECB

public static final java.lang.String MODE_ECB
Operating mode (block): ECB, electronic codebook (no chaining).

See Also:
Constant Field Values

MODE_CBC

public static final java.lang.String MODE_CBC
Operating mode (block): CBC, cipher block chaining.

See Also:
Constant Field Values

MODE_PBC

public static final java.lang.String MODE_PBC
Operating mode (block): PBC, plaintext block chaining.

See Also:
Constant Field Values

MODE_PCBC

public static final java.lang.String MODE_PCBC
Operating mode (block): PCBC, propagating cipher block chaining.

See Also:
Constant Field Values

MODE_BC

public static final java.lang.String MODE_BC
Operating mode (block): BC, block chaining.

See Also:
Constant Field Values

MODE_CFB

public static final java.lang.String MODE_CFB
Operating mode (stream): CFB, cipher feedback.

See Also:
Constant Field Values

MODE_CFB8

public static final java.lang.String MODE_CFB8
Operating mode (stream): CFB-8, cipher feedback.

See Also:
Constant Field Values

MODE_OFB

public static final java.lang.String MODE_OFB
Operating mode (stream): OFB, output feedback.

See Also:
Constant Field Values

MODE_OFB8

public static final java.lang.String MODE_OFB8
Operating mode (stream): OFB-8, output feedback.

See Also:
Constant Field Values

MODE_PFB

public static final java.lang.String MODE_PFB
Operating mode (stream): PFB, plaintext feedback.

See Also:
Constant Field Values

MODE_PFB8

public static final java.lang.String MODE_PFB8
Operating mode (stream): PFB-8, plaintext feedback.

See Also:
Constant Field Values

MODE_CTR

public static final java.lang.String MODE_CTR
Operating mode (stream): CTR, counter mode.

See Also:
Constant Field Values

MODE_CTR8

public static final java.lang.String MODE_CTR8
Operating mode (stream): CTR-8, counter mode.

See Also:
Constant Field Values

PADDING_NONE

public static final java.lang.String PADDING_NONE
Padding scheme: None.

See Also:
Constant Field Values

PADDING_PKCS5

public static final java.lang.String PADDING_PKCS5
Padding scheme: PKCS#5.

See Also:
Constant Field Values

PADDING_ZEROS

public static final java.lang.String PADDING_ZEROS
Padding scheme: Pad with zero bytes (nulls).

See Also:
Constant Field Values

PADDING_CTS

public static final java.lang.String PADDING_CTS
Padding scheme: Ciphertext stealing in the final partial block.

See Also:
Constant Field Values
Constructor Detail

CipherSpi

protected CipherSpi(java.lang.String alg,
                    java.lang.String mode,
                    java.lang.String pad)
             throws java.security.NoSuchAlgorithmException,
                    javax.crypto.NoSuchPaddingException
Constructor.

Parameters:
alg - Cryptographic cipher algorithm name.
mode - Operating mode, which must match one of the MODE_XXX constants.
pad - Padding scheme, which must match one of the PADDING_XXX constants}.
Throws:
java.security.NoSuchAlgorithmException - Thrown if mode does not specify a supported operating mode.
javax.crypto.NoSuchPaddingException - Thrown if pad does not specify a supported padding scheme.
Since:
1.5 (JCE 1.2), 2005-07-10
Method Detail

engineInit

protected abstract void engineInit(int mode,
                                   java.security.Key key,
                                   java.security.SecureRandom rand)
                            throws java.security.InvalidKeyException
Initialize this cipher.

Parameters:
mode - Ciphering mode, which is either ENCRYPT_MODE or DECRYPT_MODE.
key - Key for this cipher to use.
rand - Source of random values, or null if they are to be supplied by a default source.
Throws:
java.security.InvalidKeyException - Thrown if key is not the proper kind of key for use with this cipher.
java.lang.IllegalArgumentException - (unchecked) Thrown if mode is not a valid value.
Since:
1.1 (JCE 1.2), 2003-03-30

engineInit

protected abstract void engineInit(int mode,
                                   java.security.Key key,
                                   java.security.spec.AlgorithmParameterSpec parms,
                                   java.security.SecureRandom rand)
                            throws java.security.InvalidKeyException,
                                   java.security.InvalidAlgorithmParameterException
Initialize this cipher.

Parameters:
mode - Ciphering mode, which is either ENCRYPT_MODE or DECRYPT_MODE.
key - Key for this cipher to use.
parms - Algorithm-specific initialization parameters (e.g., an IV passed as a javax.crypto.spec.IvParameterSpec object).
rand - Source of random values, or null if this is to be supplied by a default source.
Throws:
java.security.InvalidKeyException - Thrown if key is not the proper kind of key for use with this cipher.
java.security.InvalidAlgorithmParameterException - Thrown if parms is not a proper initialization parameter for this cipher.
Since:
1.1 (JCE 1.2), 2003-03-30

engineInit

protected abstract void engineInit(int mode,
                                   java.security.Key key,
                                   java.security.AlgorithmParameters parms,
                                   java.security.SecureRandom rand)
                            throws java.security.InvalidKeyException,
                                   java.security.InvalidAlgorithmParameterException
Initialize this cipher.

Parameters:
mode - Ciphering mode, which is either ENCRYPT_MODE or DECRYPT_MODE.
key - Key for this cipher to use.
parms - Algorithm-specific initialization parameters (e.g., an IV passed as a javax.crypto.spec.IvParameterSpec object).
rand - Source of random values, or null if this is to be supplied by a default source.
Throws:
java.security.InvalidKeyException - Thrown if key is not the proper kind of key for use with this cipher.
java.security.InvalidAlgorithmParameterException - Thrown if parms is not a proper initialization parameter for this cipher.
Since:
1.1 (JCE 1.2), 2003-03-30

engineSetMode

protected abstract void engineSetMode(java.lang.String mode)
                               throws java.security.NoSuchAlgorithmException
Set the operating mode of this cipher.

Subclasses must override this method, and may call engineSetMode().

Parameters:
mode - Cipher operating mode to use (e.g., "ECB", "CBC", "CFB", "OFB", "PCBC", etc.). See the MODE_XXX constants.
Throws:
java.security.NoSuchAlgorithmException - Thrown if mode does not specify an operating mode supported by this cipher.
java.lang.NullPointerException - (unchecked) Thrown if mode is null.
Since:
1.1 (JCE 1.2), 2003-03-30

engineSetPadding

protected abstract void engineSetPadding(java.lang.String padding)
                                  throws javax.crypto.NoSuchPaddingException
Set the padding scheme of this cipher.

Parameters:
padding - Cipher padding scheme to use (e.g., "PKCS5Padding").
Throws:
javax.crypto.NoSuchPaddingException - Thrown if padding does not specify a padding scheme supported by this cipher.
java.lang.NullPointerException - (unchecked) Thrown if padding is null.
Since:
1.1 (JCE 1.2), 2003-03-30

engineSetIV

protected void engineSetIV(byte[] iv)
                    throws java.security.InvalidAlgorithmParameterException
Set the initial vector (IV) used by this cipher.

This method is not part of the standard set defined in class javax.crypto.CipherSpi, but is provided as a convenient enhancement.

Parameters:
iv - Initial vector bytes to be used by this cipher. This array must be no longer than the cipher block size (see engineGetBlockSize()). It can be shorter than the cipher block size, in which case the IV of this cipher will be padded on the right with zeros. Note that the contents of this array are copied to an internal buffer, so that subsequent changes made to the array do not affect this cipher object.
Throws:
java.security.InvalidAlgorithmParameterException - Thrown if the length of iv is longer than the cipher block size.
java.lang.NullPointerException - (unchecked) Thrown if iv is null.
Since:
1.3, 2005-04-01

engineGetBlockSize

protected int engineGetBlockSize()
Retrieve the block size (in bytes) of this cipher.

Returns:
The size, in bytes, of the blocks to use with this cipher.
Since:
1.1 (JCE 1.2), 2003-03-30

engineGetKeySize

protected int engineGetKeySize()
Retrieve the key size (in bytes) of this cipher.

This method is not part of the standard set defined in class javax.crypto.CipherSpi, but is provided as a convenient enhancement.

Returns:
The size, in bytes, of the key to use with this cipher.
Throws:
java.lang.UnsupportedOperationException - (unchecked) Thrown if this cipher does not use a fixed key size.
java.lang.IllegalStateException - (unchecked) Thrown if this cipher has not been initialized.
Since:
1.3, 2005-04-01

engineGetKeySize

protected int engineGetKeySize(java.security.Key key)
                        throws java.security.InvalidKeyException
Determine the size of a key for this cipher.

Parameters:
key - A key suitable for use with this cipher.
Returns:
Key size (in bits) of the given key.
Throws:
java.security.InvalidKeyException - Thrown if the given key cannot be used with this cipher.
java.lang.IllegalStateException - (unchecked) Thrown if this cipher has not been initialized.
java.lang.UnsupportedOperationException - (unchecked) Thrown if this method is not overridden, or if this cipher does not use a fixed key size.
Since:
1.3 (JCE 1.2), 2005-04-01

engineGetOutputSize

protected abstract int engineGetOutputSize(int n)
Determine the output buffer size of this cipher.

Parameters:
n - Size of the input buffer (in addition to any previous pending input bytes).
Returns:
Output buffer size (in bytes) that will be created by this cipher.
Throws:
java.lang.IllegalStateException - (unchecked) Thrown if this cipher has not been initialized.
Since:
1.1 (JCE 1.2), 2003-03-30

engineGetIV

protected byte[] engineGetIV()
Retrieve the initial vector (IV) used by this cipher.

Returns:
Initial vector bytes used by this cipher (which is an array exactly as long as the cipher block size), or null if this cipher does not (yet) have, or need, an IV.
Throws:
java.lang.IllegalStateException - (unchecked) Thrown if this cipher has not been initialized.
Since:
1.1 (JCE 1.2), 2003-03-30

engineGetParameters

protected abstract java.security.AlgorithmParameters engineGetParameters()
Retrieve algorithm-specific initialization parameters for this cipher.

Returns:
Algorithm-specific initialization parameters (e.g., an IV value as a javax.crypto.spec.IvParameterSpec object).
Throws:
java.lang.IllegalStateException - (unchecked) Thrown if this cipher has not been initialized.
Since:
1.1 (JCE 1.2), 2003-03-30

engineUpdate

protected byte[] engineUpdate(byte[] in,
                              int off,
                              int len)
Encrypt/decrypt an array of bytes using this cipher. The input bytes are encrypted/decrypted, being appended to any input bytes that were previously added to this cipher.

Parameters:
in - Array of bytes to add as input to this cipher. The data from this array is appended to any input data previously added to this cipher.
off - Index of the first byte in array in to encrypt/decrypt.
len - Number of bytes in array in to input to encrypt/decrypt.
Returns:
Resulting output bytes suitably encrypted/decrypted by this cipher, or null if the number of input bytes so far is insufficient to produce a complete output block. Only complete encrypted/decrypted blocks are returned; partially complete blocks are not returned, and are kept pending within this cipher.
Throws:
java.lang.IllegalArgumentException - (unchecked) Thrown if len is negative.
java.lang.IllegalStateException - (unchecked) Thrown if this cipher has not been initialized.
Since:
1.1 (JCE 1.2), 2003-03-30

engineUpdate

protected abstract int engineUpdate(byte[] in,
                                    int inOff,
                                    int len,
                                    byte[] out,
                                    int outOff)
                             throws javax.crypto.ShortBufferException
Encrypt/decrypt an array of bytes using this cipher. The input bytes are encrypted/decrypted, being appended to any input bytes that were previously added to this cipher.

Parameters:
in - Array of bytes to add as input to this cipher. The data from this array is appended to any input data previously added to this cipher.
inOff - Index of the first byte of array in to input to this cipher.
len - Number of bytes in array in to encrypt/decrypt.
out - Resulting encrypted/decrypted output bytes.
outOff - Index of the first byte in array out to write the resulting output bytes to.
Returns:
Number of output bytes produced by this cipher. Only complete encrypted/decrypted blocks are written to the output array. Partially complete blocks are not written, and are kept pending within this cipher object.
Throws:
javax.crypto.ShortBufferException - Thrown if the output buffer is too small to hold the resulting data.
java.lang.IllegalStateException - (unchecked) Thrown if this cipher has not been initialized.
java.lang.IllegalArgumentException - (unchecked) Thrown if len is negative.
Since:
1.1 (JCE 1.2), 2003-03-30

engineDoFinal

protected byte[] engineDoFinal(byte[] in,
                               int off,
                               int len)
                        throws javax.crypto.BadPaddingException,
                               javax.crypto.IllegalBlockSizeException
Add final input bytes to this cipher. The added bytes are encrypted/decrypted, being appended to any input bytes that were previously added to this cipher.

Parameters:
in - Array of bytes to add as input to this cipher.
off - Index of the first byte in array in to input to this cipher.
len - Number of bytes in array in to input to this cipher.
Returns:
Array of bytes suitably encrypted/decrypted by this cipher.
Throws:
javax.crypto.BadPaddingException - Thrown if the final input block does not contain the appropriate padding (decrypt mode only).
javax.crypto.IllegalBlockSizeException - Thrown if the total number of input bytes so far is insufficient to produce a complete output block (encrypt mode only).
java.lang.IllegalArgumentException - (unchecked) Thrown if len is negative.
java.lang.IllegalStateException - (unchecked) Thrown if this cipher has not been initialized.
Since:
1.1 (JCE 1.2), 2003-03-30

engineDoFinal

protected abstract int engineDoFinal(byte[] in,
                                     int inOff,
                                     int len,
                                     byte[] out,
                                     int outOff)
                              throws javax.crypto.BadPaddingException,
                                     javax.crypto.IllegalBlockSizeException,
                                     javax.crypto.ShortBufferException
Add final input bytes to this cipher. The added bytes are encrypted/decrypted, being appended to any input bytes that were previously added to this cipher.

Parameters:
in - Array of bytes to add as input to this cipher.
inOff - Index of the first byte in array in to input to this cipher.
len - Number of bytes in array in to input to this cipher.
out - Output array to write the resulting encrypted/decrypted bytes to.
outOff - Index of the first byte in array out to write the resulting output bytes to.
Returns:
Number of output bytes produced by this cipher.
Throws:
javax.crypto.BadPaddingException - Thrown if the final input block does not contain the appropriate padding (decrypt mode only).
javax.crypto.IllegalBlockSizeException - Thrown if the total number of input bytes so far is insufficient to produce a complete output block (encrypt mode only).
javax.crypto.ShortBufferException - Thrown if the output buffer is too small to hold the resulting data.
java.lang.IllegalArgumentException - (unchecked) Thrown if len is negative.
java.lang.IllegalStateException - (unchecked) Thrown if this cipher has not been initialized.
Since:
1.1 (JCE 1.2), 2003-03-30

engineWrap

protected byte[] engineWrap(java.security.Key key)
                     throws javax.crypto.IllegalBlockSizeException,
                            java.security.InvalidKeyException
Wrap a cipher key into a raw encoded form.

Parameters:
key - Key suitable for use with this cipher.
Returns:
The key in a raw encoded format.
Throws:
javax.crypto.IllegalBlockSizeException - Thrown if key is not encoded with a block length supported by this cipher.
java.security.InvalidKeyException - Thrown if key is not a valid key for this cipher.
java.lang.UnsupportedOperationException - (unchecked) Thrown if this operation is not supported by this cipher.
Since:
1.1 (JCE 1.3), 2003-03-30
See Also:
engineUnwrap()

engineUnwrap

protected java.security.Key engineUnwrap(byte[] wrappedKey,
                                         java.lang.String alg,
                                         int type)
                                  throws java.security.InvalidKeyException,
                                         java.security.NoSuchAlgorithmException
Unwrap a cipher key from a raw encoded form.

Returns:
The key, decoded into a form suitable for use with this cipher.
Throws:
java.security.InvalidKeyException - Thrown if key is not a valid key for this cipher.
java.security.NoSuchAlgorithmException - Thrown if key is not encoded in a recognizable form.
java.lang.UnsupportedOperationException - (unchecked) Thrown if this operation is not supported by this cipher.
Since:
1.1 (JCE 1.3), 2003-03-30
See Also:
engineWrap()

engineClear

protected void engineClear()
Clear (wipe) this cipher. Erases all sensitive information contained within this object.

This method is not part of the standard set defined in class javax.crypto.CipherSpi, but is provided as a convenient enhancement.

This method should be overridden by classes extending this base class. It should erase sensitive cryptographic information contained within the cipher object, such as key schedules, passwords/passphrases, and leftover plaintext (pre-encrypted or post-decrypted) data blocks. Note that this kind of information must be written over (with zeros, for example) before being garbage collected, otherwise it may remain accessible in local memory for an indeterminate period of time. Some of the cipher information does not need to be wiped since it does not compromise security, such as the IV, mode, and padding settings.

The derived overridding method should wipe its sensitive member variables, and then this method can be called (super.engineClear()) to wipe the remaining base class members.

Note that this cipher object is no longer usable after calling this method.

Since:
1.3, 2005-04-01

finalize

protected void finalize()
                 throws java.lang.Throwable
Finalization. Erases all sensitive information contained within this object prior to it being garbage-collected.

Throws:
java.lang.Throwable
Since:
1.3, 2004-12-20