org.owasp.esapi.crypto

Class CipherSpec

java.lang.Object

org.owasp.esapi.crypto.CipherSpec

All Implemented Interfaces:

java.io.Serializable

public final class CipherSpec
extends java.lang.Object
implements java.io.Serializable

Specifies all the relevant configuration data needed in constructing and using a Cipher except for the encryption key.

The "setters" all return a reference to this so that they can be strung together.

Note: While this is a useful class in it's own right, it should primarily be regarded as an implementation class to use with ESAPI encryption, especially the reference implementation. It is not intended to be used directly by application developers, but rather only by those either extending ESAPI or in the ESAPI reference implementation. Use directly by application code is not recommended or supported.

Since:

2.0

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	CipherSpec.CipherTransformationComponent

Field Summary

Fields

Modifier and Type	Field and Description
private int	blockSize_
private java.lang.String	cipher_xform_
private byte[]	iv_
private int	keySize_
private static long	serialVersionUID

Constructor Summary

Constructors

Constructor and Description
CipherSpec() Default CTOR.
CipherSpec(byte[] iv)
CipherSpec(javax.crypto.Cipher cipher) CTOR that sets everything except for the cipher key size and possibly the IV.
CipherSpec(javax.crypto.Cipher cipher, int keySize) CTOR that sets everything.
CipherSpec(java.lang.String cipherXform, int keySize) CTOR that sets everything but block size and IV.
CipherSpec(java.lang.String cipherXform, int keySize, byte[] iv) CTOR that sets everything except block size.
CipherSpec(java.lang.String cipherXform, int keySize, int blockSize) CTOR that sets everything but IV.
CipherSpec(java.lang.String cipherXform, int keySize, int blockSize, byte[] iv) CTOR that explicitly sets everything.

Method Summary

Modifier and Type	Method and Description
protected boolean	canEqual(java.lang.Object other) Needed for correct definition of equals for general classes.
boolean	equals(java.lang.Object other)
int	getBlockSize() Retrieve the block size, in bytes.
java.lang.String	getCipherAlgorithm() Retrieve the cipher algorithm.
java.lang.String	getCipherMode() Retrieve the cipher mode.
java.lang.String	getCipherTransformation() Get the cipher transformation.
private java.lang.String	getFromCipherXform(CipherSpec.CipherTransformationComponent component) Split the current cipher transformation and return the requested part.
byte[]	getIV() Retrieve the initialization vector (IV).
int	getKeySize() Retrieve the key size, in bits.
java.lang.String	getPaddingScheme() Retrieve the cipher padding scheme.
int	hashCode()
boolean	requiresIV() Return true if the cipher mode requires an IV.
CipherSpec	setBlockSize(int blockSize) Set the block size for this CipherSpec.
CipherSpec	setCipherTransformation(java.lang.String cipherXform) Set the cipher transformation for this CipherSpec.
private CipherSpec	setCipherTransformation(java.lang.String cipherXform, boolean fromCipher) Set the cipher transformation for this CipherSpec.
CipherSpec	setIV(byte[] iv) Set the initialization vector (IV).
CipherSpec	setKeySize(int keySize) Set the key size for this CipherSpec.
java.lang.String	toString() Override Object.toString() to provide something more useful.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

cipher_xform_

private java.lang.String cipher_xform_

keySize_

private int keySize_

blockSize_

private int blockSize_

iv_

private byte[] iv_

Constructor Detail

CipherSpec

public CipherSpec(java.lang.String cipherXform,
                  int keySize,
                  int blockSize,
                  byte[] iv)

CTOR that explicitly sets everything.

Parameters:

cipherXform - The cipher transformation

keySize - The key size (in bits).

blockSize - The block size (in bytes).

iv - The initialization vector. Null if not applicable.

CipherSpec

public CipherSpec(java.lang.String cipherXform,
                  int keySize,
                  int blockSize)

CTOR that sets everything but IV.

Parameters:

cipherXform - The cipher transformation

keySize - The key size (in bits).

blockSize - The block size (in bytes).

CipherSpec

public CipherSpec(java.lang.String cipherXform,
                  int keySize)

CTOR that sets everything but block size and IV.

CipherSpec

public CipherSpec(java.lang.String cipherXform,
                  int keySize,
                  byte[] iv)

CTOR that sets everything except block size.

CipherSpec

public CipherSpec(javax.crypto.Cipher cipher)

CTOR that sets everything except for the cipher key size and possibly the IV. (IV may not be applicable--e.g., with ECB--or may not have been specified yet.

CipherSpec

public CipherSpec(javax.crypto.Cipher cipher,
                  int keySize)

CTOR that sets everything.

CipherSpec

public CipherSpec(byte[] iv)

CipherSpec

public CipherSpec()

Default CTOR. Creates a cipher specification for 128-bit cipher transformation of "AES/CBC/PKCS5Padding" and a null IV.

Method Detail

setCipherTransformation

public CipherSpec setCipherTransformation(java.lang.String cipherXform)

Set the cipher transformation for this CipherSpec.

Parameters:

cipherXform - The cipher transformation string; e.g., "DESede/CBC/PKCS5Padding".

Returns:

This current CipherSpec object.

setCipherTransformation

private CipherSpec setCipherTransformation(java.lang.String cipherXform,
                                           boolean fromCipher)

Set the cipher transformation for this CipherSpec. This is only used by the CTOR CipherSpec(Cipher) and CipherSpec(Cipher, int).

Parameters:

cipherXform - The cipher transformation string; e.g., "DESede/CBC/PKCS5Padding". May not be null or empty.

fromCipher - If true, the cipher transformation was set via Cipher.getAlgorithm() which may only return the actual algorithm. In that case we check and if all 3 parts were not specified, then we specify the parts that were based on "ECB" as the default cipher mode and "NoPadding" as the default padding scheme.

Returns:

This current CipherSpec object.

getCipherTransformation

public java.lang.String getCipherTransformation()

Get the cipher transformation.

Returns:

The cipher transformation String.

setKeySize

public CipherSpec setKeySize(int keySize)

Set the key size for this CipherSpec.

Parameters:

keySize - The key size, in bits. Must be positive integer.

Returns:

This current CipherSpec object.

getKeySize

public int getKeySize()

Retrieve the key size, in bits.

Returns:

The key size, in bits, is returned.

setBlockSize

public CipherSpec setBlockSize(int blockSize)

Set the block size for this CipherSpec.

Parameters:

blockSize - The block size, in bytes. Must be positive integer.

Returns:

This current CipherSpec object.

getBlockSize

public int getBlockSize()

Retrieve the block size, in bytes.

Returns:

The block size, in bytes, is returned.

getCipherAlgorithm

public java.lang.String getCipherAlgorithm()

Retrieve the cipher algorithm.

Returns:

The cipher algorithm.

getCipherMode

public java.lang.String getCipherMode()

Retrieve the cipher mode.

Returns:

The cipher mode.

getPaddingScheme

public java.lang.String getPaddingScheme()

Retrieve the cipher padding scheme.

Returns:

The padding scheme is returned.

getIV

public byte[] getIV()

Retrieve the initialization vector (IV).

Returns:

The IV as a byte array.

setIV

public CipherSpec setIV(byte[] iv)

Set the initialization vector (IV).

Parameters:

iv - The byte array to set as the IV. A copy of the IV is saved. This parameter is ignored if the cipher mode does not require an IV.

Returns:

This current CipherSpec object.

requiresIV

public boolean requiresIV()

Return true if the cipher mode requires an IV.

Returns:

True if the cipher mode requires an IV, otherwise false.

toString

public java.lang.String toString()

Override Object.toString() to provide something more useful.

Overrides:

toString in class java.lang.Object

Returns:

A meaningful string describing this object.

equals

public boolean equals(java.lang.Object other)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

canEqual

protected boolean canEqual(java.lang.Object other)

Needed for correct definition of equals for general classes. (Technically not needed for 'final' classes like this class though; this will just allow it to work in the future should we decide to allow sub-classing of this class.)

See How to write an Equality Method in Java for full explanation.

getFromCipherXform

private java.lang.String getFromCipherXform(CipherSpec.CipherTransformationComponent component)

Split the current cipher transformation and return the requested part.

Parameters:

component - The component of the cipher transformation to return.

Returns:

The cipher algorithm, cipher mode, or padding, as requested.