PKCS12 with IBM HTTP Server / / and later

IBM HTTP Server (or the WAS WebServer Plug-in) / / 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 IBM Global Security Kit (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 IBM Global Security Kit (GSKit) tools (such as gskcapicmd -certreq -list or Ikeyman) as a CSR, but can be used to "receive" an issued certificate.