Recently, I was asked by a client to help them set up a couple of SSL certificates on two IBM HTTP Server (IHS) environments; one for QA, and one for development. It’d been a while since I worked with SSL certificates, but from what I recalled, it’s always been a rather painful process. That assumption held true in this case; on the plus side the IHS servers in question did not yet have any SSL configuration, so I didn’t have to deal with multihoming the ethernet adapters or acquiring a wildcard certificate.
So, first off, I needed to create a keystore. One thing to remember about IHS is that its SSL certificates are accessed using a completely different mechanism from the usual Apache mod_ssl method; IHS certificates must be stored in a CMS key database created by the GSKit software installed with IHS. GSKit provides a relatively powerful set of tools for dealing with SSL certificates; the only problem with GSKit is that it’s not really very intuitive. So, I went about creating a keystore; lacking a GUI interface, I was obliged to accomplish this using the command-line interface to GSKit, the gsk7cmd command. In order to use gsk7cmd on the command line, it’s necessary to set up your session’s PATH and CLASSPATH variables appropriately, as below:
export PATH=${IHS_HOME}/java/jre/bin:${IHS_HOME}/gsk7/bin:$PATH export CLASSPATH=${IHS_HOME}/gsk7/classes/cfwk.zip:${IHS_HOME}/gsk7/classes/gsk7cls.jar:$CLASSPATH
In order to actually create the keystore, invoke the gsk7cmd command with the following options:
gsk7cmd -keydb -create -db ihskeys.kdb -pw coolpassword -type cms -stash
The only option of note is the -stash option; this instructs gsk7cmd to create a stash file containing an encrypted password value on the filesystem. This stash file allows IHS to automatically open the keystore without waiting for an interactive password prompt; rather important if you want IHS to be automatically started when the system initializes.Now that we have our keystore, it’s time to create a certificate request. Using gsk7cmd, issues the following command, replacing with your own salient information:
gsk7cmd -certreq -create -db ihskeys.kdb -pw coolpassword -label host.www.xtivia.com -dn "CN=host.www.xtivia.com,O=Xtivia,L=Austin,ST=Texas,C=US" -size 2048 -file host.www.xtivia.com.certreq
Note that I’m creating a cert request for a 2048-bit certificate here.Now, send off this certificate request file to your SSL certificate authority of choice. Once they’ve responded to your request with your valid certificate file, it’s time to import it into the keystore. Here’s where things get tricky.
First things first; you’ll need to import all of the standard CA signing certificates into the keystore to establish the base of the trust chain. Luckily, gsk7cmd provides a quick way to do this; GSKit ships with default CA certificates for a number of CA providers. You can view the list of available default CA certs shipped with GSKit using the following:
gsk7cmd -cert -listsigners
For this example, I’ll be assuming that you received a certificate from Symantec (Verisign) using their Secure Site Pro service. To import Symantec’s root certs, issue the following command:
gsk7cmd -cert -populate -db ihskeys.kdb -label verisign
If you’re using another CA, simply specify their label in place of the “verisign” label.
You may want to verify that the CA certs were correctly populated in your keystore. To list all of the CA certs, issue the following command:
gsk7cmd -cert -list CA -db ihskeys.kdb
You should see all of the various Verisign certificates listed. There are a bunch of ’em. For Symantec Secure Site Pro, there were two additional intermediate CA certificates that I needed to download from their site; I copied them down from the Symantec website and stored them in ASCII format in ./certs/symantec-securesitepro-primary-ca.crt and ./certs/symantec-securesitepro-secondary-ca.crt. I then added these two additional CA certs to the keystore via the following commands:
gsk7cmd -cert -add -db ihskeys.kdb -label "Symantec Secure Site Pro Primary Intermediate" -format ascii -trust enable -file ./certs/symantec-securesitepro-primary-ca.crt gsk7cmd -cert -add -db ihskeys.kdb -label "Symantec Secure Site Pro Secondary Intermediate" -format ascii -trust enable -file ./certs/symantec-securesitepro-secondary-ca.crt
Once this step is completed, you can validate that the certificates have been imported properly via the -cert -list command specified above. Now, you’re ready to import the actual SSL cert! Assuming that you’ve copied the file to a local file named host.www.xtivia.com.crt, execute the following command to import your certificate into the keystore:
gsk7cmd -cert -receive -file host.www.xtivia.com.crt -db ihskeys.kdb -format ascii -default_cert yes
One very important item of note here is that the keystore you import this into must be the same keystore that was used to generate the certificate request. Now you can execute the following command to verify that your cert was successfully imported into the keystore:
gsk7cmd -cert -list -db ihskeys.kdb
That’s basically it! You should now have a valid CMS keystore for use with IBM HTTP Server. One final note on troubleshooting issues with SSL; if after generating your keystore and setting up SSL in IHS, you notice a “SSL0208E” error occurring stating that there was a certificate validation error, then you have a problem with your trust chain. In that situation, you will need to make certain that all of your signer certificates are correctly loaded into the keystore. The -cert -list command is very useful for this, as is the following command:
gsk7cmd -cert -details -db ihskeys.kdb -label host.www.xtivia.com
This command will show the details for a particular certificate, including the CN of its signer. Work your way up the chain until you find out which signer is missing or invalid.