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:

  1. Install IBM or an IBM-equivalent 32-bit Java 2 Technology, version 1.4.2
  2. Set JAVA_HOME to the Java directory location. For example:
  3. Remove the ibmjsse.jar and the gskikm.jar (if present) and ibmjcaprovider.jar files from your JAVA_HOME/jre/lib/ext directory.
    Notes:
    1. For Solaris, substitute JAVA_HOME/lib/ext/ directory for JAVA_HOME/jre/lib/ext directory.
    2. 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.
  4. All the following jar files are currently in the GSKit_Installation_path/classes/jre/lib/ext/.
  5. 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.

  6. (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:

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:

  1. Start the key management utility.
  2. From the main menu, select Key Database File -> New.
  3. 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.
  4. In the Password Prompt dialog box, type and confirm the password for this database. Click OK.
  5. 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:

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:

  1. From the main menu, click Key Database File -> Open.
  2. In the Open dialog box, type your key database name or accept the default, key.kdb. Click OK.
  3. In the Password Prompt dialog box, type your established password and click OK.
  4. From the main menu, click Key Database File -> Change Password.
  5. 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:

  1. If you have not created the key database, follow the instructions in Creating a new key database, password, and stash file.
  2. In the key management utility, from the main menu, click Key Database -> File -> Open.
  3. In the Open dialog box, type your key database name (or click key.kdb if you are using the default). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. From the main menu, click Create -> New Certificate Request.
  6. In the New Key and Certificate Request dialog box, specify the following:
  7. Click OK. A confirmation message is displayed:
    A new certificate request has been successfully created 
    in the file keyfile_database_name.
  8. Click OK. Expect the label name that you entered to be displayed under the Personal Certificate Requests heading.
  9. In the Information dialog box, click OK. You are reminded to send the file to a certificate authority.
  10. 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: 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:

  1. If you have not created the key database, follow the instructions in Creating a new key database, password, and stash file.
  2. In the key management utility, from the main menu, click Key Database -> File -> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. In the Key Database content frame, select Personal Certificates and click Create New Self-Signed Certificate.
  6. In the Create New Self-Signed Certificate window, specify the following:
  7. Click OK.
  8. 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:

  1. Start the key management utility.
  2. From the main menu, click Key Database File -> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. In the Key Database content frame, select Personal Certificates, then click the Export/Import button on the label.
  6. In the Export/Import Key window:
  7. Click OK.
  8. 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:

  1. Start the key management utility.
  2. From the main menu, select Key Database File -> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your correct password and click OK.
  5. In the Key Database content frame, select Personal Certificates, then click the Export/Import button on the label.
  6. In the Export/Import Key window:
  7. Click OK.
  8. In the Password Prompt dialog box, type the correct password and click OK.
  9. 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:

  1. Start the key management utility.
  2. From the main menu, click Key Database File -> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your correct password and click OK.
  5. In the Key Database content frame, select Signer Certificates.
  6. 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:

  1. Start the key management utility.
  2. From the main menu, select Key Database File -> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. Ensure that the file name in the DB-Type listing is correct.
  6. In the Key Database window, select Personal Certificates, then click Receive.
  7. 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.
  8. 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:

  1. Start the key management utility.
  2. From the main menu, click Key Database File -> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. In the Key Database content frame, select Signer Certificates, then click Add.
  6. 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.
  7. In the Label dialog box, type a label name and click OK.
  8. 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:

  1. Start the key management utility.
  2. From the main menu, click Key Database File -> Open.
  3. In the Open dialog box, type your key database name (or accept the default, key.kdb). Click OK.
  4. In the Password Prompt dialog box, type your password and click OK.
  5. In the Key Database content frame, select Personal Certificates and select the CA certificate label name.
  6. In the Key Information window, click View/Edit to display the certificate default key information.