PingDS

PKCS#11 HSM

DS servers support key management using a Public-Key Cryptography Standard #11 (PKCS#11) token store. The PKCS#11 standard defines a cryptographic token interface, a platform-independent API for storing keys in a Hardware Security Module (HSM), for example.

DS servers rely on the PKCS#11 interface and Java APIs to use it. DS servers don’t support vendor-specific interfaces.

DS servers use an HSM only to hold asymmetric key pairs and, optionally, CA certificates. (Since the CA certificate holds the CA’s public key, which isn’t secret, store it in a separate, file-based keystore or PEM file, not in the HSM.)

The asymmetric key pairs you can store in the HSM are the server’s TLS keys, the shared master key, and the optional shared signing key for the deployment.

DS servers use the shared master key to wrap symmetric (secret) keys. DS servers store secret keys in the data they encrypt. For this reason, DS servers don’t use the HSM for secret keys.

Using a PKCS#11 device for storing DS keys involves:

  • Storing the keys on the PKCS#11 device.

    How you generate and store keys in your HSM depends on the device. Learn more in the documentation for your device.

  • Creating the DS PKCS#11 key manager provider to access the device.

    The DS server accesses a PKCS#11 device using a PIN. You can provide the PIN in the server configuration or in a separate file. Store the PIN as a cleartext value DS can read on startup.

  • Configuring DS components to use the key manager provider.

    For example, DS connection handlers reference the key manager provider in their configurations.

Prepare the HSM and keys

  • The examples on this page use BouncyHsm for evaluation.

  • The examples use the sun.security.pkcs11.SunPKCS11 provider implementation with BouncyHsm.

  • Adapt the examples for use with your HSM.

  1. Install BouncyHsm.

  2. Go to the BouncyHsm UI in a browser.

  3. Create a slot.

    • Record the user PIN for use when configuring DS.

    • Record the SO PIN in case you choose to reinitialize the token.

    • Record the slot ID for use when creating the Java PKCS#11 configuration file.

  4. Generate a key pair using the following hints:

    Field Value

    Key type

    EC key pair

    EC name or OID

    secp256r1

    CKA LABEL

    ssl-key-pair

    For signing and verification

    Selected

    For encryption and decryption

    Selected

    Private key is sensitive

    Selected

  5. Generate a certificate using the following hint:

    Field Value

    Subject

    CN=localhost,O=Example Corp,C=FR

  6. Download the BouncyHsm PKCS#11 library through the UI.

  7. Create a Java PKCS#11 configuration file, /path/to/hsm.conf, to access BouncyHsm.

    The following example uses the Linux library file and slot 1. Adjust the BouncyHsm library path and use the BouncyHsm slot ID shown in the UI:

    name = BouncyHsm
library = /path/to/BouncyHsm.Pkcs11.so
slot = 1

    Learn about the configuration file format in the Java PKCS#11 Reference Guide.

    Find recommendations for production deployments in the platform documentation page, HSMs and platform software.

  8. Verify Java can access the device using your configuration.

    The following example uses the Java keytool command to list the keys:

    $ keytool \
 -list \
 -keystore NONE \
 -storetype PKCS11 \
 -storepass password \
 -providerClass sun.security.pkcs11.SunPKCS11 \
 -providerArg /path/to/hsm.conf
    Output
    Keystore type: PKCS11
Keystore provider: SunPKCS11-BouncyHsm

Your keystore contains 1 entry

ssl-key-pair, PrivateKeyEntry,
Certificate fingerprint (SHA-256): <fingerprint>

You have successfully prepared the HSM and keys for use with DS.

Let DS access the HSM

DS presents its certificate to client applications, so get it signed by a CA they trust.

For evaluation only with BouncyHsm, use the ssl-key-pair self-signed certificate you generated.

Repeat these steps for each DS server:

  1. Make the plaintext user PIN for the slot available to the DS server.

    Store the PIN in a single-line file with restricted permissions:

    $ ls -l /path/to/opendj/config/bouncyhsm.pin
-rw-------  1 user  staff   /path/to/opendj/opendj/config/bouncyhsm.pin

    DS reads the file when the server starts.

    For some HSMs, you provide the PKCS#11 token credentials as part of the configuration instead. In such cases, you don’t need a file for the PIN as in this example.

  2. Configure a PKCS#11 key manager provider to access the HSM.

    The following example creates a provider for BouncyHsm:

    • The pkcs11-provider-name:SunPKCS11 setting uses the Java name for the PKCS#11 provider.

    • The pkcs11-provider-arg:/path/to/hsm.conf setting holds the absolute path to the Java PKCS#11 configuration file.

    • The configuration uses the bouncyhsm.pin file to get the user PIN for the slot.

    • The command connects to the administrative port (4444) where the existing PKCS12 keystore contains the trusted CA certificate.

    $ dsconfig \
 create-key-manager-provider \
 --provider-name BouncyHsm \
 --type pkcs11 \
 --set enabled:true \
 --set pkcs11-provider-name:SunPKCS11 \
 --set pkcs11-provider-arg:/path/to/hsm.conf \
 --set key-store-pin:"&{file:config/bouncyhsm.pin}" \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --trustStorePath /path/to/opendj/config/keystore \
 --trustStoreType PKCS12 \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

Use the keys in the HSM

  1. Configure a connection handler to use the PKCS#11 key manager provider.

    The following example configures an existing LDAPS connection handler to use the BouncyHsm provider. The command connects to the administrative port (4444) where the existing PKCS12 keystore contains the trusted CA certificate:

    $ dsconfig \
 set-connection-handler-prop \
 --handler-name LDAPS \
 --set key-manager-provider:BouncyHsm \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --trustStorePath /path/to/opendj/config/keystore \
 --trustStoreType PKCS12 \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

  2. Check TLS with the HSM configured:

    $ ldapsearch \
 --hostname localhost \
 --port 1636 \
 --useSSL \
 --baseDN dc=example,dc=com \
 "(uid=bjensen)" \
 cn
    Output
    User DN  : CN=localhost, O=Example Corp, C=FR
Issuer   : CN=localhost, O=Example Corp, C=FR
Validity : <validity-period>

Do you trust this server certificate?

  1) No
  2) Yes, for this session only
  3) Yes, also add it to a truststore
  4) View certificate details

Enter choice: [1]: 2

dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen

You have successfully demonstrated using keys in an HSM for DS TLS connections.

Store shared master keys in the HSM

  • Before you begin, set up DS servers without the --start option, and without any data or setup profiles that create base entries or generate data, as in Install DS for custom cases. Don’t start the DS server until you have configured it to use the shared master key(s) in your HSM.

    The setup command requires a deployment ID and password. It generates a shared master key you will discard. If you start DS with any data at all, it uses the generated shared master key to wrap symmetric keys and DS must continue to use that shared master key to decrypt the data.

    Don’t use this procedure when upgrading servers.

  • A shared master key is an asymmetric key pair with a self-signed certificate. Only DS uses the shared master key. DS only uses it for encrypting and decrypting secret keys and for signing and verifying signatures on backups, unless you configure a separate shared signing key. DS does not check the hostname or the validity period of the shared master key, so neither matters.

  • When you store the shared master key(s) in an HSM:

    • The HSM must share the identical master key(s) with all DS servers in the deployment.

      Each server wraps and unwraps shared secret keys with a shared master key. Without access to the same shared master key, DS servers cannot read each others' encrypted data.

      The (networked) HSM must replicate the same shared master key pair(s) everywhere for each HSM instance DS servers access.

    • DS servers mustn’t rely on cn=admin data.

      All the secret keys must use the DS 7 and later security model exclusively. The procedures describing how to use an HSM for the shared master key don’t apply if you upgraded from DS 6.5 or earlier and used encrypted data.

  1. Generate a shared master key pair in the HSM using the following hints:

    Setting Value

    Key algorithm

    RSA

    Key size

    Use at least 3072 bits

    Also generate a self-signed certificate for the key pair.

  2. (Optional) For FIPS compliance, use separate keys for signing backups and for key wrapping.

    In this case, generate a second shared master key pair and certificate for signing backups with a different alias from the default (master-key).

  3. For each DS server, create the PKCS#11 key manager provider to access the HSM, without starting the server.

    Use the dsconfig create-key-manager-provider command with --offline.

  4. For each DS server, update the Crypto Manager to reference the PKCS#11 key manager provider.

    For example, set the key manager provider for the Crypto Manager to <my-hsm-provider>:

    $ dsconfig \
 set-crypto-manager-prop \
 --set key-manager-provider:<my-hsm-provider> \
 --set master-key-alias:<shared-master-key-alias> \
 --offline \
 --no-prompt

    The following example for FIPS compliance uses separate keys for key wrapping and signing backups:

    $ dsconfig \
 set-crypto-manager-prop \
 --set key-manager-provider:<my-hsm-provider> \
 --set master-key-alias:<wrapping-key-alias> \
 --set signing-key-alias:<signing-key-alias> \
 --offline \
 --no-prompt

  5. For each DS server, apply Setup profiles with the setup-profile command, and complete any necessary preliminary configuration.

  6. Start each DS server.

You have successfully configured DS servers to use shared master key(s) in your HSM.