Use the key management utility (IKEYMAN)

Before you begin

Review security configuration examples

This appendix provides detailed information on tasks you can perform using the IBM Key Management Utility (IKEYMAN). It does not explain how to configure security options that require updates to the server configuration file.

Before you begin, we recommend that you review the following examples:

• Set up secure connections using an external CA

  Use this example if you plan to have your operational server certificate signed by an external CA such as VeriSign.

• Set up secure connections using self-signed certificates

Set up your system environment

To run IKEYMAN on Windows, you do not have to set any environment variables. To run on AIX or Solaris, set your system environment using the following guidelines:

• Set the home where the JDK is installed:

  
            EXPORT JAVA_HOME=the JDK home directory full path name
  
  

• If you want the ability to run IKEYMAN from any directory, add the path where IKEYMAN is installed to your PATH environment variable:

  
            EXPORT PATH=$IKEYMAN_HOME/bin:$PATH
  
  

Using the IKEYMAN graphical user interface

Starting IKEYMAN

To start the IKEYMAN graphical user interface,

• On AIX or Solaris, type ikeyman on the command line.
• On Windows, go to the start menu and select Start Key Management Utility.

Note: If you are starting IKEYMAN to create a new key database file, the file will be stored in the directory where you start IKEYMAN.

Using IKEYMAN

You do not have a secure network connection until you have created a key for secure network communications and received a certificate from a certificate authority (CA) who is designated as a trusted CA on your server. Use IKEYMAN to create the key database file, public-private key pair, and certificate request. After you receive the CA-signed certificate, use IKEYMAN to receive the certificate into the key database where you created the original certificate request.

This section provides a quick reference of IKEYMAN tasks and detailed descriptions of the most common tasks.

User interface task reference

The tasks you can perform using the IKEYMAN user interface are summarized in the following table.

Creating a new key database

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.

To create a new key database:

1. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
2. Select Key Database File from the main menu, then select New.
3. In the New dialog box, enter your key database name or click key.kdb if you are using the default. Click OK.
4. In the Password Prompt dialog box, enter your correct password, then enter the confirm password. Click OK.

Setting the database password

When you create a new key database, you specify a key database password. This password is important because it protects the private key. The private key is the only key that can sign documents or decrypt messages encrypted with the public key. It's a good practice to change the key database password frequently.

Use the following guidelines when specifying the password:

• The password must be from the U.S. English character set.
• The password should be at least six characters and contain at least two nonconsecutive numbers. Make sure the password doesn't consist of publicly obtainable information about you, such as the initials and birth date for you, your spouse, or children.
• Stash the password.

Changing the database password

To change the database password:

1. Enter ikeyman on a command line.
2. Select Key Database File from the main menu, then select Open.
3. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
4. In the Password Prompt dialog box, enter your correct password and click OK.
5. Select Key Database File from the main menu, then select Change Password.
6. In the Change Password dialog box, enter a new password and a new confirming password. Click OK.

Registering a key database with the server

The initial configuration setting for the default key database name is key.kdb. If you use key.kdb as your default key database name, you do not need to register the database with the server. The server will use the initial setting on the KeyFile directive in the configuration file. If you do not use key.kdb as your default key database name or if you create additional key databases, you must register those databases.

Creating a new key pair and certificate request

Key pairs and certificate requests are stored in a key database. To create a public-private key pair and certificate request:

1. If you have not created the key database, see Creating a new key database for instructions.
2. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT. e.
3. Select Key Database File from the main menu, then select Open.
4. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
5. In the Password Prompt dialog box, enter your correct password and click OK.
6. Select Create from the main menu, then select New Certificate Request.
7. In the New Key and Certficate Request dialog box, enter:

   • Key Label: Enter a name (label) that is used to identify the key and certificate in the database, for example, my self-signed certificate.
   • Keysize

   • Organization Name

   • Organization Unit (Optional)

   • Locality (Optional)

   • State/Province (Optional)

   • Zipcode (Optional)

   • Country: Enter a country code. You must specify at least 2 characters, for example, US.
   • Certificate request file name, or use the default name
8. Click OK.
9. In the Information dialog box, click OK. You will be reminded to send the file to a certificate authority.

Creating a self-signed certificate

It usually takes two to three weeks to get a certificate from a well-known CA. While waiting for a certificate to be issued, you can use IKEYMAN to create a self-signed server certificate to enable SSL sessions between clients and the server. You also use this procedure if you are acting as your own CA for a private Web network.

To create a self-signed certificate:

1. If you have not created the key database, see Creating a new key database for instructions.
2. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
3. Select Key Database File from the main menu, then select Open.
4. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
5. In the Password Prompt dialog box, enter your correct password and click OK.
6. Select Personal Certificates in the Key Database content frame, click New Self-Signed button.
7. In the Create New Self-Signed Certificate dialog box, enter:

   • Key Label: Enter a name (label) that is used to identify the key and certificate in the database, for example, my self-signed certificate.
   • Key Size
   • Common Name: Enter the fully qualified host name of the server as the common name, for example, www.myserver.com.
   • Organization Name
   • Organization Unit (Optional)
   • Locality (Optional)
   • State/Province (Optional)
   • Zipcode (Optional)
   • Country: Enter a country code. You must specify at least 2 characters, for example, US.
   • Validity Period
8. Click OK.

Exporting keys

• To export keys to another key database:
  1. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
  2. Select Key Database File from the main menu, then select Open.
  3. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
  4. In the Password Prompt dialog box, enter your correct password and click OK.
  5. Select Personal Certificates in the Key Database content frame, then click the Export/Import button on the label.
  6. In the Export/Import Key window:

     • Select Export Key

     • Select the target database type

     • Enter the file name or use the Browse option

     • Enter the correct location
  7. Click OK.
  8. In the Password Prompt dialog box, click OK to export the selected key to another key database.

• To export keys to a PKCS12 file:
  1. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
  2. Select Key Database File from the main menu, then select Open.
  3. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
  4. In the Password Prompt dialog box, enter your correct password and click OK.
  5. Select Personal Certificates in the Key Database content frame, then click the Export/Import button on the label.
  6. In the Export/Import Key window:

     • Select Export Key

     • Select the PKCS12 database file type

     • Enter the file name or use the Browse option

     • Enter the correct location
  7. Click OK.
  8. In the Password Prompt dialog box, enter the correct password, enter the password again to confirm, then click OK to export the selected key to a PKCS12 file.

Importing keys

• To import keys from another key database:
  1. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
  2. Select Key Database File from the main menu, then select Open.
  3. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
  4. In the Password Prompt dialog box, enter your correct password and click OK.
  5. Select Personal Certificates in the Key Database content frame, then click the Export/Import button on the label.
  6. In the Export/Import Key window:

     • Select Import Key

     • Select the key database file type

     • Enter the file name or use the Browse option

     • Select the correct location
  7. Click OK.
  8. In the Password Prompt dialog box, enter the correct password and click OK.
  9. In the Select from Key Label list, select the correct label name and click OK.

• To import keys from a PKCS12 file:
  1. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
  2. Select Key Database File from the main menu, then select Open.
  3. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
  4. In the Password Prompt dialog box, enter your correct password and click OK.
  5. Select Personal Certificates in the Key Database content frame, then click the Export/Import button on the label.
  6. In the Export/Import Key window:

     • Select Import Key

     • Select the PKCS12

     • Enter the file name or use the Browse option

     • Select the correct location
  7. Click OK.
  8. In the Password Prompt dialog box, enter the correct password, then click OK.

Listing CAs

To display a list of trusted certificate authorities (CAs) in a key database:

1. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
2. Select Key Database File from the main menu, then select Open.
3. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
4. In the Password Prompt dialog box, enter your correct password and click OK.
5. Select Signer Certificates in the Key Database content frame.
6. Click Signer Certificates, Personal Certificates, or Certificate Requests, to view the list of CAs in the Key Information window

Opening a key database

To open an existing key database:

1. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
2. Select Key Database File from the main menu, then select Open.
3. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
4. In the Password Prompt dialog box, enter your correct password and click OK.
5. The key database name appears in the File Name text box.

Receiving a CA-signed certificate

Use this procedure to receive a certificate that is electronically mailed to you from a certificate authority (CA) who is designated as a trusted CA on your server. By default, the following CA certificates are stored in the key database and marked as trusted CA certificates:

• IBM World Registry CA
• Integrion CA Root (from IBM World Registry)
• VeriSign Class 1 Public Primary CA
• VeriSign Class 2 Public Primary CA
• VeriSign Class 3 Public Primary CA
• VeriSign Class 4 Public Primary CA
• VeriSign Test CA
• RSA Secure Server CA (from VeriSign)
• Thawte Personal Basic CA
• Thawte Personal Freemail CA
• Thawte Personal Premium CA
• Thawte Premium Server CA
• Thawte Server CA

The Certificate Authority may send more than 1 certificate. In addition to the certificate for your server, the CA may also send additional Signing certificates or Intermediate CA Certificates. For example, Verisign includes an Intermediate CA Certificate when it sends a Global Server ID certificate. Before receiving the server certificate, you will first need to receive any additional Intermediate CA certificates. Follow the instructions in Storing a CA's certificate to receive Intermediate CA Certificates.

To receive the CA-signed certificate into a key database:

1. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
2. Select Key Database File from the main menu, then select Open.
3. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
4. In the Password Prompt dialog box, enter your correct password, then click OK.
5. Select Personal Certificates in the Key Database content frame, then click the Receive button.
6. In the Receive Certificate from a File dialog box, enter the name of a valid Base64-encoded file in the Certificate file name text field. Click OK.

Showing the default key in a key database

To display the default key entry:

1. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
2. Select Key Database File from the main menu, then select Open.
3. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
4. In the Password Prompt dialog box, enter your correct password, then click OK.
5. Select Personal Certificates in the Key Database content frame, and select the CA certificate label name.
6. Click the View/Edit button and view the certificate default key information in the Key Information window.

Storing a CA's certificate

To store a certificate from a CA who is not a trusted CA:

1. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
2. Select Key Database File from the main menu, then select Open.
3. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
4. In the Password Prompt dialog box, enter your correct password and click OK.
5. Select Signer Certificates in the Key Database content frame, then click the Add button.
6. In the Add CA's Certificate from a File dialog box, select the Base64-encoded ASCII data certificate file name, or use the Browse option. Click OK.
7. In the Label dialog box, enter a label name and click OK.

Storing the encrypted database password in a stash file

For a secure network connection, you must store the encrypted database password in a stash file.

To store the password while a database is being created:

1. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
2. Select Key Database File from the main menu, then select Open.
3. In the New dialog box, enter your key database name or click key.kdb if you are using the default. Click OK.
4. In the Password Prompt dialog box, enter your correct password, then enter your confirm password.
5. Check the Stash box and click OK.
6. Select Key Database File then select Stash Password.
7. In the Information dialog box click OK.

To store the password after a database has been created:

1. Enter ikeyman on a command line on Unix or start the Key Management utility in the IBM HTTP Server folder on Windows NT.
2. Select Key Database File from the main menu, then select Open.
3. In the Open dialog box, enter your key database name or click on key.kdb if you are using the default. Click OK.
4. In the Password Prompt dialog box, enter your correct password and click OK.
5. Select Key Database File then select Stash Password.
6. In the Information dialog box click OK.