Use the key management utility (IKEYMAN)

  • Before you begin
  • Review security configuration examples
  • Set up your system environment
  • Using the IKEYMAN graphical user interface
  • Starting IKEYMAN
  • Using IKEYMAN
  • User interface task reference
  • Creating a new key database
  • Creating a new key pair and certificate request
  • Creating a self-signed certificate
  • Exporting keys
  • Importing keys
  • Listing CAs
  • Opening a key database
  • Receiving a CA-signed certificate
  • Showing the default key in a key database
  • Storing a CA's certificate
  • Storing the encrypted database password in a stash file
  • 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 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:

    Using the IKEYMAN graphical user interface

    Starting IKEYMAN

    To start the IKEYMAN graphical user interface,

    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.

    IKEYMAN task For instructions, go to
    Create a new key database and specify the database password
    "Creating a new key database"

    Create a new key pair and certificate request
    "Creating a new key pair and certificate request"

    Create a self-signed certificate
    "Creating a self-signed certificate"

    Export a key to another database or PKCS12 file
    "Exporting keys"

    Import a key from another database or PKCS12 file
    "Importing keys"

    List certificate authorities (CAs) and certificate requests
    "Listing CAs"

    Open a key database
    "Opening a key database"

    Receive a CA-signed certificate into a key database
    "Receiving a CA-signed certificate"

    Show the default key in a key database
    "Showing the default key in a key database"

    Store the root certificate of a CA
    "Storing a CA's certificate"

    Store the encrypted database password in a stash file
    "Storing the encrypted database password in a stash file"

    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:

    Note:If you specify an expiration date for the password, keep track of when to change it. If the password expires before you change it, a message will be written to the error log. The server will start, but there will not be a secure network connection if the password has expired.

    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:
    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:
    8. Click OK.

    Exporting keys

    Importing keys

    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:

    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.

    Note:If the CA who 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 who is not a trusted CA. For instructions, see Storing a CA's certificate.

    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.