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

Using the Key Management Utility

This section provides information on planning, preparation and use of the Key Management Utility (IKEYMAN) utility. Links to related topics appear at the end of this section.

Planning to use the Key Management Utility

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 and private key pairs and certificate requests. If you act 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 and 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, use the IBM Administration Server.

Pertains to Linux for S/390 users

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.

 

Reviewing 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.

Setting your system environment

The IKEYMAN GUI is Java-based and needs an IBM Developer Kit for the Java platform, or Java Runtime Environment (JRE) to run. Ensure you have Developer Kit level V1.3 or later for IKEYMAN support.

Set your system environment using the following guidelines:
  • Set the variables for the IBM Developer Kit for the Java platform. These variables vary, depending on the version, You can verify these variables by reading the documentation included with the Developer Kit.
  • Set the JAVA_HOME variable to IBM JDK shipped with WebSphere:
              EXPORT JAVA_HOME=the IBM Developer Kit for the Java platform home directory full path name
    
  • For example, for Linux:
    export JAVA_HOME=/opt/WebSphere/AppServer/java
    
  • Rename and move the $JAVA_HOME/jre/lib/ext/gskikm.jar to a directory that is not visible to the JDK classpath, extdirs, bootclasspath. For example, for Linux:
    mv  $JAVA_HOME/jre/lib/ext/gskikm.jar to /gskfiles/gskikm.jar.org .
    
  • For the IBM Developer Kit for the Java platform, Version 1.3.x, update the PATH variable:
    	  EXPORT PATH = <the IBM Developer Kit for the Java platform home directory full path name>
    	  /jre/sh:<the IBM Developer Kit for the Java platform home directory full path name>/sh:$PATH
    
  • On non-UNIX platforms: 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
    
  • On UNIX platforms: Run <IHS install root>/bin/ikeyman to bring up the IKEYMAN GUI. You cannot invoke IKEYMAN from any directory because the IKEYMAN script that brings up the IKEYMAN GUI is no longer in the /usr/bin directory.

Pertains to Linux for S/390 users

Linux for S/390 users: See Using the IKEYCMD command line interface for more detailed information regarding IKEYCMD.

To run IKEYMAN on the Linux for S/390 operating system, 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 use a JRE executible, or the IBM Developer Kit for the Java platform. Example:
jre com.ibm.gsk.ikeyman.ikeycmd <command>

Each IKEYCMD, except create database, requires that you specify the key database and password for the key database because the database opens with each command. See Using the IKEYCMD command line interface, for more detailed information on IKEYCMD.

Note: If you are unable to open IKEYMAN, do the following:

  1. Rename and move the $JAVA_HOME/jre/lib/ext/gskikm.jar to other directory that is not visible to the JDK classpath,extdirs,bootclasspath, e.g. for Linux: mv $JAVA_HOME/jre/lib/ext/gskikm.jar to /gskfiles/gskikm.jar.org
  2. Set the JAVA_HOME to IBM JDK shipped with WebSphere, e.g. for Linux: export JAVA_HOME=/opt/WebSphere/AppServer/java
  3. Ensure that the C:\Program Files\IBM\Java141\jre\lib\security\java.security file has the following providers for GSKit: security.provider.2=com.ibm.crypto.provider.IBMJCE security.provider.3=com.ibm.spi.IBMCMSProvider If you plan to use cryptographic hardware for GSKit, add the following providers in this order: security.provider.1=com.ibm.spi.IBMCMSProvider security.provider.2=com.ibm.crypto.provider.IBMJCE security.provider.3=com.ibm.jsse.IBMJSSEProvider security.provider.4=com.ibm.crypto.pkcs11.provider.IBMPKCS11
  4. If you are not using an IBM JDK or if the IBM JDK files are older than the GSKit files, copy all the jar files from ibm\gsk7\classes\jre\lib\ext to Java141\jre\lib\ext.

    Using the Key Management Utility graphical user interface

    The following section describes how to get started and use IKEYMAN or the IKEYCMD command line interface.

Starting the Key Management Utility

To start the IKEYMAN graphical user interface:

 
Pertains to Linux users Type <IHS root>/bin/ikeyman on the command line, or change to the <IHS root>/bin directory and type ikeyman on the command line.

If you are using WebSphere Application Server 5.0.2 on Linux PPC, which supports GSKit 7, see Configuration for Linux PPC for configuration you need to perform prior to starting the IKEYMAN graphical user interface.

Go to the start user interface and click Start Key Management Utility.
 

Note: If you start IKEYMAN to create a new key database file, the utility stores the file in the directory where you start IKEYMAN.

Configuration for Linux PPC

If you are using WebSphere Application Server 5.0.2 on Linux PPC, you must do the following configuration before starting the IKEYMAN graphical user interface. However, if you are using the JDK that came with WebSphere to start IKEYMAN on LinuxPPC, these steps may not be necessary:

  1. Set JAVA_HOME to point to the directory where JDK 1.3 was installed. For example:
         Linux PPC:     export JAVA_HOME=/opt/IBMJava2-ppc-131
  2. Remove the gskikm.jar and ibmjcaprovider.jar files from your JAVA_HOME\jre\lib\ext directory.
  3. Make sure JAVA_HOME\jre\lib\ext\ has the following jar files:
         ibmjceprovider.jar
         ibmpkcs.jar
         ibmjcefw.jar
         local_policy.jar
         US_export_policy.jar
    Note: GSKit ships the above jar files and ibmjsse.jar under {GSKit Installation path}\classes\jre\lib\ext for your convenience. If your existing Java 1.3 installation’s JSSE jar files are a higher level than those required by GSKit, no action is required. If your existing Java 1.3 installation’s JSSE jar files are a lower level than those required by GSKit, it is recommended that you replace your old JSSE jar files with the jar files provided with GSKit. Although GSKit IKEYMAN will work with the old JSSE jar files, some IKEYMAN functions may fail due to fixes that may not be included in your JDK installation.
  4. Optional: If you are a JSSE user and use JSSE to access cryptographic hardware, install the ibmjsse.jar in the JAVA_HOME\jre\lib\ext directory and follow the instructions in {GSKit Installation path}/classes/native/native-support.zip to setup the cryptographic hardware DLLs.
  5. Register IBM JCE and IBM CMS service providers. GSKit users need to register

    both IBM CMS and IBM JCE service providers, if not already registered as described below:

    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 You can find a sample java.security file in {GSKit Installation path}\classes\gsk_java.security.
  6. Note: IBM is shipping a Java141\jre\lib\ext\gskism.jar for JRE 1.4.1. This file may cause problems when trying to use IKEYMAN with the CMS provider. The problem is that there is no option ot create or open a CMS .kdb file. To avoid this problem, rename the gskism file to gskikm.jar.org.

Using the Key Management Utility 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 operating systems, to create the key database file, public and private key pair and certificate request. After you receive the CA-signed certificate, use IKEYMAN, or IKEYCMD on Linux for S/390 operating systems, 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.

Referencing user interface tasks

A summarization of the IKEYMAN user interface and IKEYCMD command line interface tasks follow:  


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:

Pertains to UNIX users Pertains to Windows NT users Pertains to Windows 2000 users
  1. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  2. Click key database file from the main UI, then click New.
  3. Enter your key database name in the New dialog box, or click key.kdb if you use the default. Click OK.
  4. Enter your correct password in the Password Prompt dialog box, then enter to confirm the password. Click OK.

Pertains to Linux for S/390 users

Linux for S/390 users:

See Using the IKEYCMD Command Line Interface for more detailed information regarding IKEYCMD. Each key database operation requires a password. Even though a database of the type sslight requires a specified password, you can use a NULL string password, 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 <file name>.kdb -pw <password>
 -type cms -expire <days> -stash

where:
-type: Represents the type of key database. The IBM HTTP Server only handles a CMS key database.
-expire: Represents days before the password expires.
-stash: Indicates password stashing for the key database. Stashing the password is required for the IBM HTTP Server.

When you specify the -stash option during the key database creation, the password stashes in a file with a file name built as follows:

	   <file name of key database>.sth
For example, if the database created is named keydb.kdb, the stash file name 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 come from the U.S. English character set.
  • The password should contain 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 or enable SSL password prompting. See Using SSL Password Prompting.

Note: Keep track of expiration dates for the password. If the password expires, a message writes to the error log. The server starts, but a secure network connection does not exist, if the password has expired.

Changing the database password

To change the database password:

  1. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  2. Click Key Database File from the main UI, then click Open.
  3. Enter your key database name in the Open dialog box, or click the key.kdb file, if you use the default. Click OK.
  4. Enter your password in the Password Prompt dialog box, and click OK.
  5. Click Key Database File from the main UI, then click Change Password.
  6. Enter a new password in the Password Prompt dialog box, and a new confirming password. Click OK.

Pertains to Linux for S/390 users 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 <file name> .kdb -pw <password> -new_pw
<new_password> -expire <days> -stash

where:
-new_pw: Represents the new key database password. This password must differ from the old password.
-expire: Represents the number of days before the password expires.
-stash: Indicates password stashing for the 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 uses 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.

Pertains to UNIX users Pertains to Windows NT users Pertains to Windows 2000 users

Creating a new key pair and certificate request

You find key pairs and certificate requests stored in a key database. To create a public and private key pair and certificate request:

  1. If you have not created the key database, see Creating a new key database for instructions.
  2. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  3. Click Key Database File, from the main UI, then click Open.
  4. Enter your key database name in the Open dialog box, or click the key.kdb file, if you use the default. Click OK.
  5. In the Password Prompt dialog box, enter your correct password and click OK.
  6. Click Create from the main UI, then click New Certificate Request.
  7. In the New Key and Certficate Request dialog box, enter the following:
    • 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)
    • Zip code (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. Click OK in the Information dialog box. A reminder to send the file to a certificate authority appears.

Pertains to Linux for S/390 users

Linux for S/390 users: See Using the IKEYCMD command line interface for more detailed information about IKEYCMD.

To create a public and 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 <file name> -label <label>
    
    where:
    -size: Represents a key size of 512, or 1024.
    -label: Represents a label attached to a certificate or a certificate request.
    -dn: Represents an X.500 distinguished name. 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"

    where:

    -file: Represents the name of the file where the certificate request stores.

  2. Verify that the certificate 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 <file name> 
      -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 act as your own CA for a private Web network.

Pertains to UNIX users Pertains to Windows NT users Pertains to Windows 2000 users

To create a self-signed certificate:

  1. See Creating a new key database for instructions, if you have not created the key database.
  2. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  3. Click Key Database File from the main UI, then click Open.
  4. Enter your key database name in the Open dialog box, or click the key.kdb file, if you use the default. Click OK.
  5. Enter your password in the Password Prompt dialog box, and click OK.
  6. Click Personal Certificates in the Key Database content frame, and click the New Self-Signed radio button.
  7. Enter the following information in the Password Prompt dialog box:
    • 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)
    • Zip code (Optional)
    • Country: Enter a country code. Specify at least two characters. Example:US
    • Validity Period
  8. Click OK.
Pertains to Linux for S/390 users

Linux for S/390 users: See Using the Key Management Utility 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: Indicates a key size of 512, or 1024
-label: Indicates a descriptive comment used to identify the key and certificate in the database.
-dn: Indicates an X.500 distinguished name. 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 as the default certificate in the key database. Enter no, if not.

Pertains to UNIX users Pertains to Windows NT users Pertains to Windows 2000 users

Exporting keys

To export keys to another key database:
  1. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  2. Click Key Database File from the main UI, then click Open.
  3. Enter your key database name in the Password Prompt dialog box, or click key.kdb if using the default. Click OK.
  4. Enter your correct password in the Password Prompt dialog box, and click OK.
  5. Click Personal Certificates in the Key Database content frame, then click Export/Import on the label.
  6. In the Export/Import Key window:
    • Click Export Key.
    • Click the target database type.
    • Enter the file name, or use the Browse option.
    • Enter the correct location.
  7. Click OK.
  8. Click OK in the Password Prompt dialog box,to export the selected key to another key database.

To export keys to a PKCS12 file:

  1. Enter ikeyman on a command line on the UNIX platform, or start the Key Management utility in the IBM HTTP Server folder on the Windows NT operating system.
  2. Click Key Database File from the main UI, then click Open.
  3. Enter your key database name in the Open dialog box, or click key.kdb if you use the default. Click OK.
  4. Enter your password in the Password Prompt dialog box and click OK.
  5. Click Personal Certificates in the Key Database content frame, then click Export/Import on the label.
  6. In the Export/Import Key window:
    • Click Export KeyM.
    • Click the PKCS12 database file type.
    • Enter the file name, or use the Browse option.
    • Enter the correct location.
  7. Click OK.
  8. Enter the correct password in the Password Prompt dialog box, and enter the password again to confirm. Click OK to export the selected key to a PKCS12 file.
Pertains to Linux for S/390 users

Linux for S/390 users: See Using the IKEYCMD command line interface for more detailed information about IKEYCMD.

Pertains to UNIX users Pertains to Windows NT users Pertains to Windows 2000 users

Importing keys

To import keys from another key database:

  1. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  2. Click Key Database File from the main UI, then click Open.
  3. Enter your key database name in the Open dialog box, or click the key.kdb file, if using the default. Click OK.
  4. Enter your password in the Password Prompt dialog box, and click OK.
  5. Click Personal Certificates in the Key Database content frame, then click Export/Import on the label.
  6. In the Export/Import Key window:
    • Click the Import Key.
    • Click the key database file type.
    • Enter the file name, or use the Browse option.
    • Select the correct location.
  7. Click OK.
  8. Enter the correct password in the Password Prompt dialog box, and click OK.
  9. Click the correct label name in the Select from Key Label list, and click OK.
Pertains to UNIX users Pertains to Windows NT users Pertains to Windows 2000 users

To import keys from a PKCS12 file:

  1. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  2. Click Key Database File from the main UI, then click Open.
  3. Enter your key database name in the Open dialog box, or click the key.kdb file, if using the default. Click OK.
  4. Enter your password and click OK.
  5. Click Personal Certificates in the Key Database content frame, then click the Export/Import button on the label.
  6. In the Export/Import Key window:
    • Click Import Key.
    • Click 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.
Pertains to Linux for S/390 users

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

Pertains to UNIX users Pertains to Windows NT users Pertains to windows 2000 users

Listing certificate authorities

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

  1. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  2. Click Key Database File from the main UI, then click Open.
  3. Enter your key database name in the Open dialog box, or click the key.kdb file, if you use the default. Click OK.
  4. Enter your correct password in the Password Prompt dialog box, and click OK.
  5. Click 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.
Pertains to Linux for S/390 users

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

Pertains to the UNIX users Pertains to Windows NT users Pertains to Windows 2000 users

Opening a key database

To open an existing key database:

  1. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  2. Click Key Database File from the main UI, then click Open.
  3. In the Open dialog box, enter your key database name, or click the key.kdb file, if you use the default. Click OK.
  4. Enter your correct password in the Password Prompt dialog box, and click OK.
  5. The key database name appears in the File Name text box.
Pertains to Linux for S/390 users

Linux for S/390 users: See Using the IKEYCMD command line interface for more detailed information about IKEYCMD.

No explicit opening of a key database occurs. For each command, specify database and password options. These specifications provide the information needed to operate in a key database.

Receiving a signed certificate from a certificate authority

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 can send more than one certificate. In addition to the certificate for your server, the CA can 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 issuing your CA-signed certificate is not a trusted CA in the key database, store the CA certificate first 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.

Pertains to UNIX users Pertains to Windows NT users Pertains to Windows 2000 users

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

  1. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  2. Click Key Database File from the main UI, then click Open.
  3. Enter your key database name in the Open dialog box, or click the key.kdb file, if you use the default. Click OK.
  4. Enter your correct password in the Password Prompt dialog box, then click OK.
  5. Click Personal Certificates in the Key Database content frame, then click Receive.
  6. Enter the name of a valid Base64-encoded file in the Certificate file name text field in the Receive Certificate from a File dialog box. Click OK.
Pertains to Linux for S/390 users

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 <file name> dB <dB_name>
.kdb -pw <password> -format <ascii | binary> -default_cert <yes | no>

where:
-format: Represents where a certificate authority can provide a CA certificate, in either ASCII or binary format
-label: Represents the label attached to the CA certificate.
-trust: Indicates whether you can trust this CA. Use enable options when receiving a CA certificate.
-file: Indicates file containing the CA certificate.

Pertains to the UNIX users Pertains to Windows NT users Pertains to Windows 2000 users

Showing the default key in a key database

To display the default key entry:

  1. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  2. Click Key Database File from the main UI, then click Open.
  3. Enter your key database name in the Open dialog box, or click the key.kdb file, if using the default. Click OK.
  4. Enter your password in the Password Prompt dialog box, then click OK.
  5. Click Personal Certificates in the Key Database content frame, and click the CA certificate label name.
  6. Click View/Edit and view the certificate default key information in the Key Information window.
Pertains to Linux for S/390 users

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>

Pertains to UNIX users Pertains to Windows NT users Pertains to Windows 2000 users

Storing a certificate authority certificate

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

  1. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  2. Click Key Database File from the main UI, then click Open.
  3. Enter your key database name in the Open dialog box, or click the key.kdb file, if you use the default. Click OK.
  4. Enter your correct password in the Password Prompt dialog box, and click OK.
  5. Click Signer Certificates in the Key Database content frame, then click Add.
  6. In the Add CA Certificate from a File dialog box, click 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.
Pertains to Linux for the S/390 users

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 <file name>.kdb -pw <password>
-label <label> -format <ASCII | binary> -trust <enable |disable> -file
<file>
where:
-label: Represents the label attached to the certificate or the certificate request
-format: Indicates that the certificate authorities can supply a binary ASCII file
-trust: Indicates whether you can trust this CA. This value should be Yes.

Pertains to UNIX users Pertains to Windows NT users Pertains to Windows 2000 users

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 creates:

  1. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  2. Click Key Database File from the main UI, then click Open.
  3. Enter your key database name in the New dialog box, or click the key.kdb file, if using the default. Click OK.
  4. Enter your correct password in the Password Prompt dialog box, then enter to confirm your password.
  5. Select the stash box and click OK.
  6. Click Key Database File > Stash Password.
  7. Click OK in the Information dialog box.
Pertains to Linux for S/390 users

Linux for S/390 users: See Using the IKEYCMD command line interface for more detailed information on IKEYCMD.

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

Pertains to UNIX users Pertains to Windows NT users Pertains to windows 2000 users

To store the password after creating a database:

  1. Start the IKEYMAN GUI. Refer to Starting the Key Management Utility for platform-specific instructions.
  2. Click Key Database File from the main UI, then click Open.
  3. Enter your key database name in the Open dialog box, or click the key.kdb file, if you use the default. Click OK.
  4. Enter your correct password in the Password Prompt dialog box, and click OK.
  5. Click Key Database File, then click Stash Password.
  6. Click OK in the Information dialog box.
Pertains to Linux for S/390 users

Linux for S/390 users: See Using the IKEYCMD command line interface for more detailed information on IKEYCMD.

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

Pertains to Linux for S/390 users

On Linux for S/390: Using the Key Management Utility command line interface

On the Linux for S/390 operating system, IKEYCMD, the Java command line interface to IKEYMAN, provides the necessary options to create and manage keys, certificates and certificate requests. If you act 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 and 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, use the IBM Administration Server.

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

Looking at the Key Management Utility command line syntax

The syntax of the Java command line interface follows:

 	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, exists as a sample file that you can modify and use with any Java application.

Object includes 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
Displays help for the IKEYCMD invocations

-version
Displays version information for IKEYCMD

Action represents the specific action to take on the object, and options represents the options, both required and optional, specified for the object and action pair.

Note: The object and action keywords are positional and you must specify them in the selected order. However, options are not positional and you can specify them in any order, as an option and operand pair.

Reviewing Key Management Utility command line parameters

The following table describes each action possible 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 you can modify 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 requests in the certificate request database
-recreate Recreate a certificate request
-help Display help information for the IKEYCMD command
-version Display IKEYCMD version information

Reviewing Key Management Utility command line options

The following table shows each option that can exist on the command line. The options are listed as a complete group. However, their use depends 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 use 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.

Using command line invocation

A list of each command line invocation, with the optional parameters specified in italics follows.

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

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

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

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

-help

-version

Working with user properties file

To eliminate some of the typing on the Java command line interface invocations, specify user properties in a properties file. Specify the properties file on the Java command line invocation through 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.

 
Finding related information

     (Back to the top)