Creating and maintaining hardware key ring files

You can use the hwkeytool command that is provided as part of the IBM® Java™ software development kit in much the same way as the keytool command to generate key rings and manage certificates. Extra parameters are available to specify how the key is stored on the cryptographic device, and how it is to be used. You also have the option of labeling the key on the cryptographic device.

To create a key ring, issue a command like the following: 
hwkeytool -genkey -alias aliasname -keyalg algorithm 
-storetype JCE4758KS -dname distname –keypass password 
-storepass password -hardwaretype type -hardwareusage KEYMANAGEMENT
The options are as follows:
-genkey
Generates a key pair and wraps the public key into a self-signed certificate.
-alias aliasname
Defines the alias name that identifies the store containing the self-signed certificate and private key.
-keyalg algorithm
The algorithm to be used to generate the key pair. See your Java SDK documentation for details.
-storetype
The format of the keystore.
-dname distname
Specifies the X.500 distinguished name to be associated with the alias. This is used as the issuer and subject fields of the self-signed certificate. The distinguished name consists of a number of fields separated by commas in the following format:

"cn=strvalue1,o=strvalue2,ou=strvalue3, l=strvalue4,s=strvalue5,c=strvalue6"

Each strvalue is a string value. The meaning of the abbreviations is as follows:

  • cn = common name
  • o = organization
  • ou = organization unit
  • l = city/locality
  • s = state/province
  • c = country name
An example of an X.500 distinguished name: 
"cn=someserver.company.ibm.com,o=IBM,ou=IBMGB,
   l=Winchester,s=Hants,c=GB"
-keypass password
The password used to protect the private key. Set this to the same value as the -storepass password, so that the CICS® Transaction Gateway can establish a connection over SSL.
-storepass password
The password used to protect the integrity of the key ring. Set this to the same value as the -keypass password, so that the CICS Transaction Gateway can establish a connection over SSL.
-hardwaretype type
The type of key pair that is being generated. Either CLEAR, PKDS or RETAINED. The default value is CLEAR.
-hardwareusage KEYMANAGEMENT
Sets the usage of the key pair being generated (SIGNATURE or KEYMANAGEMENT). The default value is KEYMANAGEMENT except for DSA keys, where it is SIGNATURE.
The following optional parameter is available when you are using the -genkey flag:
-KeyLabel
The label that will identify the private key on the hardware device. If this is not present a randomly-generated string is used.
The following optional parameter is available if you use -delete to delete a key:
-hardwarekey
Deletes the key pair from the hardware storage as well as the keystore. The default is that it is deleted only from the keystore.

The default keystore name when using hwkeytool is .HWkeystore in the user's home directory. Use the -keystore parameter to change this.

Every keystore file created by hwkeytool needs to have these items in the keystore:
  • The personal certificate
  • The Certificate Authority certificate used to sign it
If the personal certificate is self-signed, (created with the -selfcert parameter), first export the certificate and then import it into the same keystore file under a different alias. If you are warned when importing the certificate back into the keystore that it already exists in the keystore, type Y to confirm that you want to import it.