edu.vt.middleware.crypt.symmetric
Class SymmetricAlgorithm

java.lang.Object
  edu.vt.middleware.crypt.AbstractAlgorithm
      edu.vt.middleware.crypt.AbstractEncryptionAlgorithm
          edu.vt.middleware.crypt.symmetric.SymmetricAlgorithm

All Implemented Interfaces:

Algorithm, EncryptionAlgorithm

Direct Known Subclasses:

AES, Blowfish, CAST5, CAST6, DES, DESede, RC2, RC4, RC5, RC6, Rijndael, Serpent, Skipjack, Twofish

public class SymmetricAlgorithm
extends AbstractEncryptionAlgorithm

Provides symmetric encryption and decryption operations using a secret key.

Version:

$Revision: 84 $

Author:

Middleware Services

Field Summary

static String	DEFAULT_MODE Default mode used for encryption and decryption.
static String	DEFAULT_PADDING Default padding used for encryption and decryption.
protected byte[]	iv Initialization vector used for encryption.
protected AlgorithmParameterSpec	paramSpec Cipher-specific initialization parameters provided to factory methods.

Fields inherited from class edu.vt.middleware.crypt.AbstractEncryptionAlgorithm

cipher, cipherMode, key, mode, padding

Fields inherited from class edu.vt.middleware.crypt.AbstractAlgorithm

algorithm, logger, randomByteSize, randomProvider

Constructor Summary

protected

SymmetricAlgorithm(String cipherAlgorithm, String cipherModeName, String cipherPadding) Creates a new instance that uses a cipher of the given algorithm.

Method Summary

SecretKey	generateKey() Generates a secret key of the default key size for encryption and decryption operations with this instance and others that use the same algorithm.
SecretKey	generateKey(int bitLength) Generates a secret key of the given size for encryption and decryption operations with this instance and others that use the same algorithm.
static SecretKey	generateKey(String algorithm, int bitLength, SecureRandom random) Generates a new secret key for encryption/decryption operations on a cipher of the given algorithm name.
protected AlgorithmParameterSpec	getAlgorithmParameterSpec() Gets the algorithm parameter specification for this algorithm.
int[]	getAllowedKeyLengths() Gets an array of key lengths that are acceptable for the cipher algorithm.
protected int	getChunkSize() Gets the chunk size for buffers using in stream-based encryption and decryption operations.
int	getDefaultKeyLength() Gets the default key length for this algorithm.
int	getMaxKeyLength() Gets the maximum key length for this algorithm.
int	getMinKeyLength() Gets the minimum key length for this algorithm.
byte[]	getRandomIV() Gets a random initialization vector whose size is equal to the underlying cipher's block size.
boolean	hasIV() Determines whether the cipher has been provided with iv data.
boolean	isValidKeyLength(int bitLength) Determines whether the given key size in bits is valid for this symmetric cipher algorithm.
static SymmetricAlgorithm	newInstance(AlgorithmSpec spec) Creates a new instance from an algorithm specification.
static SymmetricAlgorithm	newInstance(AlgorithmSpec spec, AlgorithmParameterSpec cipherSpec) Creates a new instance from an algorithm specification and cipher initialization parameters.
static SymmetricAlgorithm	newInstance(String cipherAlgorithm) Creates a new instance that uses a cipher of the given algorithm and the default mode and padding.
static SymmetricAlgorithm	newInstance(String cipherAlgorithm, String cipherModeName, String cipherPadding) Creates a new instance that uses a cipher of the given algorithm.
void	setIV(byte[] ivBytes) Sets the encryption initialization vector.

Methods inherited from class edu.vt.middleware.crypt.AbstractEncryptionAlgorithm

crypt, crypt, decrypt, decrypt, decrypt, encrypt, encrypt, encrypt, getBlockSize, getCipherMode, getMode, getPadding, init, initCipher, initDecrypt, initEncrypt, setKey, toString

Methods inherited from class edu.vt.middleware.crypt.AbstractAlgorithm

getAlgorithm, getRandomData, setRandomProvider

Methods inherited from class java.lang.Object

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

Methods inherited from interface edu.vt.middleware.crypt.Algorithm

getAlgorithm, getRandomData, setRandomProvider

Field Detail

DEFAULT_MODE

public static final String DEFAULT_MODE

Default mode used for encryption and decryption.

See Also:

Constant Field Values

DEFAULT_PADDING

public static final String DEFAULT_PADDING

Default padding used for encryption and decryption.

See Also:

Constant Field Values

iv

protected byte[] iv

Initialization vector used for encryption.

paramSpec

protected AlgorithmParameterSpec paramSpec

Cipher-specific initialization parameters provided to factory methods.

Constructor Detail

SymmetricAlgorithm

protected SymmetricAlgorithm(String cipherAlgorithm,
                             String cipherModeName,
                             String cipherPadding)

Creates a new instance that uses a cipher of the given algorithm.

Parameters:

cipherAlgorithm - Cipher algorithm name.

cipherModeName - Cipher mode.

cipherPadding - Cipher padding method.

Method Detail

newInstance

public static SymmetricAlgorithm newInstance(String cipherAlgorithm)

Creates a new instance that uses a cipher of the given algorithm and the default mode and padding.

Parameters:

cipherAlgorithm - Cipher algorithm name.

Returns:

Symmetric algorithm instance that implements the given cipher algorithm.

newInstance

public static SymmetricAlgorithm newInstance(AlgorithmSpec spec)

Creates a new instance from an algorithm specification.

Parameters:

spec - Algorithm specification.

Returns:

Symmetric algorithm instance based on the given specification.

newInstance

public static SymmetricAlgorithm newInstance(String cipherAlgorithm,
                                             String cipherModeName,
                                             String cipherPadding)

Creates a new instance that uses a cipher of the given algorithm.

Parameters:

cipherAlgorithm - Cipher algorithm name.

cipherModeName - Cipher mode.

cipherPadding - Cipher padding method.

Returns:

Symmetric algorithm instance that implements the given cipher algorithm.

newInstance

public static SymmetricAlgorithm newInstance(AlgorithmSpec spec,
                                             AlgorithmParameterSpec cipherSpec)

Creates a new instance from an algorithm specification and cipher initialization parameters.

Parameters:

spec - Algorithm specification.

cipherSpec - Cipher-specific initialization parameters.

Returns:

Symmetric algorithm instance that implements the given cipher algorithm.

generateKey

public static SecretKey generateKey(String algorithm,
                                    int bitLength,
                                    SecureRandom random)
                             throws CryptException

Generates a new secret key for encryption/decryption operations on a cipher of the given algorithm name.

Parameters:

algorithm - Name of cipher algorithm for which a suitable key will be generated.

bitLength - Bit length required in generated key. Valid key lengths are commonly a function of the cipher algorithm.

random - Source of random data for key generation operation.

Returns:

New secret key for use with cipher of given algorithm name.

Throws:

CryptException - if the private key cannot be generated

generateKey

public SecretKey generateKey()
                      throws CryptException

Generates a secret key of the default key size for encryption and decryption operations with this instance and others that use the same algorithm.

Returns:

New secret key whose algorithm matches that of this instance.

Throws:

CryptException - On key generation errors.

generateKey

public SecretKey generateKey(int bitLength)
                      throws CryptException

Generates a secret key of the given size for encryption and decryption operations with this instance and others that use the same algorithm.

Parameters:

bitLength - Bit length required in generated key. Valid key lengths are commonly a function of the cipher algorithm.

Returns:

New secret key whose algorithm matches that of this instance.

Throws:

CryptException - On key generation errors.

setIV

public void setIV(byte[] ivBytes)

Sets the encryption initialization vector. A unique IV should be specified for each encryption operation using the same key for good security. Use the getRandomIV() method to obtain random initialization data of the appropriate size for the chosen cipher.

IV data is used upon calling either AbstractEncryptionAlgorithm.initEncrypt() or AbstractEncryptionAlgorithm.initDecrypt().

Parameters:

ivBytes - Initialization bytes; in many cases the size of data should be equal to the cipher block size.

hasIV

public boolean hasIV()

Determines whether the cipher has been provided with iv data.

Returns:

True if an IV has been provided to the cipher, false otherwise.

getRandomIV

public byte[] getRandomIV()

Gets a random initialization vector whose size is equal to the underlying cipher's block size.

Returns:

An array of random bytes of a size equal to cipher block size as defined by AbstractEncryptionAlgorithm.getBlockSize().

getAllowedKeyLengths

public int[] getAllowedKeyLengths()

Gets an array of key lengths that are acceptable for the cipher algorithm. By convention the lengths are returned in descending sort order from longest to shortest. There are some ciphers (e.g. Blowfish) that allow key sizes to be any integral value in a range; in those cases only key sizes that are multiple of the cipher block length are returned. Thus this method always returns lengths that are acceptable, but not necessarily all possible lengths.

Returns:

Array of key lengths in bits.

getDefaultKeyLength

public int getDefaultKeyLength()

Gets the default key length for this algorithm.

Returns:

Default key length in bits.

getMinKeyLength

public int getMinKeyLength()

Gets the minimum key length for this algorithm.

Returns:

Minimum key length in bits.

getMaxKeyLength

public int getMaxKeyLength()

Gets the maximum key length for this algorithm.

Returns:

Maximum key length in bits.

isValidKeyLength

public boolean isValidKeyLength(int bitLength)

Determines whether the given key size in bits is valid for this symmetric cipher algorithm.

Parameters:

bitLength - Key size in bits.

Returns:

True if given value is a valid key size for this algorithm, false otherwise.

getAlgorithmParameterSpec

protected AlgorithmParameterSpec getAlgorithmParameterSpec()

Gets the algorithm parameter specification for this algorithm.

Specified by:

getAlgorithmParameterSpec in class AbstractEncryptionAlgorithm

Returns:

Algorithm parameter specification specific to this algorithm.

getChunkSize

protected int getChunkSize()

Gets the chunk size for buffers using in stream-based encryption and decryption operations.

Specified by:

getChunkSize in class AbstractEncryptionAlgorithm

Returns:

Stream chunk size.