Module ibm.crypto.hdwrcca

Package com.ibm.crypto.hdwrCCA.provider

Class KDFParameterSpec

java.lang.Object

com.ibm.crypto.hdwrCCA.provider.KDFParameterSpec

All Implemented Interfaces:

AlgorithmParameterSpec

public class KDFParameterSpec
extends Object
implements AlgorithmParameterSpec

This class specifies the set of parameters to be used during the key derivation step of the Diffie-Hellman key agreement algorithm.

Constructor Summary

Constructors

Constructor	Description
KDFParameterSpec(int keySize, byte[] sharedInfo)	Constructs a parameter set to be used during the key derivation step of the Diffie-Hellman key agreement algorithm.
KDFParameterSpec(int keySize, byte[] sharedInfo, SymmetricKeyConstants.KeyType keyType, String ckdsLabel, SymmetricKeyConstants.KeyUsage keyUsage)	Constructs a parameter set to be used during the key derivation step of the Diffie-Hellman key agreement algorithm.
KDFParameterSpec(int keySize, byte[] sharedInfo, SymmetricKeyConstants.KeyType keyType, String ckdsLabel, SymmetricKeyConstants.KeyUsage keyUsage, boolean NoCvKEK)	Constructs a parameter set to be used during the key derivation step of the Diffie-Hellman key agreement algorithm.

Method Summary

Modifier and Type	Method	Description
String	getCKDSLabel()	Returns the user provided CKDS label.
int	getKeySize()	Return the size of the secret key to derive using Diffie-Hellman.
SymmetricKeyConstants.KeyType	getKeyType()	Returns the type of key to derive using Diffie-Hellman.
SymmetricKeyConstants.KeyUsage	getKeyUsage()	Returns the usage of key to derive using Diffie-Hellman.
boolean	getNoCvKEK()	Returns the value of the NoCvKEK option for the key to derive using Diffie-Hellman.
byte[]	getSharedInfo()	Return a clone of the information shared by the participants of the Diffie-Hellman key agreement.

Methods inherited from class java.lang.Object

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

Constructor Details

KDFParameterSpec

public KDFParameterSpec(int keySize,
 byte[] sharedInfo)

Constructs a parameter set to be used during the key derivation step of the Diffie-Hellman key agreement algorithm.

By default, keys will be derived as SymmetricKeyConstants.KeyType.PROTECTED keys. The default key usage of the derived keys depends on the key algorithm of the key to be derived.

Parameters:

keySize - the size of the secret key to derive using Diffie-Hellman. It must be between 56 and 2048

sharedInfo - the information shared by the participants of the Diffie-Hellman key agreement. It must be between 8 and 64 bytes long. If no information will be shared by the participants, null may be specified

Throws:

IllegalArgumentException - if keySize or sharedInfo does not contain acceptable values.

See Also:

• KDFParameterSpec(int, byte[], KeyType, String, KeyUsage)

KDFParameterSpec

public KDFParameterSpec(int keySize,
 byte[] sharedInfo,
 SymmetricKeyConstants.KeyType keyType,
 String ckdsLabel,
 SymmetricKeyConstants.KeyUsage keyUsage)

Constructs a parameter set to be used during the key derivation step of the Diffie-Hellman key agreement algorithm.

By default, keys will be derived as SymmetricKeyConstants.KeyType.PROTECTED keys if null is specified for the keyType parameter. If the keyUsage parameter is null, the default key usage of the key algorithm of the key to be derived will be used. The default key usage for the DES and Triple-DES key algorithms is SymmetricKeyConstants.KeyUsage.OP_CIPHER, and the default key usage for the AES key algorithm is SymmetricKeyConstants.KeyUsage.OP_DATA.

Parameters:

keySize - the size of the secret key to derive using Diffie-Hellman. It must be between 56 and 2048

sharedInfo - the information shared by the participants of the Diffie-Hellman key agreement. It must be between 8 and 64 bytes long. If no information will be shared between the participants, null may be specified

keyType - the type of key to derive, this must be either SymmetricKeyConstants.KeyType.PROTECTED or SymmetricKeyConstants.KeyType.CKDS. SymmetricKeyConstants.KeyType.CLEAR bypasses key derivation and is currently not supported. To let the Diffie-Hellman key agreement service determine the default type of key to derive, a null may be specified

ckdsLabel - an optional user provided CKDS label. This field will be ignored when deriving a PROTECTED key. If this parameter is null and deriving a CKDS key, a random CKDS label will be generated and used

keyUsage - the key usage attribute of the derived key, this must be a single operational key. To let the Diffie-Hellman key agreement service determine the default key usage attribute of the derived key based on the key algorithm, a null may be specified. Valid key usage attribute for DES keys is SymmetricKeyConstants.KeyUsage.OP_CIPHER. Valid key usage attributes for Triple-DES keys are SymmetricKeyConstants.KeyUsage.OP_CIPHER, SymmetricKeyConstants.KeyUsage.OP_EXPORTER, and SymmetricKeyConstants.KeyUsage.OP_IMPORTER. Valid key usage attributes for AES keys are SymmetricKeyConstants.KeyUsage.OP_DATA, SymmetricKeyConstants.KeyUsage.OP_EXPORTER, and SymmetricKeyConstants.KeyUsage.OP_IMPORTER.

Throws:

IllegalArgumentException - if keySize, sharedInfo, keyType, ckdsLabel, or keyUsage does not contain acceptable values.

KDFParameterSpec

public KDFParameterSpec(int keySize,
 byte[] sharedInfo,
 SymmetricKeyConstants.KeyType keyType,
 String ckdsLabel,
 SymmetricKeyConstants.KeyUsage keyUsage,
 boolean NoCvKEK)

Constructs a parameter set to be used during the key derivation step of the Diffie-Hellman key agreement algorithm.

By default, keys will be derived as SymmetricKeyConstants.KeyType.PROTECTED keys if null is specified for the keyType parameter. If the keyUsage parameter is null, the default key usage of the key algorithm of the key to be derived will be used. The default key usage for the DES and Triple-DES key algorithms is SymmetricKeyConstants.KeyUsage.OP_CIPHER, and the default key usage for the AES key algorithm is SymmetricKeyConstants.KeyUsage.OP_DATA.

Parameters:

keySize - the size of the secret key to derive using Diffie-Hellman. It must be between 56 and 2048

sharedInfo - the information shared by the participants of the Diffie-Hellman key agreement. It must be between 8 and 64 bytes long. If no information will be shared between the participants, null may be specified

keyType - the type of key to derive, this must be either SymmetricKeyConstants.KeyType.PROTECTED or SymmetricKeyConstants.KeyType.CKDS. SymmetricKeyConstants.KeyType.CLEAR bypasses key derivation and is currently not supported. To let the Diffie-Hellman key agreement service determine the default type of key to derive, a null may be specified

ckdsLabel - an optional user provided CKDS label. This field will be ignored when deriving a PROTECTED key. If this parameter is null and deriving a CKDS key, a random CKDS label will be generated and used

keyUsage - the key usage attribute of the derived key, this must be a single operational key. To let the Diffie-Hellman key agreement service determine the default key usage attribute of the derived key based on the key algorithm, a null may be specified. Valid key usage attribute for DES keys is SymmetricKeyConstants.KeyUsage.OP_CIPHER. Valid key usage attributes for Triple-DES keys are SymmetricKeyConstants.KeyUsage.OP_CIPHER, SymmetricKeyConstants.KeyUsage.OP_EXPORTER, and SymmetricKeyConstants.KeyUsage.OP_IMPORTER. Valid key usage attributes for AES keys are SymmetricKeyConstants.KeyUsage.OP_DATA, SymmetricKeyConstants.KeyUsage.OP_EXPORTER, and SymmetricKeyConstants.KeyUsage.OP_IMPORTER.

NoCvKEK - specifies whether the CKDS key encrypting key should be created with the NoCvKEK option. This is only valid for a DESede key encrypting key in the CKDS. It is usually true only if the derived key encrypting key will be used to export a key to an non-z/OS system or import a key from a non-z/OS system.

Throws:

IllegalArgumentException - if keySize, sharedInfo, keyType, ckdsLabel, or keyUsage does not contain acceptable values.

IllegalArgumentException - if NoCvKEK is true and keyUsage or keyType does not contain acceptable values.

Method Details

getKeySize

public int getKeySize()

Return the size of the secret key to derive using Diffie-Hellman.

Returns:

the size of the secret key to derive using Diffie-Hellman

getSharedInfo

public byte[] getSharedInfo()

Return a clone of the information shared by the participants of the Diffie-Hellman key agreement.

Note that this method returns a clone of sensitive information. It is the caller's responsibility to zero out the information after it is no longer needed.

Returns:

A clone of the information shared by the participants of the Diffie-Hellman key agreement

getKeyType

public SymmetricKeyConstants.KeyType getKeyType()

Returns the type of key to derive using Diffie-Hellman.

Returns:

the type of key to derive using Diffie-Hellman.

getCKDSLabel

public String getCKDSLabel()

Returns the user provided CKDS label.

Returns:

the user provided CKDS label.

getKeyUsage

public SymmetricKeyConstants.KeyUsage getKeyUsage()

Returns the usage of key to derive using Diffie-Hellman.

Returns:

the usage of key to derive using Diffie-Hellman.

getNoCvKEK

public boolean getNoCvKEK()

Returns the value of the NoCvKEK option for the key to derive using Diffie-Hellman.

Returns:

the value of the NoCvKEK option for the key to derive using Diffie-Hellman.