Server/client mutual authentication with the Web Services PKCS #11 library

Overview

The Web Services PKCS #11 Library can only communicate securely with a WSOP Server if the following certificates are installed:

The WSOP Server’s CA certificate.
An appropriate client certificate (with each PKCS #11 client using its own client certificate).
Any intermediate CA certificates that are to be used to form a complete chain to verify the client certificate on the WSOP Server.

The following sections in the nShield Web Services Option Pack User Guide contain information concerning the PKCS #11 Library’s client certificates:

Web Services client authentication describes the Web Services Option Pack client authentication, client certificate based virtual partitioning, and the client certificate revocation.
TLS client authentication describes how the client ‘s CA (root) certificate for the PKCS #11 Library’s client’s certificate hierarchy is configured in the WSOP server.
Appendix A: Security guidance for the Web Services Option Pack describes some important security considerations associated with the PKCS #11 Library’s client’s certificate hierarchy.

The ‘extended key usage’ extension of a PKCS #11 Library’s client (end-entity) certificate should be set to ‘TLS Web client authentication’.

Linux

The following guidance should be followed when installing the PKCS #11 Library’s certificates in a Linux platform.

If intermediate certificates are used in the PKCS #11 Library’s client certificate hierarchy, they should be included in the same file as the client certificate. The root client certificate should not be included in this file.
The recommended format for the client certificate file is PEM.
The recommended format for the client certificate key file is PEM.

For details on the Linux config file entries, see Configuration parameters for Linux only.

Windows

The following guidance should be followed when installing the PKCS #11 Library’s certificates in a Windows platform.

Install the WSOP Server’s CA certificate into the Root store.
Below is an example of how you can do this using certutil.exe.
1. Add a CA certificate to the Root store
  certutil.exe -addstore Root <ca_certificate.pem>
2. Check that the certificate has been installed:
  certutil.exe -store Root
Install any intermediate CA certificates for the client certificate.
Below is an example of how you can do this by using certutil.exe to load the client certificate’s intermediate certificates into the 'CA' certificate store:
```
certutil.exe -addstore CA <intermediate_ca_certificate.pem>
```
Install the client certificate and its private key. This should be a PFX file that contains a single certificate and the associated private key.

The PFX must not contain the full certificate chain.

For example, to install the PFX file in the Local Machine’s certificate store
```
certutil.exe -p <password> -importPFX [certificatestorename] <client-cert.pfx>
```
or to install the PFX file into the Current User’s certificate store
```
certutil.exe -p <password> -importPFX -user [certificatestorename] <client-cert.pfx>
```

To find the thumbprint of a certificate, open Certificate view dialog box with the command below, select the details tab and scroll down to the thumbprint field. For example, to view thumbprints in My store.

certutil.exe -viewstore My

PowerShell can also be used to see the thumbprint on a list. In this example store is My and store type is LocalMachine.

PS Get-ChildItem -Path Cert:LocalMachine\My

If necessary, update pkcs11webservices.cfg with the changed thumbprint.

For details on the Windows config file entries, see Configuration parameters for Windows only