de.flexiprovider.api
Class BlockCipher

java.lang.Object
  |
  +--javax.crypto.CipherSpi
        |
        +--de.flexiprovider.api.Cipher
              |
              +--de.flexiprovider.api.BlockCipher

Direct Known Subclasses:

Camellia, DESede, IDEA, MARS, Misty1, RC2, RC5, RC6, Rijndael, SAFERPlus, SAFERPlusPlus, Serpent, Shacal, Shacal2, Twofish

public abstract class BlockCipher

extends Cipher

The BlockCipher class extends CipherSpi and handles the creation of PaddingScheme, BlockCipher and Mode. An instance of this class will be created by the Cipher.getInstance(String)-mechanism of the Cipher class.

BlockCipher ensures that a Mode and a PaddingsScheme are created, even if the user has set no preferences. For this to work, BlockCipher requires version 1.3 of the mode class that can handle a getInstance()-call without arguments to return a default Mode or Padding.

BlockCipher will acknowledge only one call of engineSetMode() and engineSetPadding() to ensure that these settings aren't changed while encrypting.

Author:

Christoph Sesterhenn, Christoph Ender, Ralf-Philipp Weinmann, Martin Döring, Johannes Müller

Field Summary

protected SecureRandom

random the source of randomness, if necessary

Fields inherited from class de.flexiprovider.api.Cipher

DECRYPT_MODE, ENCRYPT_MODE, opMode

Constructor Summary

BlockCipher()

Method Summary

byte[]	doFinal(byte[] input, int inOff, int inLen) Finish a multiple-part encryption or decryption operation (depending on how this cipher was initialized).
int	doFinal(byte[] input, int inOff, int inLen, byte[] output, int outOff) Finish a multiple-part encryption or decryption operation (depending on how this cipher was initialized).
protected void	engineInit(int opmode, java.security.Key key, java.security.spec.AlgorithmParameterSpec paramSpec, java.security.SecureRandom javaRand) Initialize this cipher object with proper key and algorithm parameters, and some random seed.
int	getBlockSize()
protected abstract int	getCipherBlockSize() Return the blocksize the algorithm uses.
byte[]	getIV() Return the initialization vector.
int	getOutputSize(int inLen) Return the length in bytes that an output buffer would need to be in order to hold the result of the next update or doFinal operation, given the input length inputLen (in bytes).
AlgorithmParameterSpec	getParameters() Return the parameters used with this cipher.
protected abstract void	initCipherDecrypt(SecretKey key, AlgorithmParameterSpec params) Initialize the block cipher with a secret key and parameters for data decryption.
protected abstract void	initCipherEncrypt(SecretKey key, AlgorithmParameterSpec params) Initialize the block cipher with a secret key and parameters for data encryption.
void	initDecrypt(Key key) Initialize this cipher with a key and a source of randomness for decryption.
void	initDecrypt(Key key, AlgorithmParameterSpec cipherParams) Initialize this cipher with a key, a set of algorithm parameters, and a source of randomness for decryption.
void	initDecrypt(Key key, ModeParameterSpec modeParams, AlgorithmParameterSpec cipherParams) Initialize this cipher with a key, a set of algorithm parameters, and a source of randomness for decryption.
void	initEncrypt(Key key) Initialize this cipher with a key and a source of randomness for encryption.
void	initEncrypt(Key key, AlgorithmParameterSpec cipherParams, SecureRandom random) Initialize this cipher with a key, a set of algorithm parameters, and a source of randomness for encryption.
void	initEncrypt(Key key, ModeParameterSpec modeParams, AlgorithmParameterSpec cipherParams, SecureRandom random) Initialize this cipher with a key, a set of algorithm parameters, and a source of randomness for encryption.
void	initEncrypt(Key key, SecureRandom random) Initialize this cipher with a key and a source of randomness for encryption.
void	setMode(java.lang.String modeName) Set the mode of this cipher.
void	setPadding(java.lang.String paddingName) Set the padding scheme of this cipher.
protected abstract void	singleBlockDecrypt(byte[] input, int inOff, byte[] output, int outOff) Decrypt a single block of data.
protected abstract void	singleBlockEncrypt(byte[] input, int inOff, byte[] output, int outOff) Encrypt a single block of data.
byte[]	update(byte[] input, int inOff, int inLen) Continue a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.
int	update(byte[] input, int inOff, int inLen, byte[] output, int outOff) Continue a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.

Methods inherited from class de.flexiprovider.api.Cipher

doFinal, doFinal, engineDoFinal, engineDoFinal, engineGetBlockSize, engineGetIV, engineGetKeySize, engineGetOutputSize, engineGetParameters, engineInit, engineInit, engineSetMode, engineSetPadding, engineUpdate, engineUpdate, getKeySize, getName, update

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

random

protected SecureRandom random

the source of randomness, if necessary

Constructor Detail

BlockCipher

public BlockCipher()

Method Detail

engineInit

protected final void engineInit(int opmode,
                                java.security.Key key,
                                java.security.spec.AlgorithmParameterSpec paramSpec,
                                java.security.SecureRandom javaRand)
                         throws java.security.InvalidKeyException,
                                java.security.InvalidAlgorithmParameterException

Initialize 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. Note: If the Mode needs an initialization vector, a try to retrieve it from the AlgorithmParametersSpec is made.

Overrides:

engineInit in class Cipher

Parameters:

opmode - the operation mode for which this cipher is used (ENCRYPT_MODE or DECRYPT_MODE)

key - the key

paramSpec - the algorithm parameters

javaRand - the random seed

Throws:

java.security.InvalidKeyException - if the key is inappropriate for initializing this block cipher.

java.security.InvalidAlgorithmParameterException - if the parameters are inappropriate for initializing this block cipher.

setMode

public final void setMode(java.lang.String modeName)
                   throws NoSuchModeException

Set the mode of this cipher. The mode can only be set once.

Overrides:

setMode in class Cipher

Parameters:

modeName - the cipher mode

Throws:

NoSuchModeException - if neither the mode with the given name nor the default mode can be found

setPadding

public final void setPadding(java.lang.String paddingName)
                      throws NoSuchPaddingException

Set the padding scheme of this cipher. The padding scheme can only be set once.

Overrides:

setPadding in class Cipher

Parameters:

paddingName - the padding scheme

Throws:

NoSuchPaddingException - if the requested padding scheme cannot be found.

getIV

public final byte[] getIV()

Return the initialization vector. This is useful in the context of password-based encryption or decryption, where the IV is derived from a user-provided passphrase.

Overrides:

getIV in class Cipher

Returns:

the initialization vector in a new buffer, or null if the underlying algorithm does not use an IV, or if the IV has not yet been set.

getCipherBlockSize

protected abstract int getCipherBlockSize()

Return the blocksize the algorithm uses. This method will usually be called by the mode.

Returns:

the blocksize of the cipher

getBlockSize

public final int getBlockSize()

Overrides:

getBlockSize in class Cipher

Returns:

the block size of the used mode, or -1 if the cipher has not been initialized.

getOutputSize

public final int getOutputSize(int inLen)

Return the length in bytes that an output buffer would need to be in order to hold the result of the next update or doFinal operation, given the input length inputLen (in bytes).

This call takes into account any unprocessed (buffered) data from a previous update call, and padding.

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

Overrides:

getOutputSize in class Cipher

Parameters:

inLen - the input length (in bytes)

Returns:

the required output buffer size (in bytes)

getParameters

public final AlgorithmParameterSpec getParameters()

Return 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).

Overrides:

getParameters in class Cipher

Returns:

the parameters used with this cipher, or null if this cipher does not use any parameters.

initEncrypt

public final void initEncrypt(Key key)
                       throws InvalidKeyException,
                              InvalidParameterException

Initialize this cipher with a key and a source of randomness for encryption.

If this cipher requires any algorithm parameters that cannot be derived from the given key, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption, and raise an InvalidKeyException if it is being initialized for decryption. The generated parameters can be retrieved using engineGetParameters or engineGetIV (if the parameter is an IV).

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

Note that when a BlockCipher 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:

key - the encryption key

Throws:

InvalidKeyException - if the given key is inappropriate for initializing this cipher

InvalidParameterException - if this block cipher requires parameters for initialization and cannot generate parameters itself.

initEncrypt

public final void initEncrypt(Key key,
                              SecureRandom random)
                       throws InvalidKeyException,
                              InvalidParameterException

Initialize this cipher with a key and a source of randomness for encryption.

If this cipher requires any algorithm parameters that cannot be derived from the given key, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption, and raise an InvalidKeyException if it is being initialized for decryption. The generated parameters can be retrieved using engineGetParameters or engineGetIV (if the parameter is an IV).

If this cipher (including its underlying feedback or padding scheme) requires any random bytes (e.g., for parameter generation), it will get them from random and they will be stored in the class variable rndBytes.

Note that when a BlockCipher 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:

key - the encryption key

random - the source of randomness

Throws:

InvalidKeyException - if the given key is inappropriate for initializing this cipher

InvalidParameterException - if this block cipher requires parameters for initialization and cannot generate parameters itself.

initEncrypt

public final void initEncrypt(Key key,
                              AlgorithmParameterSpec cipherParams,
                              SecureRandom random)
                       throws InvalidKeyException,
                              InvalidAlgorithmParameterException

Initialize this cipher with a key, a set of algorithm parameters, and a source of randomness for encryption.

If this cipher requires any algorithm parameters and paramSpec is null, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption, and raise an InvalidAlgorithmParameterException if it is being initialized for decryption. The generated parameters can be retrieved using engineGetParameters or engineGetIV (if the parameter is an IV).

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

Note that when a BlockCipher 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.

Overrides:

initEncrypt in class Cipher

Parameters:

key - the encryption key

cipherParams - the cipher parameters

random - the source of randomness

Throws:

InvalidKeyException - if the given key is inappropriate for initializing this block cipher.

InvalidAlgorithmParameterException - if the parameters are inappropriate for initializing this block cipher.

initEncrypt

public final void initEncrypt(Key key,
                              ModeParameterSpec modeParams,
                              AlgorithmParameterSpec cipherParams,
                              SecureRandom random)
                       throws InvalidKeyException,
                              InvalidAlgorithmParameterException

Initialize this cipher with a key, a set of algorithm parameters, and a source of randomness for encryption.

If this cipher requires any algorithm parameters and paramSpec is null, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption, and raise an InvalidAlgorithmParameterException if it is being initialized for decryption. The generated parameters can be retrieved using engineGetParameters or engineGetIV (if the parameter is an IV).

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

Note that when a BlockCipher 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:

key - the encryption key

modeParams - the mode parameters

cipherParams - the cipher parameters

random - the source of randomness

Throws:

InvalidKeyException - if the given key is inappropriate for initializing this block cipher.

InvalidAlgorithmParameterException - if the parameters are inappropriate for initializing this block cipher.

initDecrypt

public final void initDecrypt(Key key)
                       throws InvalidKeyException,
                              InvalidParameterException

Initialize this cipher with a key and a source of randomness for decryption.

If this cipher requires any algorithm parameters that cannot be derived from the given key, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption, and raise an InvalidKeyException if it is being initialized for decryption. The generated parameters can be retrieved using engineGetParameters or engineGetIV (if the parameter is an IV).

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

Note that when a BlockCipher 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:

key - the encryption key

Throws:

InvalidKeyException - if the given key is inappropriate for initializing this cipher

InvalidParameterException - if the parameters are

initDecrypt

public final void initDecrypt(Key key,
                              AlgorithmParameterSpec cipherParams)
                       throws InvalidKeyException,
                              InvalidAlgorithmParameterException

Initialize this cipher with a key, a set of algorithm parameters, and a source of randomness for decryption.

If this cipher requires any algorithm parameters and paramSpec is null, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption, and throw an InvalidAlgorithmParameterException if it is being initialized for decryption. The generated parameters can be retrieved using engineGetParameters or engineGetIV (if the parameter is an IV).

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

Note that when a BlockCipher 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.

Overrides:

initDecrypt in class Cipher

Parameters:

key - the encryption key

cipherParams - the cipher parameters

Throws:

InvalidKeyException - if the given key is inappropriate for initializing this block cipher.

InvalidAlgorithmParameterException - if the parameters are inappropriate for initializing this block cipher.

initDecrypt

public final void initDecrypt(Key key,
                              ModeParameterSpec modeParams,
                              AlgorithmParameterSpec cipherParams)
                       throws InvalidKeyException,
                              InvalidAlgorithmParameterException

Initialize this cipher with a key, a set of algorithm parameters, and a source of randomness for decryption.

If this cipher requires any algorithm parameters and paramSpec is null, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption, and throw an InvalidAlgorithmParameterException if it is being initialized for decryption. The generated parameters can be retrieved using engineGetParameters or engineGetIV (if the parameter is an IV).

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

Note that when a BlockCipher 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:

key - the encryption key

modeParams - the mode parameters

cipherParams - the cipher parameters

Throws:

InvalidKeyException - if the given key is inappropriate for initializing this block cipher.

InvalidAlgorithmParameterException - if the parameters are inappropriate for initializing this block cipher.

update

public final byte[] update(byte[] input,
                           int inOff,
                           int inLen)

Continue a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.

Overrides:

update in class Cipher

Parameters:

input - the input buffer

inOff - the offset where the input starts

inLen - the input length

Returns:

a new buffer with the result (maybe an empty byte array)

update

public final int update(byte[] input,
                        int inOff,
                        int inLen,
                        byte[] output,
                        int outOff)
                 throws ShortBufferException

Continue a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.

Overrides:

update in class Cipher

Parameters:

input - the input buffer

inOff - the offset where the input starts

inLen - the input length

output - the output buffer

outOff - the offset where the result is stored

Returns:

the length of the output

Throws:

ShortBufferException - if the output buffer is too small to hold the result.

doFinal

public final byte[] doFinal(byte[] input,
                            int inOff,
                            int inLen)
                     throws IllegalBlockSizeException,
                            BadPaddingException

Finish a multiple-part encryption or decryption operation (depending on how this cipher was initialized).

Overrides:

doFinal in class Cipher

Parameters:

input - the input buffer

inOff - the offset where the input starts

inLen - the input length

Returns:

a new buffer with the result

Throws:

IllegalBlockSizeException - if the total input length is not a multiple of the block size (for encryption when no padding is used or for decryption).

BadPaddingException - if unpadding fails.

doFinal

public final int doFinal(byte[] input,
                         int inOff,
                         int inLen,
                         byte[] output,
                         int outOff)
                  throws ShortBufferException,
                         IllegalBlockSizeException,
                         BadPaddingException

Finish a multiple-part encryption or decryption operation (depending on how this cipher was initialized).

Overrides:

doFinal in class Cipher

Parameters:

input - the input buffer

inOff - the offset where the input starts

inLen - the input length

output - the buffer for the result

outOff - the offset where the result is stored

Returns:

the output length

Throws:

ShortBufferException - if the output buffer is too small to hold the result.

IllegalBlockSizeException - if the total input length is not a multiple of the block size (for encryption when no padding is used or for decryption).

BadPaddingException - if unpadding fails.

initCipherEncrypt

protected abstract void initCipherEncrypt(SecretKey key,
                                          AlgorithmParameterSpec params)
                                   throws InvalidKeyException,
                                          InvalidAlgorithmParameterException

Initialize the block cipher with a secret key and parameters for data encryption.

Parameters:

key - the secret key

params - the parameters

Throws:

InvalidKeyException - if the given key is inappropriate for this cipher.

InvalidAlgorithmParameterException - if the given parameters are inappropriate for this cipher.

initCipherDecrypt

protected abstract void initCipherDecrypt(SecretKey key,
                                          AlgorithmParameterSpec params)
                                   throws InvalidKeyException,
                                          InvalidAlgorithmParameterException

Initialize the block cipher with a secret key and parameters for data decryption.

Parameters:

key - the secret key

params - the parameters

Throws:

InvalidKeyException - if the given key is inappropriate for this cipher.

InvalidAlgorithmParameterException - if the given parameters are inappropriate for this cipher.

singleBlockEncrypt

protected abstract void singleBlockEncrypt(byte[] input,
                                           int inOff,
                                           byte[] output,
                                           int outOff)

Encrypt a single block of data. It has to be assured that the array input contains a whole block starting at inOff and that out is large enough to hold an encrypted block starting at outOff.

Parameters:

input - array of bytes which contains the plaintext to be encrypted

inOff - index in array in, where the plaintext block starts

output - array of bytes which will contain the ciphertext startig at outOffset

outOff - index in array out, where the ciphertext block will start

singleBlockDecrypt

protected abstract void singleBlockDecrypt(byte[] input,
                                           int inOff,
                                           byte[] output,
                                           int outOff)

Decrypt a single block of data. It has to be assured that the array input contains a whole block starting at inOff and that output is large enough to hold an decrypted block starting at outOff.

Parameters:

input - array of bytes which contains the ciphertext to be decrypted

inOff - index in array in, where the ciphertext block starts

output - array of bytes which will contain the plaintext starting at outOffset

outOff - index in array out, where the plaintext block will start