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.
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.
This appendix 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.
The IKEYMAN GUI is Java-based and needs a JDK or JRE to run. The minimum JDK levels for IKEYMAN support are:
On Windows and Solaris, the GSKit libraries installed as part of the SSL component include a JRE. No additional environment set up 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:
EXPORT JAVA_HOME=the JDK home directory full path name
EXPORT PATH = <the JDK home directory full path name> /jre/sh:<the JDK home directory full path name>/sh:$PATH
EXPORT PATH=$IKEYMAN_HOME/bin:$PATH
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:
EXPORT PATH=/opt/IBMJava/bin:$PATH
EXPORT CLASSPATH=/usr/local/ibm/gsk/classes/cfwk.zip:/usr/local/ibm/ gsk/classes/gsk4cls.jar:$CLASSPATH
and run the following java command:
java com.ibm.gsk.ikeyman.ikeycmd <command>
Once completed, IKEYCMD should run from any directory.
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.
The following section describes how to get started and use IKEYMAN or the IKEYCMD Command Line Interface.
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.
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.
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 |
|
Create a new key pair and certificate request |
|
Create a self-signed certificate |
|
Export a key to another database or PKCS12 file |
|
Import a key from another database or PKCS12 file |
|
List certificate authorities (CAs) and certificate requests |
|
Open a key database |
|
Receive a CA-signed certificate into a key database |
|
Show the default key in a key database |
|
Store the root certificate of a CA |
|
Store the encrypted database password in a 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.
To create a new key database:
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
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>.sthFor example, if the database being created is named keydb.kdb, the stash filename is keydb.sth.
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:
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 will not be a secure network connection if the password has expired. |
To change the database password:
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
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.
Key pairs and certificate requests are stored in a key database. To create a public-private key pair and certificate request:
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:
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:
"CN=weblinux.raleigh.ibm.com,O=ibm,OU=IBM HTTP Server,L=RTP,SP=NC,C=US"
java com.ibm.gsk.ikeyman.ikeycmd -certreq -list -db <filename> -pw <password>You should see the label listed that you just created.
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.
To create a self-signed certificate:
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:
"CN=weblinux.raleigh.ibm.com,O=ibm,OU=IBM HTTP Server,L=RTP,SP=NC,C=US"
Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information about IKEYCMD.
Linux for S/390 users: See Using the IKEYCMD Command Line Interface for more detailed information about IKEYCMD.
To display a list of trusted certificate authorities (CAs) in a key database:
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
To open an existing key database:
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.
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:
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.
To receive the CA-signed certificate into a key database:
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>
To display the default key entry:
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>
To store a certificate from a CA who is not a trusted CA:
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:
For a secure network connection, store the encrypted database password in a stash file.
To store the password while a database is created:
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
To store the password after a database has been created:
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>
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.
The syntax of the Java CLI is:
java [-Dikeycmd.properties=<properties_file>] com.ibm.gsk.ikeyman.ikeycmd <object> <action> [options]
where:
-Dikeycmd.properties |
|
Object is one of the following:
-keydb |
|
-cert |
|
-certreq |
|
-help |
|
-version |
|
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.
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
|
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. Input with quotes
around the label entry.
|
-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.
|
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
In order to eliminate some of the typing on the Java CLI invoacations, 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.