Algorithm parameter classes

Classes that implement the AlgorithmParameterSpec interface.

The CCAAlgorithmParameterSpec class

This class (which implements the AlgorithmParameterSpec interface) specifies whether the AES, DES, or triple DES key to be generated or unwrapped is a secret hardware key and whether it is stored in the CCA key storage area.

In the default case, an object of this class is created without specifying a key type, and this object is passed to the init() method of an AESKeyGenerator, a DESKeyGenerator, or a DESedeKeyGenerator. In this case, a subsequent call to generateKey() returns a key object that contains the requested key, which is encrypted by using the host primary key.

A CCAAlgorithmParameterSpec object can be used to specify the strength (size) of the key to be generated.

A CCAAlgorithmParameterSpec object can be used to specify the type of CCA key token wrapping to use for a DES or DESede key that is of type CKDS or SECURE_INTERNAL_TOKEN.

If the CCAAlgorithmParameterSpec object is used to generate a CKDS type key, the CCAAlgorithmParameterSpec can be used to specify the desired label that is to be used to store the key within the CCA key storage area. If a label is specified, it must be unique in the CCA key storage area and must follow the CCA rules for labels. If no label is specifed for a new CCA entry, the KeyGenerator generateKey() method creates one automatically.

A CCAAlgorithmParameterSpec object can also be used to explicitly specify the type of key to be generated:

  • CCAAlgorithmParameterSpec.CKDS can be passed to the CCAAlgorithmParameterSpec constructor, and the resulting object passed to the init() method of an AESKeyGenerator, a DESKeyGenerator, or a DESedeKeyGenerator. In this case, a subsequent call to generateKey() returns a key object that contains the CCA label of the key encrypted using the host primary key and stored in the system CCA key storage area.
  • CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN can be passed to the CCAAlgorithmParameterSpec constructor, and the resulting object passed to the init() method of an AESKeyGenerator, a DESKeyGenerator, or a DESedeKeyGenerator. In this case, a subsequent call to generateKey() returns a key object that contains the requested key, which is encrypted by using the host primary key. This key can also be generated by using a KeyGenerator class and passing a CCAAlgorithmParameterSpec object, which was created without specifying a key type, to the KeyGenerator init() method.
  • CCAAlgorithmParameterSpec.CLEAR can be passed to the CCAAlgorithmParameterSpec constructor and the resulting object passed to the init() method of an AESKeyGenerator, a DESKeyGenerator, or a DESedeKeyGenerator. In this case, a subsequent call to generateKey() returns a key object that contains the clear key material for the requested key. This key can also be generated by using a KeyGenerator class without passing a CCAAlgorithmParameterSpec object to the KeyGenerator init() method.
CCAAlgorithmParameterSpec has the following constructor methods:
public CCAAlgorithmParameterSpec()
public CCAAlgorithmParameterSpec(int size)
public CCAAlgorithmParameterSpec(byte hwType)
public CCAAlgorithmParameterSpec(int size,byte hwType)
public CCAAlgorithmParameterSpec(int size,byte hwType,String label)
public CCAAlgorithmParameterSpec(byte hwType,String label)
public CCAAlgorithmParameterSpec(int size, byte hwType, String label, byte wrappingMode)

The following parameter restrictions apply to these constructor methods:

  • The size parameter must be valid for the specific algorithm of the KeyGenerator to which this CCAAlgorithmParameterSpec is passed.
  • The hwType parameter must be one of the following constant values:
    • CCAAlgorithmParameterSpec.CLEAR
    • CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN
    • CCAAlgorithmParameterSpec.CKDS
  • The label parameter must be valid for the CCA component, according to the rules that are defined for ICSF on z/OS®.
  • The wrappingMode parameter is used to specify the type of key wrapping that you want to use by CCA when you generate DES or DESede keys. Other key types, such as AES, do not honor the key wrapping mode value because they are always generated with the system default wrapping mode that is defined for ICSF on z/OS. Acceptable values for mode include ECB, CBC, and DEFAULT (the case is ignored for these values). When you use this flag, you receive an error under the following conditions:
    • When you generate a key that is not of type DES or DESede. Enhanced key wrapping is supported only for DES and DESede keys.
    • If you did not specify ECB, CBC, or DEFAULT for the mode.
    • If you specified the -wrappingMode flag when you created a CLEAR key. The enhanced key wrapping mode is supported only when you generatie SECURE_INTERNAL_TOKEN and CKDS types of keys.

The CCAAlgorithmParameterSpec class has the following methods.

Key size methods
These methods set or return the key size that is optionally specified to the CCAAlgorithmParameterSpec constructor method:
  • public int getKeySize()
  • public void setKeySize(int size)
If you do not specify a key size, the key size is set to 0.
Key type methods
These methods set or return the key type that is optionally specified to the CCAAlgorithmParameterSpec constructor method:
  • public byte getHwType()
  • public void setHwType(byte hwTypeVal)
The value is one of the following constants:
  • CCAAlgorithmParameterSpec.CLEAR
  • CCAAlgorithmParameterSpec.SECURE_INTERNAL_TOKEN
  • CCAAlgorithmParameterSpec.CKDS
Storage label methods
These methods set or return the CCA key storage label that is optionally specified to the CCAAlgorithmParameterSpec constructor method. If you do not specify a CCA label, this label is set to null:
  • public String getLabel()
  • public void setLabel(String label)
Wrapping mode methods
These methods set or return the CCA token wrapping mode that is optionally specified to the CCAAlgorithmParameterSpec constructor method. If you do not specify a wrapping mode, this mode is set to DEFAULT:
  • public byte getTokenWrappingMode()
  • public void setTokenWrappingMode(byte wrappingMode)

It is not necessary to specify a CCAAlgorithmParameterSpec object to create a key by using an AESKeyGenerator, DESKeyGenerator, or DESedeKeyGenerator object. If no CCAAlgorithmParameterSpec object is passed to the KeyGenerator init() method before the generateKey() method is called, the key object that is returned contains the clear key material for the requested key.

The KeyParameterSpec class for DSA hardware (DSAHWKeyParameterSpec)

This class (which implements the AlgorithmParameterSpec interface) specifies the set of parameters to use with the DSA hardware algorithm:

  • DSAKeyHWAttributes

    Due to hardware restrictions, these must be KeyHWAttributeValues.PKDS and KeyHWAttributeValues.SIGNATURE.

  • DSAParameterSpec
    These are as follows:
    • p: the prime
    • q: the sub-prime
    • g: the base
  • KeySize

    This parameter specifies the size of the key based on prime p.

  • KeyLabel

    This parameter specifies the name that is used as a reference to the key that is stored in the hardware.

See the Java™ API documentation for the specific methods, default values and restrictions that are associated with this class.

The KeyParameterSpec class for RSA hardware (RSAKeyParameterSpec)

This class (which implements the AlgorithmParameterSpec interface) specifies the set of parameters to use with the RSA hardware algorithm:

  • RSAKeyHWAttributes

    This parameter includes the following items:

    • RSAKeyHWAttributes.type
      This item must have one of the following values:
      • KeyHWAttributeValues.PKDS
      • KeyHWAttributeValues.CLEAR
      • KeyHWAttributeValues.RETAIN
    • RSAKeyHWAttributes.usage
      This item must have one of the following values:
      • KeyHWAttributeValues.SIGNATURE
      • KeyHWAttributeValues.KEYMANAGEMENT
  • KeySize

    This parameter specifies the size of the key.

  • KeyLabel

    If the RSAKeyHWAttributes.type is not specified as KeyHWAttributeValues.CLEAR, this parameter specifies the name that is used as a reference to the key that is stored in the CCA key storage area.

See the Java API documentation for the specific methods, default values and restrictions associated with this class.

The KeyParameterSpec class for EC hardware (ECHWKeyParameterSpec)

This class (which implements the AlgorithmParameterSpec interface) specifies the set of parameters to use with the EC hardware algorithm:

  • ECHWKeyAttributes

    This parameter includes the following items:

    • ECHWKeyAttributes.type

      This item must have one of the following values:

      • KeyHWAttributeValues.PKDS
      • KeyHWAttributeValues.CLEAR
    • ECHWKeyAttributes.usage

      This item must have one of the following values:

      • KeyHWAttributeValues.SIGNATURE
      • KeyHWAttributeValues.KEYMANAGEMENT
  • ECParameterSpec
    This item consists of the following items:
    • curve: the elliptic curve
    • g: the generator, which is also known as the base point
    • n: the order of the generator g
    • h: the cofactor
  • StandardName

    This parameter specifies the standard name of the elliptic curve domain parameters.

  • KeySize

    This parameter specifies the size of the key.

  • KeyLabel

    If the ECHWKeyAttributes.type is not specified as KeyHWAttributeValues.CLEAR, this parameter specifies the name that is used as a reference to the key that is stored in the CCA key storage area.

See the Java API documentation for the specific methods, default values, and restrictions associated with this class.