IBM HTTP Server certificate management

Background information and tools

The primary tool for creating certificates with IBM HTTP Server is iKeyman, a graphical pure Java™ key management tool.

On z/OS® operating systems, all certificate management is done with the native gskkyman certificate management tool.

On Microsoft Windows, you can start iKeyman using the Start Menu. On other platforms, start the tool from the IBM HTTP Server bin/ directory, like all IBM HTTP Server executable files.

Native and Java supplemental command-line certificate management tools are also provided in the IBM HTTP Server bin/ directory as gskcmd (also known as iKeycmd) and gskcapicmd (also known as gsk8capicmd). Both share similar syntax and contain extensive embedded usage information.

Certificate limitations in IBM HTTP Server

Complete documentation for certificate management tools

System setup

Certificate management tasks

Detailed example scenarios for certificate management are documented in the complete documentation for iKeyman (distributed operating systems) and gskkyman (z/OS operating systems).

Certificate management tasks

Detailed example scenarios for certificate management are documented in the complete documentation for iKeyman (distributed operating systems) and gskkyman (z/OS operating systems).

See the following command-line examples of common tasks. You can view full usage syntax by entering the following commands with only the first two parameters, or you can refer to the comprehensive documentation for the command. The following table lists the operations that you can perform on CA certificates, the AdminTask object that you can use to perform that operation, and how to navigate to the certificate on the console:

Create a CMS keystore

When creating a keystore to be used with IBM HTTP Server, specify the option to stash the password to a file regardless of the tool used.

# Syntax: <ihsroot>/bin/gskcapicmd -keydb -create -db <database> -pw <password> -stash 
<ihsroot>/bin/gskcapicmd -keydb -create -db /opt/IBM/HTTPServer/key.kdb -pw password -stash

Populate a keystore with a set of default trusted CA certificates

By default, new keystores contain no trusted CA certificates.

# The populate operation is supported with Ikeyman and gskcmd (ikeycmd) only, not with gskcapicmd. 
# Syntax: <ihsroot>/bin/gskcmd -cert -populate -db <database> -pw <password> 
<ihsroot>/bin/gskcmd -cert -populate -db /opt/IBM/HTTPServer/key.kdb -pw password

Add additional CA certificates, if wanted (optional)

# Syntax: <ihsroot>/bin/gskcapicmd -cert -add -db <database> -pw <password >-file <inputcert> -label <labelname> 
<ihsroot>/bin/gskcapicmd -cert -add -db /opt/IBM/HTTPServer/key.kdb -pw password -file cacert.cer -label "CA certificate from example.com"   

Create a self-signed certificate for test purposes (optional)

#Syntax: <ihsroot>/bin/gskcapicmd -cert -create -db <database> -pw <password>  \
     -dn <distinguished name> -label <labelname> -size <size> 
<ihsroot>/bin/gskcapicmd -cert -create -db /opt/IBM/HTTPServer/key.kdb -pw password \
     -dn "cn=www.example.com" -label "example.com" -size 2048

Create a certificate request

Most of the fields and options are optional, including selecting a Signature Algorithm (this signature is used only by your certificate authority, not at runtime). You can also specify other host names for your web server.

# Syntax: <ihsroot>/bin/gskcapicmd -certreq -create -db <database> -pw <password> \
     -dn <distinguished name> -label <labelname> -size  <size> -file <outputfilename> 
<ihsroot>/bin/gskcapicmd -certreq -create -db/opt/IBM/HTTPServer/key.kdb -pw password \
   -dn "cn=www.example.com" -label www.example.com -size 2048 -file example.csr 

Submit the certificate request to a trusted certificate authority

This task does not include using any local tools. Typically, the certificate request (example.csr) is sent in an email or uploaded to a trusted certificate authority.

Receive the issued certificate

Receiving a certificate associates a signed certificate from your CA with the private key (personal certificate) in your KDB file. A certificate can only be received into the KDB that generated the certificate request.

# Syntax: <ihsroot>/bin/gskcapicmd -cert -receive -db db <database> -pw <password> -file <inputcertificate> 
<ihsroot>/bin/gskcapicmd -cert -receive -db/opt/IBM/HTTPServer/key.kdb -pw password -file certificate.arm

List certificates in a keystore.

# Syntax <ihsroot>/bin/gskcapicmd -cert -list -db <database> -pw <password> 
<ihsroot>/bin/gskcapicmd -cert -list -db /opt/IBM/HTTPServer/key.kdb -pw password 

Import certificates from JKS or PKCS12 into a key file usable by IBM HTTP Server (optional)

Instead of creating a new private key (personal certificate), you can import an existing private key and certificate created by another tool into an existing key file.

# Syntax: <ihsroot>/bin/gskcapicmd -cert -import -db <inputp12file> -pw <pkcs12password>\
      -target <existingkdbfile>  -target_pw <existingkdbpassword> 
<ihsroot>/bin/gskcapicmd -cert -import -db other.p12 -pw pkcs12password  \
     -target key.kdb -target_pw password 

View certificate expiration data (optional)

The -expiry flag causes certificates that will be considered expired "numdays" in the future to be displayed. Use 0 to display already expired certificates, or large numbers to display all certificate expiration dates.

# Syntax:<ihsroot>/bin/gskcapicmd -cert -list -db <database> -pw <password> -expiry <numdays> 
<ihsroot>/bin/gskcapicmd -cert -list -db key.kdb -password -expiry 365