IBM HTTP Server certificate management

Before we can configure IBM HTTP Server to accept TLS (also known as SSL) connections, you must create a certificate for your web server. An SSL certificate authenticates your web servers identity to clients.


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, we 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

  • IBM HTTP Server supports Rivest-Shamir-Adleman (RSA) and Elliptic Curve Digital Signature Algorithm (ECDSA) certificates. Digital Signature Algorithm (DSA) certificates are not supported.

    • The gskkyman utility on z/OS and the bin/gskcapicmd utility are the only certificate management tools that are supported for creating certificates and certificate signing requests with ECDSA keys. The iKeyman and bin/gskcmd utilities have ECDSA capability, but the capability does not interoperate with IBM HTTP Server.

  • Certificates with a key length of up to 4096 bits are supported at run time with IBM HTTP Server.

  • Ikeyman and gskcmd (ikeycmd) support creating certificates of lengths up to 4096 bits. The gskcapicmd command supports creating certificates of lengths up to 4096 bits.

  • Multiple key database files can be used with each instance of IBM HTTP Server, but only one, which can still contain multiple personal certificates, can be used per TLS-enabled virtual host.


Complete documentation for certificate management tools

  • Complete documentation of gskkyman is available in the Cryptographic Services PKI Services Guide and Reference document (SA22-7693) in the z/OS Internet Library.

  • Complete documentation for iKeyman and gskcmd (Ikeycmd) are available in the iKeyman v8 Users Guide.

  • Complete documentation for gskcapicmd (gsk8capicmd), the native command-line certificate management tool, is available on the IBM HTTP Server library page.


System setup

  • Unlike prior releases of IBM HTTP Server, do not move or modify the java/jre/lib/ext/gskikm.jar file.

  • Optionally install the Unrestricted JCE policy files from DeveloperWorks to use unlimited strength cryptography in iKeyman and gskcmd (ikeycmd). This step is often required to manipulate PKCS12 keystores.


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. We can view full usage syntax by entering the following commands with only the first two parameters, or we 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 we 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). We 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), we 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


Related tasks


Related