com.entrust.toolkit.security.spec

Class AesKeyWrapParameterSpec

java.lang.Object

com.entrust.toolkit.security.spec.AesKeyWrapParameterSpec

All Implemented Interfaces:

java.security.spec.AlgorithmParameterSpec

public class AesKeyWrapParameterSpec
extends java.lang.Object
implements java.security.spec.AlgorithmParameterSpec

A transparent algorithm parameters representation for Entrust's AesKeyWrap algorithm implementation.

It contain an initial value that is used to obtain an integrity check on the key data. The exact properties achieved by this integrity check depend on the definition of the initial value. Different applications may call for somewhat different properties; for example, whether there is need to determine the integrity of key data throughout its lifecycle or just when it is unwrapped. The AES Key Wrap Specification defines the default initial value as a hexadecimal constant: A6A6A6A6A6A6A6A6.

The default initial value supports integrity of the key data during the period it is wrapped. When using the default initial value, if unwrapping produces an initial value of A6A6A6A6A6A6A6A6, then the chance that the key data is corrupt is 2^-64. If unwrapping does not produce an initial value of A6A6A6A6A6A6A6A6, then an integrity problem has been encountered and the key data is considered corrupt. When attempting to use the AES key wrap algorithm with the default initial value, manually specifying it using this class is not necessary; it is automatically used by default.

When the key wrap is used as part of a larger key management protocol or system, the desired scope for data integrity may be more than just the key data or the desired duration for more than just the period that it is wrapped. Also, if the key data is not just an AES key, it may not always be a multiple of 64 bits. Alternative definitions of the initial value can be used to address such problems. NIST will define alternative initial values in future key management publications as needed. In order to accommodate a set of alternatives that may evolve over time, Entrust's AES key wrap algorithm implementation allows the initial value to be specified (replacing the default initial value). However, since NIST has not yet defined how the AES key wrap algorithm will operate using an initial value that is not 64 bits in length, the length of the initial value MUST be exactly 64 bits.

Since:

7.2

See Also:

AesKeyWrap

Constructor Summary

Constructors

Constructor and Description
AesKeyWrapParameterSpec() The default constructor.
AesKeyWrapParameterSpec(byte[] initialValue) Creates a new InitialValueParameterSpec object with the specified initial value.
AesKeyWrapParameterSpec(byte[] initialValue, int offset, int length) Creates a new InitialValueParameterSpec object with the specified initial value.

Method Summary

Methods

Modifier and Type	Method and Description
byte[]	getInitialValue() Returns a copy of the initial value.
void	setInitialValue(byte[] initialValue) Sets the initial value by copying the data from the specified byte array.
void	setInitialValue(byte[] initialValue, int offset, int length) Sets the initial value by copying specified amount of data from the byte array beginning at the specified offset.

Methods inherited from class java.lang.Object

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

Constructor Detail

AesKeyWrapParameterSpec

public AesKeyWrapParameterSpec()

The default constructor.

It creates a new InitialValueParameterSpec object with a default initial value: A6A6A6A6A6A6A6A6, as defined in the AES Key Wrap Specification.

AesKeyWrapParameterSpec

public AesKeyWrapParameterSpec(byte[] initialValue)

Creates a new InitialValueParameterSpec object with the specified initial value.

The supplied byte array is copied, and used as the initial value.

Parameters:

initialValue - a byte array containing the initial value

Throws:

java.lang.IllegalArgumentException - thrown if the byte array is null or not 64 bits in length

AesKeyWrapParameterSpec

public AesKeyWrapParameterSpec(byte[] initialValue,
                       int offset,
                       int length)

Creates a new InitialValueParameterSpec object with the specified initial value.

The initial value is copied from the supplied byte array starting at the indicated offset.

Parameters:

initialValue - a byte array containing the initial value

offset - the offset in the byte array where the initial value begins

length - the length of initial value

Throws:

java.lang.IllegalArgumentException - thrown if the byte array is null or the length of the initial value is not 64 bits

java.lang.ArrayIndexOutOfBoundsException - thrown if an initial value of the specified size could not be extracted from the byte array

java.lang.NegativeArraySizeException - thrown if length is negative

Method Detail

getInitialValue

public byte[] getInitialValue()

Returns a copy of the initial value.

Returns:

a copy of the initial value

setInitialValue

public void setInitialValue(byte[] initialValue)

Sets the initial value by copying the data from the specified byte array.

Parameters:

initialValue - a byte array containing the initial value

Throws:

java.lang.IllegalArgumentException - thrown if the byte array is null or not 64 bits in length

setInitialValue

public void setInitialValue(byte[] initialValue,
                   int offset,
                   int length)

Sets the initial value by copying specified amount of data from the byte array beginning at the specified offset.

Parameters:

initialValue - a byte array containing the initial value

offset - the offset in the byte array where the initial value begins

length - the length of initial value

Throws:

java.lang.IllegalArgumentException - thrown if the byte array is null or the length of the initial value is not 64 bits

java.lang.ArrayIndexOutOfBoundsException - thrown if an initial value of the specified size could not be extracted from the byte array

java.lang.NegativeArraySizeException - thrown if length is negative