Use the Key Management Utility (IKEYMAN): IBM HTTP Server
System Administration IBM HTTP Server documentation

Using the Key Management Utility (IKEYMAN)


Before you begin

To have a secure network connection, create a key for secure network communications and receive a certificate from a certificate authority (CA), designated as a trusted CA on your server. Use IKEYMAN to create key databases, public-private key pairs and certificate requests. If you are acting as your own CA, you can use IKEYMAN to create self-signed certificates. If you act as your own CA for a private Web network, you have the option to use the server CA utility to generate and issue signed certificates to clients and servers in your private network.

Use IKEYMAN for configuration tasks related to public-private key creation and management. You cannot use IKEYMAN for configuration options that update the server configuration file, httpd.conf. For options that update the server configuration file, you must use the IBM Administration Server.

Applies to Linux for S/390

Linux for S/390 users: Use the IKEYCMD Command Line Interface to perform similar functions to IKEYMAN.

See Using the IKEYCMD Command Line Interface for more detailed information regarding IKEYCMD.

 

Review Security Configuration Examples

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

Set up your System Environment

The IKEYMAN GUI is Java-based and needs a JDK or JRE to run. The minimum JDK levels for IKEYMAN support are:  

Applies to AIX 1.1.6+ or 1.1.8
Applies to Windows 1.1.8
Applies to HP Applies to Solaris Applies to Linux 1.1.7      
 
Applies to HP Applies to Linux Applies to Solaris Applies to Windows

On Windows and Solaris, the GSKit libraries installed as part of the SSL component include a JRE. No additional environment setup is required on these platforms. To run on AIX, HP, or Linux, or to use another JDK on Solaris, set your system environment using the following guidelines:

  • Set the variables for using the JDK. These variables vary, depending on the JDK version and should be verified by reading the documentation included with the JDK.
    • For JDK Version 1.1.x, set the JAVA_HOME variable:
                EXPORT JAVA_HOME=the JDK home directory full path name
      
    • For JDK Version 1.2.x, update the PATH variable:
      	  EXPORT PATH = <the JDK home directory full path name>
      	  /jre/sh:<the JDK home directory full path name>/sh:$PATH
      
  • If you want the ability to run IKEYMAN from any directory, add the path where IKEYMAN installs to your PATH environment variable:
    	  EXPORT PATH=$IKEYMAN_HOME/bin:$PATH
    

Applies to Linux for S/390

Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information regarding IKEYCMD.

To run IKEYMAN on Linux for S/390, set up environment variables to use the IKEYCMD command line interface as follows:
  1. Set your PATH to where your Java or JRE executable resides:
    	  EXPORT PATH=/opt/IBMJava/bin:$PATH
    
  2. Set the following CLASSPATH environment variable:
    	  EXPORT CLASSPATH=/usr/local/ibm/gsk/classes/cfwk.zip:/usr/local/IBM/
    		gsk/classes/gsk4cls.jar:$CLASSPATH
    

Once completed, IKEYCMD should run from any directory. To run an IKEYCMD command, use the following syntax:

	  java com.ibm.gsk.ikeyman.ikeycmd <command>
Note: You can substitute JRE for Java, depending on whether you are using a JRE or JDK. Example:
jre com.ibm.gsk.ikeyman.ikeycmd <command>

Each IKEYCMD (except create database) requires that the key database and password for the key database be specified. This is a required action since the database is opened with each command. See Using the IKEYCMD Command Line Interface, for more detailed information on IKEYCMD.

Using the IKEYMAN Graphical User Interface

The following section describes how to get started and use IKEYMAN or the IKEYCMD Command Line Interface.

Starting IKEYMAN

To start the IKEYMAN graphical user interface:

 
Applies to AIX Applies to Linux Applies to Solaris Type ikeyman on the command line.
Applies to Windows Go to the start UI and select Start Key Management Utility.
 

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

Using IKEYMAN or the IKEYCMD Command Line Interface

To have a secure network connection, create a key for secure network communications and receive a certificate from a certificate authority (CA), designated as a trusted CA on your server. Use IKEYMAN (or IKEYCMD on Linux for S/390) to create the key database file, public-private key pair and certificate request. After you receive the CA-signed certificate, use IKEYMAN (or IKEYCMD on Linux for S/390) to receive the certificate into the key database where you created the original certificate request.

This section provides a quick reference of IKEYMAN and IKEYCMD tasks and common task descriptions.

User interface task reference

IKEYMAN user interface and IKEYCMD command line interface tasks are summarized in the following table.  


IKEYMAN and IKEYCMD 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 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:

Applies to UNIX Applies to Windows NT
  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 UI, 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 to confirm the password. Click OK.

Applies to Linux for S/390

Linux for S/390 users:

See Using the IKEYCMD Command Line Interface for more detailed information regarding IKEYCMD. A password is required for each key database operation. Even though a database of the type sslight requires a specified password,the password can be a NULL string (specified as ""). To create a new key database using the IKEYCMD command line interface, enter the following command:
Java com.ibm.gsk.ikeyman.ikeycmd -keydb -create -db <filename>.kdb -pw <password>
 -type cms -expire <days> -stash

where:
-type: IBM HTTP Server only handles a CMS key database.
-expire: Days before password expires.
-stash: Stashes password for key database. Stashing the password is required for the IBM HTTP Server.

When the -stash option is specified during the key database creation, the password is stashed in a file with a filename built as follows:

	   <filename of key database>.sth
For example, if the database being created is named keydb.kdb, the stash filename is keydb.sth.

Setting the Database Password

When you create a new key database, you specify a key database password. This password protects the private key. The private key is the only key that can sign documents or decrypt messages encrypted with the public key. Changing the key database password frequently is a good practice.

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 does not consist of publicly obtainable information about you, such as the initials and birth date for you, your spouse, or children.
  • Stash the password.
Note: Keep track of expiration dates for the password. If the password expires, a message is written to the error log. The server will start, but there is not 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 UI, 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 UI, then select Change Password.
  6. In the Change Password dialog box, enter a new password and a new confirming password. Click OK.

Applies to Linux for S/390 Linux for S/390 users: See Using the IKEYCMD Command Line Interface, for more detailed information on IKEYCMD.
To change the database password, type:
Java com.ibm.gsk.ikeyman.ikeycmd -keydb -changepw dB <filename> .kdb -pw <password> -new_pw
<new_password> -expire <days> -stash

where:
-new_pw: New key database password; this password must be different than the old password
-expire: Days before password expires.
-stash: Stashes password for key database. Stashing the password is required for the IBM HTTP Server.

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.

Applies to Windows NT Applies to UNIX

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.
  3. Select Key Database File, from the main UI, 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 UI, then select New Certificate Request.
  7. In the New Key and Certficate Request dialog box, enter:
    • Key Label: Enter a descriptive comment to identify the key and certificate in the database.
    • Keysize
    • Organization Name
    • Organization Unit (Optional)
    • Locality (Optional)
    • State/Province (Optional)
    • Zipcode (Optional)
    • Country: Enter a country code. Specify at least two characters. Example: US
    • Certificate request file name, or use the default name
  8. Click OK.
  9. In the Information dialog box, click OK. You are reminded to send the file to a certificate authority.

Applies to Linux for S/390

Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information about IKEYCMD.

To create a public-private key pair and certificate request:
  1. Enter the following command:
    Java com.ibm.gsk.ikeyman.ikeycmd -certreq -create dB <dB_name>.kdb -pw 
    <password> -size <1024 | 512> -dn<distinguished_name>
    -file <filename> -label <label>
    
    where:
    -size: Key size of 512 or 1024
    -label: Label attached to certificate or certificate request
    -dn: X.500 distinguished name. This is input as a quoted string of the following format (Only CN, O, and C are required) CN=common_name, O=organization, OU=organization_unit, L=location, ST=state/province, C=country.
    Example:
    "CN=weblinux.raleigh.ibm.com,O=IBM,OU=IBM HTTP Server,L=RTP,ST=NC,C=US"

    -file: Name of file where the certificate request will be stored.
  2. Verify that the certificate was successfully created.
    1. View the contents of the certificate request file you created.
    2. Make sure the key database recorded the certificate request:
      Java com.ibm.gsk.ikeyman.ikeycmd -certreq -list dB <filename> 
      -pw <password>
      
      You should see the label listed that you just created.
  3. Send the newly created 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 an issued certificate, use IKEYMAN to create a self-signed server certificate to enable SSL sessions between clients and the server. Use this procedure if you are acting as your own CA for a private Web network.

Applies to Windows NT Applies to UNIX

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 UI, 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 clickOK.
  6. Select Personal Certificates in the Key Database content frame, and click the New Self-Signed button.
  7. In the Create New Self-Signed Certificate dialog box, enter:
    • Key Label: Enter a descriptive comment used to identify the key and certificate in the database.
    • Key Size
    • Common Name: Enter the fully qualified host name of the Web server as the common name. Example: www.myserver.com.
    • Organization Name
    • Organization Unit (Optional)
    • Locality (Optional)
    • State/Province (Optional)
    • Zipcode (Optional)
    • Country: Enter a country code. Specify at least two characters. Example:US
    • Validity Period
  8. Click OK.
Applies to Linux for S/390

Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information about IKEYCMD.

To create a self-signed certificate:
Enter the following command:
Java com.ibm.gsk.ikeyman.ikeycmd -cert -create dB <dB_name>.kdb -pw <password>
-size <1024 | 512> -dn<distinguished name> -label <label> -default_cert 
<yes or no>
where:
-size: Key size 512 or 1024
-label: Enter a descriptive comment used to identify the key and certificate in the database.
-dn: Enter an X.500 distinguished name. This is input as a quoted string of the following format (Only CN, O, and C are required): CN=common_name, O=organization, OU=organization_unit, L=location, ST=state, province, C=country
Example:
"CN=weblinux.raleigh.ibm.com,O=IBM,OU=IBM HTTP Server,L=RTP,ST=NC,C=US"

-default_cert: Enter yes, if you want this certificate to be the default certificate in the key database. Enter no, if not.

Applies to Windows NT Applies to UNIX

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 UI, then select Open.
    3. In the Open dialog box, enter your key database name or click key.kdb if 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 UI, then select Open.
    3. In the Open 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 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 KeyM
      • 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.
Applies to Linux for S/390

Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information about IKEYCMD.

Applies to UNIX Applies to Windows

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 UI, then select Open.
    3. In the Open dialog box, enter your key database name, or click key.kdb, if 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.
Applies to UNIX Applies to Windows

  • 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 UI, then select Open.
    3. In the Open dialog box, enter your key database name or click key.kdb, if 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.
    Applies to Linux for S/390

    Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information about IKEYCMD.

    Applies to UNIX Applies to Windows

    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 UI, 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.
    Applies to Linux for S/390

    Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information about IKEYCMD.

    To display a list of trusted CAs in a key database:
    Java com.ibm.gsk.ikeyman.ikeycmd -cert -list CA dB <dbname>.kdb -pw <password>
    -type CMS
    

    Applies to UNIX Applies to Windows

    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 UI, then select Open.
    3. In the Open 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 and click OK.
    5. The key database name appears in the File Name text box.
    Applies to Linux for S/390

    Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information about IKEYCMD.

    There is no explicit opening of a key database. For each command, database and password options are specified and these specifications provide the information needed to operate in a key database.

    Receiving a CA-Signed Certificate

    Use this procedure to receive an electronically mailed certificate from a certificate authority (CA), 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:

    • RSA Secure Server Certification Authority (from VeriSign)
    • Thawte Personal Basic CA
    • Thawte Personal Freemail CA
    • Thawte Personal Premium CA
    • Thawte Premium Server CA
    • Thawte Server CA
    • Verisign Class 1 CA Individual-Persona Not Validated
    • Verisign Class 2 CA Individual-Persona Not Validated
    • Verisign Class 3 CA Individual-Persona Not Validated
    • VeriSign Class 1 Public Primary Certification Authority
    • VeriSign Class 2 Public Primary Certification Authority
    • VeriSign Class 3 Public Primary Certification Authority
    • VeriSign Test CA Root Certificate

    The Certificate Authority may send more than one 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 sending a Global Server ID certificate. Before receiving the server certificate, receive any additional Intermediate CA certificates. Follow the instructions in Storing a CA 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 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 certificate.

    Applies to UNIX Applies to Windows

    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 UI, then select Open.
    3. In the Open 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 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.
    Applies to Linux for S/390

    Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information about IKEYCMD.

    To receive the CA-signed certificate into a key database, enter the following command:
    Java com.ibm.gsk.ikeyman.ikeycmd -cert -receive -file <filename> dB <dB_name>
    .kdb -pw <password> -format <ascii | binary> -default_cert <yes | no>
    

    where:
    -format: Certificate Authority might provide CA Certificate in either ASCII or binary format
    -label: Label attached to CA certificate.
    -trust: Indicates whether this CA can be trusted. Use enable options when receiving a CA certificate.
    -file: File containing the CA certificate.

    Applies to UNIX Applies to Windows

    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 UI, then select Open.
    3. In the Open 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 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.
    Applies to Linux for S/390

    Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information on IKEYCMD.

    To display the default key entry:
    Java com.ibm.gsk.ikeyman.ikeycmd -cert -getdefault dB <dbname>.kdb -pw <password>
    

    Applies to UNIX Applies to Windows

    Storing a CA 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 UI, then select Open.
    3. In the Open 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 and click OK.
    5. Select Signer Certificates in the Key Database content frame, then click the Add button.
    6. In the Add CA 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.
    Applies to Linux for S/390

    Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information on IKEYCMD.

    To store a certificate from a CA who is not a trusted CA:
    Java com.ibm.gsk.ikeyman.ikeycmd -cert -add dB <filename>.kdb -pw <password>
    -label <label> -format <ASCII | binary> -trust <enable |disable> -file
    <file>
    
    where:
    -label: Label attached to certificate or certificate request
    -format: Certificate Authorities might supply a binary ASCII file
    -trust: Indicate whether this CA can be trusted. Should be Yes.

    Applies to UNIX Applies to Windows

    Storing the Encrypted Database Password in a stash file

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

    To store the password while a database is 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 UI, then select Open.
    3. In the New dialog box, enter your key database name, or click key.kdb if using the default. Click OK.
    4. In the Password Prompt dialog box, enter your correct password, then enter to confirm your 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.
    Applies to Linux for S/390

    Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information on IKEYCMD.

    To store the password while a database is created:
    Java com.ibm.gsk.ikeyman.ikeycmd -keydb -create dB <path_to_dB>/<dB_name>.kdb
    -pw <password> -type CMS -expire <days> -stash
    

    Applies to UNIX Applies to Windows

    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 UI, 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.
    Applies to Linux for S/390

    Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information on IKEYCMD.

    To store the password after a database has been created:
    Java com.ibm.gsk.ikeyman.ikeycmd -keydb -stashpw dB <dB_name>.kdb -pw <password>
    

    Applies to Linux for S/390

    On Linux for S/390: Using the IKEYCMD Command Line Interface

    On Linux for S/390, IKEYCMD, the Java command line interface to IKEYMAN, provides the necessary options to create and manage keys, certificates and certificate requests. If you are acting as your own CA, you can use IKEYCMD to create self-signed certificates. If you act as your own CA for a private Web network, you have the option to use the server CA utility to generate and issue signed certificates to clients and servers in your private network.

    Use IKEYCMD for configuration tasks related to public-private key creation and management. You cannot use IKEYCMD for configuration options that update the server configuration file, httpd.conf. For options that update the server configuration file, you must use the IBM Administration Server.

    IKEYCMD uses Java and native command line invocation, enabling IKEYMAN task scripting.

    IKEYCMD Command Line Syntax

    The syntax of the Java CLI is:

     	Java [-Dikeycmd.properties=<properties_file>] com.ibm.gsk.ikeyman.ikeycmd 
    		<object> <action> [options]
    

    where:

    -Dikeycmd.properties
    Specifies the name of an optional properties file to use for this Java invocation. A default properties file, ikeycmd.properties, is provided as a sample file that can be modified and used by any Java application.

    Object is one of the following:

    -keydb
    Actions taken on the key database (either a CMS key database file, a WebDB keyring file, or SSLight class)

    -cert
    Actions taken on a certificate

    -certreq
    Actions taken on a certificate request

    -help
    Display help for the IKEYCMD invocations

    -version
    Display version information for IKEYCMD

    Action is the specific action to be taken on the object, and options are the options, both required and optional, specified for the object and action pair.

    NOTE: The object and action keywords are positional and must be specified in the selected order. However, options are not positional and can be specified in any order, provided that they are specified as an option and operand pair.

    IKEYCMD Command Line Parameter Overview

    The following table describes each action that can be performed on a specified object.

    Object Actions Description
    -keydb -changepw Change the password for a key database
    -convert Convert the key database from one format to another
    -create Create a key database
    -delete Delete the key database
    -stashpw Stash the password of a key database into a file
    -cert -add Add a CA certificate from a file into a key database
    -create Create a self-signed certificate
    -delete Delete a CA certificate
    -details List the detailed information for a specific certificate
    -export Export a personal certificate and its associated private key from a key database into a PKCS#12 file, or to another key database
    -extract Extract a certificate from a key database
    -getdefault Get the default personal certificate
    -import Import a certificate from a key database or PKCS#12 file
    -list List all certificates
    -modify Modify a certificate (NOTE: Currently, the only field that can be modified is the Certificate Trust field)
    -receive Receive a certificate from a file into a key database
    -setdefault Set the default personal certificate
    -sign Sign a certificate stored in a file with a certificate stored in a key database and store the resulting signed certificate in a file
    -certreq -create Create a certificate request
    -delete Delete a certificate request from a certificate request database
    -details List the detailed information of a specific certificate request
    -extract Extract a certificate request from a certificate request database into a file
    -list List all certificate requsts in the certificate request database
    -recreate Recreate a certificate request
    -help Display help information for the IKEYCMD command
    -version Display IKEYCMD version information

    IKEYCMD Command Line Options Overview

    The following table shows each option that can be present on the command line. The options are listed as a complete group. However, their use is dependent on the object and action specified on the command line.


    Option Description
    dB Fully qualified path name of a key database.
    -default_cert Sets a certificate to be used as the default certificate for client authentication (yes or no). Default is no.
    -dn X.500 distinguished name. Input as a quoted string of the following format (only CN, O, and C are required):
    "CN=Jane Doe,O=IBM,OU=Java Development,L=Endicott,
    ST=NY,ZIP=13760,C=country"
    

    -encryption Strength of encryption used in certificate export command (strong or weak). Default is strong.
    -expire Expiration time of either a certificate or a database password (in days). Defaults are: 365 days for a certificate and 60 days for a database password.
    -file File name of a certificate or certificate request (depending on specified object).
    -format Format of a certificate (either ASCII for Base64_encoded ASCII or binary for Binary DER data). Default is ASCII
    -label Label attached to a certificate or certificate request.
    -new_format New format of key database.
    -new_pw New database password.
    -old_format Old format of key database.
    -pw Password for the key database or PKCS#12 file. See Creating a new key database.
    -size Key size (512 or 1024). Default is 1024.
    -stash Indicator to stash the key database password to a file. If specified, the password will be stashed in a file.
    -target Destination file or database.
    -target_pw Password for the key database if -target specifies a key database.See Creating a new key database.
    -target_type Type of database specified by -target operand (see -type).
    -trust Trust status of a CA certificate (enable or disable). Default is enable.
    -type Type of database. Allowable values are CMS (indicates a CMS key database), webdb (indicates a keyring), sslight (indicates an SSLight .class), or pkcs12 (indicates a PKCS#12 file).
    -x509version Version of X.509 certificate to create (1, 2 or 3). Default is 3.

    Command Line Invocation

    The following is a list of each of the command line invocations, with the optional parameters specified in italics.

    Note: For simplicity, the actual Java invocation, Java com.ibm.gsk.ikeyman,iKeycmd, is omitted from each of the command invocations.

    -keydb -changepw dB <filename> -pw <password> -new_pw <new_password> -stash
    	-expire <days> 
    -keydb -convert dB <filename> -pw <password> -old_format <CMS | webdb> 
    	-new_format <CMS> 
    -keydb -create dB <filename> -pw <password> -type <CMS | sslight> -expire 
    	<days> -stash 
    -keydb -delete dB <filename> -pw <password>
    -keydb -stashpw dB <filename> -pw <password>
    

    -cert -add dB <filename> -pw <password> -label <label> -file <filename> -format
    	 <ASCII | binary> -trust <enable | disable> 
    -cert -create dB <filename> -pw <password> -label <label> -dn <distinguished_name> 
    	-size <1024 | 512> -x509version <3  | 1 | 2> -default_cert <no | yes>
    -cert -delete dB <filename> -pw <password> -label <label>
    -cert -details dB <filename> -pw <password> -label <label>
    -cert -export dB <filename> -pw <password> -label <label> -type <CMS | sslight>
    	-target <filename> -target_pw <password> -target_type <CMS | sslight | pkcs12> 
    	-encryption <strong | weak> 
    -cert -extract dB <filename> -pw <password> -label <label> -target <filename> 
    	-format <ASCII | binary> 
    -cert -getdefault dB <filename> -pw <password>
    -cert -import dB <filename> -pw <password> -label <label> -type <CMS | sslight> 
    	-target <filename> -target_pw <password> -target_type <CMS | sslight>
    -cert -import -file <filename> -type <pkcs12> -target <filename> -target_pw <password> 
    	-target_type <CMS | sslight> 
    -cert -list <all | personal | CA | site> dB <filename> -pw <password> -type 
    	<CMS | sslight>
    -cert -modify dB <filename> -pw <password> -label <label>  -trust <enable | disable>
    -cert -receive -file <filename> dB <filename> -pw <password> -format <ASCII | binary> 
    	-default _cert <no | yes> 
    -cert -setdefault dB <filename> -pw <password> -label <label>
    -cert -sign -file <filename> dB <filename> -pw <password> -label <label> -target <filename> 
    	-format <ASCII | binary>  -expire <days> 
    

    -certreq -create dB <filename> -pw <password> -label <label> -dn <distinguished_name>
    	-size <1024 | 512> -file <filename>
    -certreq -delete dB <filename> -pw <password> -label <label>
    -certreq -details dB <filename> -pw <password> -label <label>
    -certreq -extract dB <filename> -pw <password> -label <label> -target <filename>
    -certreq -list dB <filename> -pw <password>
    -certreq -recreate dB <filename> -pw <password> -label <label> -target <filename>
    

    -help
    

    -version
    

    User Properties File

    In order to eliminate some of the typing on the Java CLI invocations, user properties can be specified in a properties file. The properties file can be specified on the Java command line invocation via the -Dikeycmd.properties Java option. A sample properties file, ikeycmd.properties, is supplied as a sample to enable Java applications to modify default settings for their application.

     
    Related information...

         (Back to Top)