Module ibm.crypto.hdwrcca

Package com.ibm.crypto.hdwrCCA.provider

Class CCAAlgorithmParameterSpec

java.lang.Object

com.ibm.crypto.hdwrCCA.provider.CCAAlgorithmParameterSpec

All Implemented Interfaces:

java.security.spec.AlgorithmParameterSpec

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

This class specifies a set of parameters that can optionally be used with the init method of the DESedeKeyGenerator, DESKeyGenerator, and AESKeyGenerator classes.

This class can also be used with the RSA cipher class for specifying parameters associated with how a secret key is to be unwrapped.

If the key type is SECURE_INTERNAL_TOKEN, then only the key token is returned from the hardware and resident in memory.

If the key type is CKDS, after the SECURE_INTERNAL_TOKEN key is passed to the hardware, only the CKDS entry label is resident in memory.

Field Summary

Fields

Modifier and Type	Field	Description
static byte	CKDS	A key that is encrypted by the ICSF host master key and stored in the CKDS.
static byte	CLEAR	A clear key.
static byte	PROTECTED	Deprecated. This is deprecated and SECURE_INTERNAL_TOKEN should be used instead.
static byte	SECURE_INTERNAL_TOKEN	A key that is encrypted by the ICSF host master key, sometimes called a secure hardware key, and saved as a key token.
static byte	WRAPPING_MODE_CBC	This value represents the encryption wrapping mode to be used while wrapping the key value.
static byte	WRAPPING_MODE_DEFAULT	This value represents the encryption wrapping mode to be used while wrapping the key value.
static byte	WRAPPING_MODE_ECB	This value represents the encryption wrapping mode to be used while wrapping the key value.

Constructor Summary

Constructors

Constructor	Description
CCAAlgorithmParameterSpec()	Constructs a parameter set for a DES, DESede, or AES key.
CCAAlgorithmParameterSpec(byte hwType)	Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
CCAAlgorithmParameterSpec(byte hwType, java.lang.String label)	Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
CCAAlgorithmParameterSpec(int size)	Constructs a parameter set with the desired key size for a DES, DESede, or AES key.
CCAAlgorithmParameterSpec(int size, byte hwType)	Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
CCAAlgorithmParameterSpec(int size, byte hwType, java.lang.String label)	Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.
CCAAlgorithmParameterSpec(int size, byte hwType, java.lang.String label, byte wrappingMode)	Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.

Method Summary

Modifier and Type	Method	Description
byte	getHwType()	Returns the type of key to be generated.
javax.crypto.SecretKey	getKey2KeyEncryptingKey()	Returns the specified key encrypting key.
int	getKeySize()	Get the desired key size.
SymmetricKeyConstants.KeyUsage	getKeyUsage()	Returns the user specified hardware key usage attributes.
java.lang.String	getLabel()	Returns a CKDS label.
boolean	getNoCvKEK()	Returns the NoCvKEK attribute.
javax.crypto.spec.OAEPParameterSpec	getOAEPParameterSpec()	Returns OAEP padding parameters.
byte	getTokenWrappingMode()	Returns the type of key token wrapping to be used.
TR31OptionalDataBlock[]	getTR31OptionalDataBlocks()	Returns a user-specified block of optional data blocks suitable to be included when a TR-31 KeyBlock is created to export a key.
protected boolean	isSecureInternalToken()	Checks to see if this CCAAlgorithmParameterSpec is a SECURE_INTERNAL_TOKEN type.
void	setHwType(byte hwTypeVal)	Sets the type of key to be generated.
void	setKey2KeyEncryptingKey(javax.crypto.SecretKey key2KeyEncryptingKey)	Sets the key encrypting key that will be used to wrap the second key of a generated key pair.
void	setKeySize(int size)	Set the desired key size for the key to be generated.
void	setKeyUsage(SymmetricKeyConstants.KeyUsage keyUsage)	Sets hardware key usage attributes.
void	setLabel(java.lang.String label)	Sets the label for a CKDS type hardware key.
void	setNoCvKEK(boolean NoCvKEK)	Specifies whether the CKDS Key Encrypting Key should be created with the NoCvKEK option.
void	setOAEPParameterSpec(javax.crypto.spec.OAEPParameterSpec oaepSpec)	Sets the OAEP padding parameters.
void	setTokenWrappingMode(byte wrappingMode)	Sets the type of key token wrapping mode to be used.
void	setTR31OptionalDataBlock(TR31OptionalDataBlock OptData)	Specifies an optional data block to be included when a TR-31 KeyBlock is created to export a key.
void	setTR31OptionalDataBlocks(TR31OptionalDataBlock[] OptData)	Specifies an array of optional data blocks to be included when a TR-31 KeyBlock is created to export a key.

Methods inherited from class java.lang.Object

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

Field Detail

CKDS

public static final byte CKDS

A key that is encrypted by the ICSF host master key and stored in the CKDS. The key is wrapped by the ICSF master key using the default key wrapping modes as set within ICSF.

See Also:

Constant Field Values

PROTECTED

@Deprecated
public static final byte PROTECTED

Deprecated.

This is deprecated and SECURE_INTERNAL_TOKEN should be used instead. A key that is encrypted by the ICSF host master key, sometimes called a secure hardware key, and saved as a key token. This is the default type. The key is wrapped by the ICSF master key using the default key wrapping modes as set within ICSF.

See Also:

Constant Field Values

CLEAR

public static final byte CLEAR

A clear key.

See Also:

Constant Field Values

SECURE_INTERNAL_TOKEN

public static final byte SECURE_INTERNAL_TOKEN

A key that is encrypted by the ICSF host master key, sometimes called a secure hardware key, and saved as a key token. This is the default type. The key is wrapped by the ICSF master key using the default key wrapping modes as set within ICSF.

See Also:

Constant Field Values

WRAPPING_MODE_DEFAULT

public static final byte WRAPPING_MODE_DEFAULT

This value represents the encryption wrapping mode to be used while wrapping the key value. This mode will be used by ICSF to wrap the ICSF token with the ICSF master key. In this case the default mode as set by ICSF will be used. This setting is relevant to keys that are being generated or unwrapped as CKDS or SECURE_INTERNAL_TOKEN keys.

See Also:

Constant Field Values

WRAPPING_MODE_ECB

public static final byte WRAPPING_MODE_ECB

This value represents the encryption wrapping mode to be used while wrapping the key value. This mode will be used by ICSF to wrap the ICSF token with the ICSF master key. In this case the EBC mode will be used. This setting is relevant to keys that are being generated or unwrapped as CKDS or SECURE_INTERNAL_TOKEN keys.

See Also:

Constant Field Values

WRAPPING_MODE_CBC

public static final byte WRAPPING_MODE_CBC

This value represents the encryption wrapping mode to be used while wrapping the key value. This mode will be used by ICSF to wrap the ICSF token with the ICSF master key. In this case the CBC mode will be used. ICSF currently refers to the CBC mode as enhanced key wrapping mode. This setting is relevant to keys that are being generated or unwrapped as CKDS or SECURE_INTERNAL_TOKEN keys.

See Also:

Constant Field Values

Constructor Detail

CCAAlgorithmParameterSpec

public CCAAlgorithmParameterSpec()

Constructs a parameter set for a DES, DESede, or AES key. Key type will default to SECURE_INTERNAL_TOKEN using the default wrapping mode WRAPPING_MODE_DEFAULT as set by ICSF.

CCAAlgorithmParameterSpec

public CCAAlgorithmParameterSpec(int size)

Constructs a parameter set with the desired key size for a DES, DESede, or AES key. Key type will default to SECURE_INTERNAL_TOKEN using the default wrapping mode WRAPPING_MODE_DEFAULT as set by ICSF.

Parameters:

size - the size or strength of the requested key, a key size of 0 indicates that the default key size of the key generator or cipher is to be used

CCAAlgorithmParameterSpec

public CCAAlgorithmParameterSpec(byte hwType)

Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.

Parameters:

hwType - the type of key to be generated. This must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS. If the hwType is CKDS and a CKDS label is not explicitly specified, a CKDS label will be generated automatically

Throws:

java.security.InvalidParameterException - if hwType is not valid.

CCAAlgorithmParameterSpec

public CCAAlgorithmParameterSpec(int size,
                                 byte hwType)

Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.

Parameters:

size - the size or strength of the requested key, a key size of 0 indicates that the default key size of the key generator or cipher is to be used

hwType - the type of key to be generated. This must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS. If the hwType is CKDS and a CKDS label is not explicitly specified, a CKDS label will be generated automatically

Throws:

java.security.InvalidParameterException - if hwType is not valid.

CCAAlgorithmParameterSpec

public CCAAlgorithmParameterSpec(int size,
                                 byte hwType,
                                 java.lang.String label)

Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.

Parameters:

size - the size or strength of the requested key, a key size of 0 indicates that the default key size of the key generator or cipher is to be used

hwType - the type of key to be generated. This must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS

label - if hwType is CKDS, this label will be used to identify the CKDS entry created to store the key. Otherwise, this label is ignored. This label must not be longer than 64 characters and cannot include embedded spaces. If null is specified, a label will be generated automatically if hwType is CKDS

Throws:

java.security.InvalidParameterException - if hwType is not valid or if label is longer than 64 characters.

CCAAlgorithmParameterSpec

public CCAAlgorithmParameterSpec(byte hwType,
                                 java.lang.String label)

Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.

Parameters:

hwType - the type of key to be generated. This must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS

label - if hwType is CKDS, this label will be used to identify the CKDS entry created to store the key. Otherwise, this label is ignored. This label must not be longer than 64 characters and cannot include embedded spaces. If null is specified, a label will be generated automatically if hwType is CKDS

Throws:

java.security.InvalidParameterException - if hwType is not valid or if label is longer than 64 characters.

CCAAlgorithmParameterSpec

public CCAAlgorithmParameterSpec(int size,
                                 byte hwType,
                                 java.lang.String label,
                                 byte wrappingMode)

Constructs a parameter set for specifying the characteristics of the desired DES, DESede, or AES key.

Parameters:

size - the size or strength of the requested key, a key size of 0 indicates that the default key size of the key generator or cipher is to be used

hwType - the type of key to be generated. This must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS

label - if hwType is CKDS, this label will be used to identify the CKDS entry created to store the key. Otherwise, this label is ignored. This label must not be longer than 64 characters and cannot include embedded spaces. If null is specified, a label will be generated automatically if hwType is CKDS

wrappingMode - the wrapping mode to be used by ICSF. This value will only be used when the key type is set to SECURE_INTERNAL_TOKEN or CKDS. If the key type is CLEAR, this value is ignored. The wrappingMode must be one of WRAPPING_MODE_DEFAULT, WRAPPING_MODE_CBC, or WRAPPING_MODE_ECB

Throws:

java.security.InvalidParameterException - if hwType is not valid, label is longer than 64 characters, or wrappingMode is not valid.

Method Detail

getKeySize

public int getKeySize()

Get the desired key size.

Returns:

the desired key size.

setKeySize

public void setKeySize(int size)

Set the desired key size for the key to be generated.

Parameters:

size - the desired key size, a key size of 0 indicates that the default key size of the key generator or cipher is to be used

getHwType

public byte getHwType()

Returns the type of key to be generated.

Returns:

the type of key to be generated, must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS.

setHwType

public void setHwType(byte hwTypeVal)

Sets the type of key to be generated.

Parameters:

hwTypeVal - the type of key to be generated, this must be one of CLEAR, SECURE_INTERNAL_TOKEN, or CKDS

Throws:

java.security.InvalidParameterException - if the supplied hwTypeVal is not supported.

getLabel

public java.lang.String getLabel()

Returns a CKDS label.

Returns:

the user specified CKDS entry label. If no label was specified, then null will be returned.

setLabel

public void setLabel(java.lang.String label)

Sets the label for a CKDS type hardware key.

Parameters:

label - if the key to be generated is a CKDS key, then this label will be used to identify the CKDS entry associated with the key. Otherwise, this label will be ignored. This label must not be longer than 64 characters and must not include embedded spaces.

Throws:

java.security.InvalidParameterException - if label is longer than 64 characters in length.

getTokenWrappingMode

public byte getTokenWrappingMode()

Returns the type of key token wrapping to be used. Key token wrapping applies only for SECURE_INTERNAL_TOKEN and CKDS hardware key types.

Returns:

the key token wrapping mode to be used, one of WRAPPING_MODE_DEFAULT, WRAPPING_MODE_CBC, or WRAPPING_MODE_ECB.

setTokenWrappingMode

public void setTokenWrappingMode(byte wrappingMode)
                          throws java.security.InvalidParameterException

Sets the type of key token wrapping mode to be used. Key token wrapping occurs only for SECURE_INTERNAL_TOKEN and CKDS hardware key types.

Parameters:

wrappingMode - the wrapping mode to be used, this must be one of WRAPPING_MODE_DEFAULT, WRAPPING_MODE_CBC, or WRAPPING_MODE_ECB

Throws:

java.security.InvalidParameterException - if the wrappingMode is not supported.

setOAEPParameterSpec

public void setOAEPParameterSpec(javax.crypto.spec.OAEPParameterSpec oaepSpec)

Sets the OAEP padding parameters.

Parameters:

oaepSpec - the OAEP padding parameters

getOAEPParameterSpec

public javax.crypto.spec.OAEPParameterSpec getOAEPParameterSpec()

Returns OAEP padding parameters.

Returns:

the OAEP padding parameters if previously set, otherwise returns null.

setNoCvKEK

public void setNoCvKEK(boolean NoCvKEK)

Specifies whether the CKDS Key Encrypting Key should be created with the NoCvKEK option. This is usually true only when the KEK will be used to export keys to non-z/OS systems, as in a TR-31 Key Block.

The default value is false.

The NoCvKEK attribute is only allowed when generating a KEK in the CKDS or importing a KEK to the CKDS.

Parameters:

NoCvKEK - the requested key usage NoCvKEK attribute

getNoCvKEK

public boolean getNoCvKEK()

Returns the NoCvKEK attribute.

Returns:

the NoCvKEK attribute.

setTR31OptionalDataBlocks

public void setTR31OptionalDataBlocks(TR31OptionalDataBlock[] OptData)

Specifies an array of optional data blocks to be included when a TR-31 KeyBlock is created to export a key. Optional data blocks are used to specify key attributes not included in the formal Tr-31 KeyBlock header but required by the platform where the KeyBlock will be unwrapped.

The tr31OptionalDataBlocks attribute is ignored if not creating a TR-31 KeyBlock.

This method follows a replace model. After this method is called, the CCAAlgorithmParameterSpec will contain only the TR31OptionalDataBlocks specified in this method call.

This method copies the data passed to it into local storage so it will be unaffected by changes the caller makes after the call.

Parameters:

OptData - An array of TR31OptionalDataBlock objects to be included in a TR-31 KeyBlock.

setTR31OptionalDataBlock

public void setTR31OptionalDataBlock(TR31OptionalDataBlock OptData)

Specifies an optional data block to be included when a TR-31 KeyBlock is created to export a key. Optional data blocks are used to specify key attributes not included in the formal Tr-31 KeyBlock header but required by the platform where the KeyBlock will be unwrapped.

The tr31OptionalDataBlocks attribute is ignored if not creating a TR-31 KeyBlock.

This method follows a replace model. After this method is called, the CCAAlgorithmParameterSpec will contain exactly one TR31OptionalDataBlock.

This method copies the data passed to it into local storage so it will be unaffected by changes the caller makes after the call.

Parameters:

OptData - A TR31OptionalDataBlock object to be included in a TR-31 KeyBlock.

getTR31OptionalDataBlocks

public TR31OptionalDataBlock[] getTR31OptionalDataBlocks()

Returns a user-specified block of optional data blocks suitable to be included when a TR-31 KeyBlock is created to export a key. Optional data blocks are used to specify key attributes not included in the formal Tr-31 KeyBlock header but required by the platform where the KeyBlock will be unwrapped.

Returns:

user-specified block of optional data blocks suitable to be included when a TR-31 KeyBlock is created.

setKeyUsage

public void setKeyUsage(SymmetricKeyConstants.KeyUsage keyUsage)

Sets hardware key usage attributes. This may be a single operational DATA key, or something more complex, like a pair of key encrypting keys.

The default key usage attribute for hardware DES, Triple-DES, and AES key generation is SymmetricKeyConstants.KeyUsage.OP_DATA. Valid key usage attribute for DES key generation is SymmetricKeyConstants.KeyUsage.OP_DATA. Valid key usage attributes for Triple-DES and AES key generation are SymmetricKeyConstants.KeyUsage.OP_DATA, SymmetricKeyConstants.KeyUsage.OPEX_EXPORTER_IMPORTER, and SymmetricKeyConstants.KeyUsage.OPEX_IMPORTER_EXPORTER.

Hardware key usage attribute is ignored if generating CLEAR keys.

Parameters:

keyUsage - the requested key usage attribute, null may be specified to indicate the default key usage attribute

getKeyUsage

public SymmetricKeyConstants.KeyUsage getKeyUsage()

Returns the user specified hardware key usage attributes.

Returns:

the user specified hardware key usage attributes, or null if not previously set.

setKey2KeyEncryptingKey

public void setKey2KeyEncryptingKey(javax.crypto.SecretKey key2KeyEncryptingKey)

Sets the key encrypting key that will be used to wrap the second key of a generated key pair.

Parameters:

key2KeyEncryptingKey - key encrypting key that will be used to wrap the second key of a generated key pair, has no effect if not generating a key pair

Throws:

java.security.InvalidParameterException - if key2KeyEncryptingKey is not an instance of DESedeKey or AESKey, or if the key type is CLEAR.

getKey2KeyEncryptingKey

public javax.crypto.SecretKey getKey2KeyEncryptingKey()

Returns the specified key encrypting key.

Returns:

the specified key encrypting key, or null if no such key was specified.

isSecureInternalToken

protected boolean isSecureInternalToken()

Checks to see if this CCAAlgorithmParameterSpec is a SECURE_INTERNAL_TOKEN type.

Returns:

true if hwType is SECURE_INTERNAL_TOKEN or PROTECTED.