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.