Using the IBM Key Manager utility
This section provides a quick reference for using the IBM Key Manager utility
(iKeyman). Use the key manager to create your SSL key database file, public-private
key pair, and certificate request. After you receive the CA-signed certificate,
use the key manager to place the certificate in the key database where you
created the original certificate request.
More detailed documentation on the IBM Key Manager and GSKit is packaged
with the GSKit software.
Set up your system to run the key manager
Before starting the IKeyman GUI, do the following:
- Install IBM or an IBM-equivalent 32-bit Java
2 Technology, version 1.4.2
- Set JAVA_HOME to the Java directory location. For example:
- Windows: set JAVA_HOME=C:\Program Files\IBM\Java142
- Linux and UNIX: export JAVA_HOME=/usr/opt/IBMJava2-142
- Remove the ibmjsse.jar and the gskikm.jar (if present) and ibmjcaprovider.jar
files from your JAVA_HOME/jre/lib/ext directory.
Notes:
- For Solaris, substitute JAVA_HOME/lib/ext/ directory for JAVA_HOME/jre/lib/ext
directory.
- Do not move or delete jars in a JDK that another product (for
example, WebSphere Application Server) depends on. Doing so can break or prevent
the dependent product from operating properly. If you are unsure if the JDK
is in use, install a separate JDK for the IBM Key Management utility.
- All the following jar files are currently in the GSKit_Installation_path/classes/jre/lib/ext/.
- Copy the specified jar files into JAVA_HOME/jre/lib/
ibmjcefw.jar
ibmpkcs11.jar
- Copy the specified jar files into JAVA_HOME/jre/lib/ext
ibmjceprovider.jar
ibmpkcs.jar
- Copy the specified jar files to JAVA_HOME/jre/lib/security
local_policy.jar
US_export_policy.jar
- Register IBM JCE, IBM CMS, and/or IBMJCEFIPS service providers:
Update
the JAVA_HOME/jre/lib/security/java.security file to add both IBM CMS and
IBM JCE providers after the Sun provider. For example:
security.provider.1=sun.security.provider.Sun
security.provider.2=com.ibm.spi.IBMCMSProvider
security.provider.3=com.ibm.crypto.provider.IBMJCE
A sample java.security file can be found in GSKit_Installation_path/classes/gsk_java.security.
- (Optional) If you are a JSSE user and use JSSE to access crypto hardware,
install the ibmpkcs11.jar in the JAVA_HOME/jre/lib directory and follow the instructions in GSKit_Installation_path/classes/native/native-support.zip to setup the crypto hardware
shared libraries.
Note:
You could also find ibmpkcs11.jar in the
JSSE package released after August 5, 2002. To register an IBMPKCS11 service
provider, an example that updates the JAVA_HOME/jre/lib/security/java.security
file is the following:
security.provider.1=sun.security.provider.Sun
security.provider.2=com.ibm.crypto.provider.IBMJCE
security.provider.3=com.ibm.crypto.pkcs11.provider.IBMPKCS11
Starting the key manager
Start the key manager graphical user interface as follows:
- On Linux and UNIX platforms, enter gsk7ikm at a command
prompt.
- On Windows platforms, click Start -> Programs -> IBM
WebSphere -> Edge Components -> Caching Proxy -> Start Key
Management Utility.
Note that if you create a new key database file during this session,
the file is stored in the directory from which you started the key manager.
Creating a new key database, password, and stash file
A key database is a file that the server uses to store one or more key
pairs and certificates. You can use one key database for all your key pairs
and certificates, or create multiple databases. The key management utility
is used to create new key databases and specify their passwords and stash
files.
To create a key database and stash file:
- Start the key management utility.
- From the main menu, select Key Database File -> New.
- In the New dialog box, make sure that the file type CMS Key Database is selected. Type your key database name
and file location or accept the default, key.kdb. Click OK.
- In the Password Prompt dialog box, type and confirm
the password for this database. Click OK.
- Select the check box to stash the password file. When prompted, type and
confirm a password for verification. The following message is displayed: DB-Type: CMS key database file keyfile_database_name
Note:
If you do not stash the password file, the server starts but does
not listen on port 443.
The password that you specify when you create a new key database protects
the private key. The private key is the only key that can sign documents or
decrypt messages encrypted with the public key.
Use the following guidelines when specifying the password:
- The password must be composed from the U.S. English character set.
- The password must be at least six characters in length and contain at
least two nonconsecutive numbers. Make sure that the password does not consist
of publicly obtainable information about you, such as your name or your immediate
family's names, initials, or birth dates.
- Stash the password.
It is a good practice to change the key database password frequently.
However, if you specify an expiration date for the password, keep a record
of when to change it. If the password expires before you change it, a message
is written to the error log and the server starts, but it cannot make secure
network connections.
Follow these steps to change the key database password:
- From the main menu, click Key Database File -> Open.
- In the Open dialog box, type your key database name
or accept the default, key.kdb. Click OK.
- In the Password Prompt dialog box, type your established
password and click OK.
- From the main menu, click Key Database File -> Change
Password.
- In the Change Password dialog box, type and confirm
a new password. Click OK.
For an SSL connection between a proxy and an LDAP server, put
the key database password in the pac_keyring.pwd file. (Note that the pac_keyring.pwd
file is not the stash file generated by IKeyMan.)
Creating a new key pair and certificate request
The key database stores key pairs and certificate requests. To create a
public-private key pair and certificate request, follow these steps:
- If you have not created the key database, follow the instructions in Creating a new key database, password, and stash file.
- In the key management utility, from the main menu, click Key Database -> File -> Open.
- In the Open dialog box, type your key database name
(or click key.kdb if you are using the default). Click OK.
- In the Password Prompt dialog box, type your password
and click OK.
- From the main menu, click Create -> New Certificate
Request.
- In the New Key and Certificate Request dialog box,
specify the following:
- Key Label: Type a name (label) that is used to identify
the key and certificate in the database: for example, my self-signed
certificate or www.companyA.com.
- Keysize: Size of the key, for example, 1024. (In order to take advantage of 128 bit encryption, a Keysize of
1024 is recommended.)
- Organization Name: Name of the organization to associate
with the key, for example, Company A.
- Organization Unit (Optional)
- Locality (Optional)
- State/Province (Optional)
- Zipcode (Optional)
- Country: Your country code. You must specify at
least two characters, for example, US.
- Certificate request file name: A name for the request
file. Optionally, a default name can be used.
- Click OK. A confirmation message is displayed:
A new certificate request has been successfully created
in the file keyfile_database_name.
- Click OK. Expect the label name that you entered
to be displayed under the Personal Certificate Requests heading.
- In the Information dialog box, click OK. You are reminded to send the file to a certificate authority.
- Unless you have created a self-signed certificate (see the following section,
"Creating a self-signed certificate," for details), send the certificate request
to a CA:
- Leave the key manager running.
- Start a Web browser and enter the URL of the CA from which you want to
obtain the certificate.
- Follow the instructions provided by the CA to send your certificate request.
Certificate requests can take two to three weeks to be fulfilled. While
you are waiting for the CA to process your certificate request, you can act
as your own CA and use iKeyman to create a self-signed server certificate
to enable SSL sessions between clients and your Caching Proxy server.
Creating a self-signed certificate
Use the key management utility to create a self-signed server certificate
to enable SSL sessions between clients and your proxy server while waiting
for a certificate to be issued. You also can use self-signed certificates
for testing purposes.
Follow this procedure to create a self-signed certificate:
- If you have not created the key database, follow the instructions in Creating a new key database, password, and stash file.
- In the key management utility, from the main menu, click Key Database -> File -> Open.
- In the Open dialog box, type your key database name
(or accept the default, key.kdb). Click OK.
- In the Password Prompt dialog box, type your password
and click OK.
- In the Key Database content frame, select Personal Certificates and click Create New Self-Signed
Certificate.
- In the Create New Self-Signed Certificate window,
specify the following:
- Key Label: A name (label) that is used to identify
the key and certificate in the database: for example, my self-signed
certificate
- Key Size: Size of the key, for example, 512.
- Common Name: The full host name of the server, for
example, www.myserver.com
- Organization Name: Name of the organization to associate
with the key, for example Company A
- Organization Unit (Optional)
- Locality (Optional)
- State/Province (Optional)
- Zipcode (Optional)
- Country: Your country code. You must specify at
least two characters, for example, US.
- Validity Period: The period of time that the certificate
is valid.
- Click OK.
- Register the key database with the server by adding the key file and
stash file to the configuration settings (see Creating a new key database, password, and stash file).
Exporting keys
Use this procedure to export keys to another key database:
- Start the key management utility.
- From the main menu, click Key Database File -> Open.
- In the Open dialog box, type your key database name
(or accept the default, key.kdb). Click OK.
- In the Password Prompt dialog box, type your password
and click OK.
- In the Key Database content frame, select Personal Certificates, then click the Export/Import button on the label.
- In the Export/Import Key window:
- Select Export Key.
- Select the target database type (for example, PKCS12).
- Type the file name or click Browse to select it.
- Type the correct location.
- Click OK.
- In the Password Prompt dialog box, type the correct
password, type the password again to confirm, then click OK to export the selected key to another key database.
Importing keys
To import keys from another key database:
- Start the key management utility.
- From the main menu, select Key Database File -> Open.
- In the Open dialog box, type your key database name
(or accept the default, key.kdb). Click OK.
- In the Password Prompt dialog box, type your correct
password and click OK.
- In the Key Database content frame, select Personal Certificates, then click the Export/Import button on the label.
- In the Export/Import Key window:
- Select Import Key.
- Select the key database file type (for example, PKCS12).
- Type the file name or click Browse to select it.
- Select the correct location.
- Click OK.
- In the Password Prompt dialog box, type the correct
password and click OK.
- In the Select from Key Label list, select the correct
label name and click OK.
Listing certificate authorities
To display a list of trusted certificate authorities (CAs) in a key database:
- Start the key management utility.
- From the main menu, click Key Database File -> Open.
- In the Open dialog box, type your key database name
(or accept the default, key.kdb). Click OK.
- In the Password Prompt dialog box, type your correct
password and click OK.
- In the Key Database content frame, select Signer Certificates.
- Click Signer Certificates, Personal
Certificates, or Certificate Requests to view the
list of CAs in the Key Information window.
Receiving a CA certificate
Use this procedure to receive a certificate that is electronically mailed
to you from a certificate authority (CA) that is designated as a trusted CA
by default (see the list in Certificate authorities). If the CA that issues
your CA-signed certificate is not a trusted CA in the key database, you must
first store the CA's certificate and designate the CA as a trusted CA. Then
you can receive your CA-signed certificate into the database. You cannot receive
a CA-signed certificate from a CA that is not a trusted CA (see Storing a CA certificate).
To receive a CA-signed certificate into a key database:
- Start the key management utility.
- From the main menu, select Key Database File -> Open.
- In the Open dialog box, type your key database name
(or accept the default, key.kdb). Click OK.
- In the Password Prompt dialog box, type your password
and click OK.
- Ensure that the file name in the DB-Type listing
is correct.
- In the Key Database window, select Personal Certificates, then click Receive.
- In the Receive Certificate from a File dialog box,
type the name of a valid base 64-encoded file in the Certificate
filename text field. Click OK.
- To close the key manager utility, from the main menu, click Key Database File -> Exit.
Storing a CA certificate
Only certificates signed by trusted CAs are accepted for establishing secure
connections. To add a CA to the list of trusted authorities, you must obtain
and store its certificate as trusted. Follow this procedure to store a certificate
from a new CA, prior to receiving it into the database:
- Start the key management utility.
- From the main menu, click Key Database File -> Open.
- In the Open dialog box, type your key database name
(or accept the default, key.kdb). Click OK.
- In the Password Prompt dialog box, type your password
and click OK.
- In the Key Database content frame, select Signer Certificates, then click Add.
- In the Add CA's Certificate from a File dialog box,
select the base 64-encoded ASCII data certificate file name, or use the Browse option. Click OK.
- In the Label dialog box, type a label name and click OK.
- Use the check box to designate the certificate as trusted (default).
Note:
View the check box after the certificate
is created by using the "View/Edit" button. The check box is listed on the
panel but it is not displayed during the adding of the certificate.
Displaying the default key in a key database
Display the default key entry as follows:
- Start the key management utility.
- From the main menu, click Key Database File -> Open.
- In the Open dialog box, type your key database name
(or accept the default, key.kdb). Click OK.
- In the Password Prompt dialog box, type your password
and click OK.
- In the Key Database content frame, select Personal Certificates and select the CA certificate label name.
- In the Key Information window, click View/Edit to display the certificate default key information.