The Key interface and KeySpec classes

The clear key material for private hardware keys of type PKDS is never returned to an application and can never be transported for use on another system. For this reason, no implementation of the java.security.Key interface can be used to represent them.

A software reference to a private hardware key of type PKDS is not a key or a key specification, but instead is a label that can be specified to the IBMJCECCA provider in place of a key. One of the following methods can be used to retrieve a representation of a hardware key pair:
public byte [] getToken()
public byte [] getLabelString()

For a DSA key pair, getLabelString() returns the label that represents the key that is stored in the CCA key storage area.

For an RSA or EC key pair of type CLEAR, getToken() should be used to return an internal CCA token. For an RSA or EC key pair of type PKDS, getLabelString() should be used to return the label that represents the key that is stored in the CCA key storage area.

The KeyLabelKeySpec class

This class (which implements the KeySpec interface) specifies the CCA label for an AES, DES, or DESede key that is stored in the CCA key storage area. If a KeyLabelKeySpec is passed to the generateSecret() method of an AESKeyFactory, a DESKeyFactory, or a DESedeKeyFactory then the key object that is returned represents a key that is already stored in the CCA key storage area. Note that generateSecret() does not create a new key in the CCA key storage area and also does not verify that such an entry exists in the CCA key storage area.

This class also specifies the CCA key storage area label for a DSA, RSA, or EC key pair that is stored in the system key storage area. If a KeyLabelKeySpec is passed to the generatePrivate() or the generatePublic() method of a RSAKeyFactory or an ECKeyFactory, or to the generatePrivate() method of a DSAKeyFactory, then the key object that is returned represents the corresponding key of a key pair that is already stored in the CCA key storage area. Note that generatePublic() and generatePrivate() do not create a new key in the CCA key storage area and also do not verify that such an entry currently exists in the CCA key storage area.

This class has the following methods:
public String getLabelString()
This method returns the CCA label for the key or the key pair.

The DSAPrivateHWKeySpec class

This class (which implements the KeySpec Interface) specifies a DSA private hardware key with its associated parameters. This class has the following methods:
public byte[] getLabel()
This method returns the private key label.
public DSAKeyHWAttributes getAttributes()
This method returns the DSA algorithm parameters used to calculate the key.
public DSAParameterSpec getDSAParamSpec()
This method returns the DSA hardware attributes that are associated with the key.

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

The RSAPrivateHWKeySpec class

This class (which implements the KeySpec Interface) specifies an RSA private hardware key with its associated parameters. This class has the following methods:

public byte[] getToken()
This method returns the private key token, which can be an internal CCA token or a CCA key storage area key record label.
public RSAKeyHWAttributes getAttributes()
This method returns the RSA hardware attributes that are associated with the key.

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

The ECPrivateHWKeySpec class

This class (which implements the KeySpec interface) specifies an EC private hardware key with its associated parameters. This class has the following methods:

public byte[] getToken()
This method returns the private key token, which can be an external CCA token or a CCA key storage area key record label.
public ECHWKeyAttributes getAttributes()
This method returns the EC hardware attributes associated with the key.
public ECParameterSpec getParams()
This method returns the elliptic curve domain parameters that are associated with the key.

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