iaik.me.security
Class Cipher

java.lang.Object
  |
  +--iaik.me.security.Cipher

Direct Known Subclasses:

ARCFOUR, DES, IDEA, RC2, Rijndael, RSA, TripleDES

public abstract class Cipher

extends Object

This is the base class for all cipher operations. To use a specific cipher implementation do the following:
- get an instance of the implementation
- initialize the cipher with: mode, key, opt. initialisation vector (IV) and SecureRandom object.
- feed the cipher with the data to be en-/decrypted via the cipher.update() method
- call cipher.doFinal() to close the operation

Note: the blocksize parameter in the transformation string is not supported.

For example:

 
 Cipher cipher = Cipher.getInstance( "AES/CBC/NoPadding" );
 cipher.init(Cipher.ENCRYPT_MODE, key_, IV_, null );
 bytesEncrypted = cipher.update(buffer, 0, buffer.length, encryptedBuffer, 0);
 bytesEncrypted = cipher.doFinal(buffer, 0, buffer.length, encryptedBuffer, 0);
 
  

Supported algorithm aliases are:

• RC2
• ARCFOUR
• RC4
• DES
• TripleDES
• DESede
• IDEA
• AES
• Rijndael
• RSA

Supported modes are:

• ECB
• CBC

Supportes padding schemas are:

• NoPadding
• PKCS5Padding

Note: stream ciphers (i.e. ARCFOUR) must use ECB and NoPadding.

Field Summary

protected int	chainingMode Cipher chaining mode, either MODE_ECB or MODE_CBC.
static int	DECRYPT_MODE Constant specifying decryption mode.
static int	ENCRYPT_MODE Constant specifying encryption mode.
protected byte[]	iv IV as byte array
protected int	mode Cipher mode, either ENCRYPT_MODE or DECRYPT_MODE.
protected static int	MODE_CBC Constant for CBC mode.
protected static int	MODE_ECB Constant for ECB mode.

Constructor Summary

protected

Cipher(int blockSize) Constructor for use by cipher implementations.

Method Summary

protected void	cryptBlock(byte[] input, int inputOffset, byte[] output, int outputOffset) Encrypt one block.
byte[]	doFinal(byte[] input) Encrypt the given data performing padding and return the result in a new byte array.
int	doFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) Encrypt the given data performing final padding operations.
protected void	extractIV(int mode, Object params, SecureRandom random)
int	getBlockSize() Return the block size in byte for this cipher, e.g. 8 for IDEA.
static Cipher	getInstance(String algorithm) Returns a cipher implementation.
CryptoBag	getIV() Returns the IV as a cryptobag object or null if no IV is available.
abstract int[]	getKeyLength() Return the valid key lengths for this cipher.
void	init(int mode, CryptoBag key) Initialize this cipher.
abstract void	init(int mode, CryptoBag key, Object params, SecureRandom random) Initialize this cipher.
static void	register(String name, String clazz) Registers a Cipher implementation dynamically. for e.g.: register("MyCipher", "mypackage.MyCipher"); The registered cipher can afterwards be instantiated with the getInstance("MyCipher"); method
protected String	setMode(String mode) Set the cipher chaining mode.
protected String	setPadding(String padding) Set the cipher padding mode.
String	toString() Return a String representation of the cipher.
int	update(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) Encrypt the input data storing it in the output array.
protected int	updateInternal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset, boolean doFinal) This is method performs the actual en-/decipher opertion.

Methods inherited from class java.lang.Object

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

Field Detail

ENCRYPT_MODE

public static final int ENCRYPT_MODE

Constant specifying encryption mode. For use with init().

DECRYPT_MODE

public static final int DECRYPT_MODE

Constant specifying decryption mode. For use with init().

MODE_ECB

protected static final int MODE_ECB

Constant for ECB mode. Internal use only.

MODE_CBC

protected static final int MODE_CBC

Constant for CBC mode. Internal use only.

mode

protected int mode

Cipher mode, either ENCRYPT_MODE or DECRYPT_MODE.

iv

protected byte[] iv

IV as byte array

chainingMode

protected int chainingMode

Cipher chaining mode, either MODE_ECB or MODE_CBC.

Constructor Detail

Cipher

protected Cipher(int blockSize)

Constructor for use by cipher implementations. Must specify the blocksize in bytes.

Method Detail

getIV

public CryptoBag getIV()

Returns the IV as a cryptobag object or null if no IV is available. Note that this is always the IV specified at init(), it is not updated during encryption.

getBlockSize

public int getBlockSize()

Return the block size in byte for this cipher, e.g. 8 for IDEA. Stream ciphers return 1.

getKeyLength

public abstract int[] getKeyLength()

Return the valid key lengths for this cipher. The array will always have four elements, key lengths are specified in bytes. The values identify the length of the key in bytes, not the entropy, i.e. DES returns 8 instead of 7.
[0] is the minimum allowable length (e.g. 1 byte (8 bit) for ARCFOUR).
[1] is the recommended default length (e.g. 16 byte (128 bit) for ARCFOUR).
[2] is the maximum allowable length (e.g. 128 byte (1024 bit) for ARCFOUR).
[3] is increment between key length (e.g. 1 byte (8 bit) for ARCFOUR), 4 byte (32 bit) for AES.
It is assumed that keys are always a integral number of bytes.

init

public final void init(int mode,
                       CryptoBag key)
                throws CryptoException

Initialize this cipher. Shorthand for init(mod, key, null, null);.

init

public abstract void init(int mode,
                          CryptoBag key,
                          Object params,
                          SecureRandom random)
                   throws CryptoException

Initialize this cipher.

update

public int update(byte[] input,
                  int inputOffset,
                  int inputLen,
                  byte[] output,
                  int outputOffset)
           throws CryptoException

Encrypt the input data storing it in the output array.

updateInternal

protected int updateInternal(byte[] input,
                             int inputOffset,
                             int inputLen,
                             byte[] output,
                             int outputOffset,
                             boolean doFinal)
                      throws CryptoException

This is method performs the actual en-/decipher opertion. The method always buffers the last block of the operation. The block is returned by the doFinal() operation. The doFinal flag indicates whether to return this block (doFinal() was invoked) or hold it for the next call (update() was invoked.

Parameters:

input - input data

inputOffset - offset from which on the input data will be processed

inputLen - length of the input data that will be processed

output - the processed input data

outputOffset -

doFinal - flag indicates whether this method was invoked from Cipher.update or Cipher.doFinal

Returns:

number of blocks processed

Throws:

CryptoException - is thrown if an error occurs during cipher operation

Since:

3.03

cryptBlock

protected void cryptBlock(byte[] input,
                          int inputOffset,
                          byte[] output,
                          int outputOffset)
                   throws CryptoException

Encrypt one block. To be implemented by subclasses.

doFinal

public int doFinal(byte[] input,
                   int inputOffset,
                   int inputLen,
                   byte[] output,
                   int outputOffset)
            throws CryptoException

Encrypt the given data performing final padding operations.

doFinal

public byte[] doFinal(byte[] input)
               throws CryptoException

Encrypt the given data performing padding and return the result in a new byte array. Note that this method must create a new byte array, which may be a performance concern in some environments.

setMode

protected String setMode(String mode)
                  throws CryptoException

Set the cipher chaining mode. This method is called exactly once in the lifetime of a cipher, right after the constructor is invoked.

setPadding

protected String setPadding(String padding)
                     throws CryptoException

Set the cipher padding mode. This method is called exactly once in the lifetime of a cipher, right after the constructor is invoked.

extractIV

protected void extractIV(int mode,
                         Object params,
                         SecureRandom random)
                  throws CryptoException

toString

public String toString()

Return a String representation of the cipher. This is the full transformation string, e.g. AES/CBC/PKCS5Padding.

Overrides:

toString in class Object

getInstance

public static Cipher getInstance(String algorithm)
                          throws CryptoException

Returns a cipher implementation. <alias> may be a JCE style transformation string or an ObjectID mapped to such a transformation string via the ASN1 class. For example, the string could be "AES/CBC/PKCS5Padding". Symmetric ciphers support ECB and CBC modes, NoPadding and PKCS5Padding. Any error (algorithm not available, invalid transformation string) causes a CryptoException.

Algorithm implementations can be instantiated this way:
Cipher cipher = Cipher.getInstance();
For a list of the supported algorithms and transformationstrings see the class documentation.

Parameters:

algorithm - the algorithm name plus mode and padding string

Returns:

Cipher object that implements the requested cipher algorithm

Throws:

CryptoException - if the requested mode or padding schema cannot be set or the requested algorithm implementation is not available

register

public static void register(String name,
                            String clazz)

Registers a Cipher implementation dynamically. for e.g.:
register("MyCipher", "mypackage.MyCipher");

The registered cipher can afterwards be instantiated with the getInstance("MyCipher"); method

Parameters:

name - alias of the cipher

clazz - pakcage.classname