Using PKCS #11 in the PingDirectory server

There are two ways to configure the PingDirectory server to use a PKCS #11 token to access the listener certificate.

You can either:

Set up the PingDirectory server with PKCS #11 support enabled during setup.
Enable PKCS #11 support after setup.

Regardless of the method, you must perform some initial preparation.

Performing initial preparation for PCKS #11 support in the PingDirectory server

Steps

Extract the PingDirectory server .zip file onto the system.

In this example, it’s assumed that it’s in /demo/PingDirectory.
Make /demo/PingDirectory your current working directory.
Create a provider configuration file that tells Java how to interact with the PKCS #11 token.

If you use a different type of PKCS #11 token, like an actual hardware security module (HSM), then you must specify the appropriate path to its driver library.

Consult the documentation for the token that you’re using for details, but the provider configuration file will generally look something like the following:

Example:
```
name = pkcs11
library = /path/to/provider/library.so
slotListIndex = 0
```
Create a file with the user PIN needed to access the token.
Ensure that the PKCS #11 token has an appropriate certificate chain to present to clients during TLS negotiation.

In many cases, you can use the manage-certificates tool to accomplish this. When interacting with a PKCS #11 token with manage-certificates, you must use the --keystore argument to specify the path to the provider configuration file, the --keystore-type argument with a value of PKCS11, and one of the --keystore-password, --keystore-password-file, or --prompt-for-keystore-password arguments to supply the user PIN.

Example:
```
$ bin/manage-certificates generate-certificate-signing-request \
     --keystore /path/to/provider.conf \
     --keystore-password-file /path/to/pkcs11/user.pin \
     --keystore-type PKCS11 \
     --alias server-cert \
     --subject-dn "CN=demo.example.com,O=Example Corp,C=US" \
     --key-algorithm EC \
     --key-size-bits 256 \
     --signature-algorithm SHA256withECDSA \
     --subject-alternative-name-dns demo.example.com \
     --subject-alternative-name-ip-address 1.2.3.4 \
     --extended-key-usage server-auth \
     --extended-key-usage client-auth \
     --output-file server-cert.csr \
     --output-format PEM
```
After you have the signed certificate, use the manage-certificates import-certificate command to import the certificate chain (the signed certificate, any intermediate authority certificates, and the root authority certificate).

Enabling PKCS #11 support during setup

About this task

If you know that you’re going to be using a PKCS #11, you can enable PKCS #11 support when running setup or manage-profile setup.

Steps

Run setup or manage-profile setup with the following important arguments:

--usePKCS11KeyStore

Indicates that you want to configure the server to use a PKCS #11 token to access the listener certificate.

--pkcs11ProviderConfigFile <path>

Specifies the path to the provider configuration file that tells the JVM how to access the PKCS #11 token.

--keyStorePasswordFile <path>

Specifies the path to the file containing the user PIN needed to interact with the PKCS #11 token.

Example:

$ ./setup \
     --no-prompt \
     --noPropertiesFile \
     --acceptLicense \
     --localHostName demo.example.com \
     --ldapPort 1389 \
     --ldapsPort 1636 \
     --httpsPort 1443 \
     --usePKCS11KeyStore \
     --pkcs11ProviderConfigFile config/path/to/provider.conf \
     --keyStorePasswordFile /path/to/pkcs11/user.pin \
     --encryptDataWithPassphraseFromFile config/encryption-settings.pin \
     --baseDN dc=example,dc=com \
     --rootUserDN "cn=Directory Manager" \
     --rootUserPasswordFile config/pre-encoded-root-user-password.txt \
     --instanceName demo-instance \
     --location demo-location

Ping Identity Directory Server 8.3.0.0

Initializing ..... Done
Configuring Directory Server .....

Server tools will be configured with a minimal heap size due to limited system memory
available. If out of memory errors occur, it will be necessary to increase tool memory
settings in java.properties and run dsjavaproperties for the changes to take effect.

Configuring Directory Server ..... Done
Configuring Certificates ..... Done
Starting Directory Server ..... Done

Access product documentation from docs/index.html

If you don’t specify any trust store-related properties, then setup automatically generates a trust store populated with just the listener certificate, which works if the token is configured with a self-signed certificate, or if you’re using a certificate signed by an authority that is already included in the JVM’s default trust store.

However, if you’re using a certificate signed by a private authority, then you likely want to either provide an existing trust store, such as in JKS or PKCS #12 format, or you want to use the --trustedCertificatePEMFile argument to specify the paths to PEM files for any appropriate issuer certificates that you want to include in the trust store.

Enabling PKCS #11 support after setup

Before you begin

Make sure that the token already includes a suitable certificate and that the PKCS #11 provider configuration files and user PIN files exist as described in Performing initial preparation for PCKS #11 support in the PingDirectory server.
Make sure that the trust store has the appropriate trust information for the certificate in the PKCS #11 token. If that certificate is signed by an authority in the Java virtual machine (JVM)’s default set of trusted issuers, or if it’s signed by the same private internal authority as the certificate in the current file-based key store, then you can skip this.

But if the certificate in the PKCS #11 token is self-signed, or if it’s signed by an authority that the server isn’t currently configured to trust, then you must update the trust store with the necessary certificates.

About this task

If you already have an existing PingDirectory server set up with some other type of key store, you can update it to use a PKCS #11 token without needing to set up a whole new instance.

Steps

Update the server to use the PKCS #11 token instead of the file-based key store.

Enable the PKCS11 key manager provider and give it the appropriate provider configuration file and user PIN file.

Update any appropriate connection handlers to use the PKCS11 key manager provider.

Example:

The following batch file demonstrates the configuration changes that you can use to accomplish this.

dsconfig set-key-manager-provider-prop \
     --provider-name PKCS11 \
     --set enabled:true \
     --set pkcs11-provider-configuration-file:config/path/to/provider.conf \
     --set key-store-pin-file:config/path/to/pkcs11/user.pin

dsconfig set-connection-handler-prop \
     --handler-name "LDAPS Connection Handler" \
     --set key-manager-provider:PKCS11

dsconfig set-connection-handler-prop \
     --handler-name "LDAP Connection Handler" \
     --set key-manager-provider:PKCS11

dsconfig set-connection-handler-prop \
     --handler-name "HTTPS Connection Handler" \
     --set key-manager-provider:PKCS11

dsconfig set-connection-handler-prop \
     --handler-name "JMX Connection Handler" \
     --set key-manager-provider:PKCS11

At present, it seems that if you change the key type that the certificate uses, such as if you change from a certificate that uses an RSA key pair to one that uses an elliptic curve key pair, then you might need to restart the server, or at least disable and re-enable the connection handler.

If you don’t do this, then attempts to establish new secure connections could fail during TLS negotiation, and the server-side error might indicate that it can’t handle the new key type.