# PKCS12 with IBM HTTP Server 8.0.0.9 / 8.5.5.2 / 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<!-- {#CRITERIA} -->

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

### Complete certificate chain in PKCS12<!-- {#chain} -->

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<!-- {#password} -->

- 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<!-- {#label} -->

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<!-- {#CSR} -->

### Listing CSRs<!-- {#certreqlist} -->

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.