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.