9.0.0.0 and later¶

IBM HTTP Server (or the WAS WebServer Plug-in) 8.0.0.9 / 8.5.5.2 / 9.0.0.0 and later support using PKCS12 key stores directly. Generally, PKCS12 files created and maintained by any tools can be used, but the files must adhere to a few criteria as listed below.

PKCS12 requirements¶

PKCS12 files used with IBM HTTP Server must meet the criteria in the following sections

Complete certificate chain in PKCS12¶

The PKCS12 file must contain the complete certificate chain for any end-entity (server) certificate inside the file.

If using openssl to create the PKCS12 file, this means the root should be included with "-certfile" and/or "-chain" parameters should be included to make sure the root and any intermediate certs are present.

$ openssl pkcs12 -cacerts -nokeys ... should return the certificates trust chain.

PKCS12 password requirements¶

A PKCS12 file has to actually contain a private key to be used as a server keystore.
The PKCS12 file must be password protected. The password can be stashed with gskcapicmd (bin/gskcapicmd -keydb -stashpw ...). or interactively with ikeyman.
If the private keys in the PKCS12 file are encrypted, they must be encrypted with the same password as the overall PKCS12 file.

Certificate label requirements¶

For a certificate to be usable in IHS, the certificate must have a PKCS12 "friendly name" and that name must be passed to SSLServerCert.

 $ openssl pkcs12 -in pkcs12test.p12 -nokeys -clcerts|grep friendlyName
    friendlyName: mycert

Because some tools may fold the case of friendly names, using lowercase characters only is recommended.
Duplicate friendly name fields can be problematic.
At PKCS12 creation time, the friendly name is specified with the -name parameter in openssl.

CSR Issues¶

Listing CSRs¶

Unlike CMS key files, a PKCS12 file does not keep an explicit record of outstanding Certificate Signing Requests (CSR). When GSKit creates a CSR in a PKCS12 file, it creates a dummy certificate with a special issuer and extension to identify it internally as representing a CSR. If other software creates the CSR, it will NOT be visible to GSKit tools (such as gskcapicmd -certreq -list or Ikeyman) as a CSR, but can be used to "receive" an issued certificate.