Directory Services 7.4.3

PKCS#11 hardware security module

DS servers support key management using a PKCS#11 token store. The PKCS#11 standard defines a cryptographic token interface, a platform-independent API for storing keys in an HSM, for example.

DS servers rely on the PKCS#11 interface and Java APIs to use it. DS servers do not 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 is not secret, ForgeRock recommends storing 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, and the shared master 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. Therefore, DS servers do not 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. For details, refer to the documentation for your device.

  • Creating the DS PKCS11 key manager provider to access the device.

    The DS server accesses a PKCS#11 device using a PIN. The PIN can be provided in the server configuration, in a separate file, or as the value of an environment variable or Java system property. The PIN must be stored as a cleartext value, so take care to protect it in production environments.

  • Configuring DS components to use the key manager provider.

    For example, DS connection handlers and OAuth 2.0 authorization mechanisms requiring mutual TLS can reference the key manager provider in their configurations.

Prepare the HSM

  • The examples on this page use a SoftHSM PKCS#11 software device for evaluation, development, and testing.

    The command to configure the SoftHSM build in this example is the following:

    ./configure --with-openssl=/usr/local/opt/openssl --with-sqlite3=/usr/local/opt/sqlite --with-objectstore-backend-db --disable-p11-kit

    Your build configuration options might be different.

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

    If you use a different Java implementation for the provider, refer to the documentation for details on how to use PKCS#11 devices with your JVM.

  • Adapt the examples for use with your HSM.

  1. Install SoftHSM.

    For details, refer to the SoftHSM documentation for details.

  2. Initialize the SoftHSM device:

    $ softhsm2-util --init-token --slot 0 --label "My token 1" --pin password --so-pin password
The token has been initialized and is reassigned to slot <number>

    • The user PIN is the one the DS server needs to access the device.

    • The SO PIN is to reinitialize the token.

    • The <number> is the slot number to use in the PKCS#11 configuration.

  3. Prepare a Java PKCS#11 configuration file to generate key pairs and configure DS.

    For example, to use the Java keytool command with the device, create a PKCS#11 configuration file for the security provider implementation.

    The file name is /path/to/hsm.conf. Replace <number> in the following example with the slot number from the previous step. If you lost track of the slot number, run softhsm2-util --show-slots to view it again:

    name = SoftHSM
library = /usr/local/lib/softhsm/libsofthsm2.so
slot = <number>
attributes(generate, *, *) = {
   CKA_TOKEN = true
}
attributes(generate, CKO_CERTIFICATE, *) = {
   CKA_PRIVATE = false
}
attributes(generate, CKO_PUBLIC_KEY, *) = {
   CKA_PRIVATE = false
}
attributes(*, CKO_SECRET_KEY, *) = {
   CKA_PRIVATE = false
   CKA_EXTRACTABLE = false
}

    Notes regarding the configuration file:

    • The format is described in the Java PKCS#11 Reference Guide.

    • The library must point to the SoftHSM libsofthsm2.so library.

    • The slot must be one obtained when initializing the device.

    • You can find configuration recommendations for production deployments in the platform documentation page, HSMs and ForgeRock software.

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

    The following example shows how you can use the Java keytool command to list the SoftHSM keys:

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

Your keystore contains 0 entries

Store keys for securing connections

The following examples use SoftHSM to store the TLS keys for securing network connections (LDAPS, HTTPS, and so on). Adapt them to your HSM.

Generate a TLS key pair for securing connections

This is the server key pair for securing TLS connections. It can be specific to one DS server, and does not need to be shared.

DS presents the certificate to client applications, so get it signed by a CA they trust. This example is for evaluation only, and uses localhost as the hostname and a self-signed certificate:

  1. Generate a TLS key pair.

    The following example generates a key pair with the alias ssl-key-pair:

    $ keytool \
 -genkeypair \
 -alias ssl-key-pair \
 -keyalg EC \
 -groupname secp521r1 \
 -ext "san=dns:localhost" \
 -dname "CN=localhost,O=Example Corp,C=FR" \
 -keystore NONE \
 -storetype PKCS11 \
 -storepass password \
 -providerClass sun.security.pkcs11.SunPKCS11 \
 -providerArg /path/to/hsm.conf

    The keystore password is the user PIN.

  2. Get the public key certificate signed.

    The following example self-signs the certificate:

    $ keytool \
 -selfcert \
 -alias ssl-key-pair \
 -keystore NONE \
 -storetype PKCS11 \
 -storepass password \
 -providerClass sun.security.pkcs11.SunPKCS11 \
 -providerArg /path/to/hsm.conf

    Refer to your HSM documentation for details on getting the certificate signed by a CA.

Create a PKCS#11 key manager provider

Repeat these steps for each DS server:

  1. Make the plaintext PIN available to the DS server.

    With SoftHSM, this is the user PIN set when initializing the slot where you stored the keys, softhsm2-util --pin password.

    The following example sets the PIN in an environment variable:

    $ export SOFTHSM_USER_PIN=password

    The value must be accessible every time the DS server starts.

  2. Create the PKCS#11 key manager provider configuration.

    The following example creates a provider for SoftHSM:

    • 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 SOFTHSM_USER_PIN environment variable to get the PIN.

      DS key manager providers also support storing the PIN in the configuration, in a file, or in a Java property.

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

Use the PKCS#11 key manager provider

  1. Set a connection handler or authorization mechanism to use the PKCS#11 key manager provider.

    The following example configures the LDAPS connection handler to use the SoftHSM provider:

    $ dsconfig \
 set-connection-handler-prop \
 --handler-name LDAPS \
 --set listen-port:1636 \
 --set enabled:true \
 --set use-ssl:true \
 --set key-manager-provider:SoftHSM \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

  2. Verify the secure connection negotiation works with the HSM configured:

    $ ldapsearch \
 --hostname localhost \
 --port 1636 \
 --useSSL \
 --baseDN dc=example,dc=com \
 "(uid=bjensen)" \
 cn

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

Store the shared master key

Before you start

Set up DS servers without the --start option, and without any data or setup profiles that create base entries or generate data, as if you were following the instructions in Install DS for custom cases.

Do not start the DS server until you have configured it to use the shared master key in your HSM, as described below.

The setup command requires a deployment ID and password. It generates a shared master key you will discard.

However, if you start DS with any data at all, it protects secret keys for encryption with the generated shared master key, and DS must continue to use that shared master key to decrypt the data.

This procedure is therefore not intended for deployments where you are upgrading servers with encrypted data.

The shared master key is an asymmetric key pair with a self-signed certificate. Only DS uses the shared master key, and only for encrypting and decrypting secret keys. 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 in an HSM:

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

    Each server encrypts and decrypts shared secret keys with the 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 everywhere for each HSM instance DS servers access.

  • DS servers must not rely on cn=admin data.

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

  1. Generate a shared master key pair in the HSM, using RSA as the key algorithm.

    The following example generates a key pair with the alias master-key:

    $ keytool \
 -genkeypair \
 -alias master-key \
 -keyalg RSA \
 -keysize 3072 \
 -dname "CN=Master key, O=Example.com" \
 -keystore NONE \
 -storetype PKCS11 \
 -storepass password \
 -providerClass sun.security.pkcs11.SunPKCS11 \
 -providerArg /path/to/hsm.conf

    The keystore password is the user PIN.

  2. For each DS server, create the PKCS#11 key manager provider to access the HSM, as described in Create a PKCS#11 key manager provider, but without starting the server.

    For the dsconfig create-key-manager-provider command, replace the connection parameters with --offline.

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

    For example, set the key manager provider to SoftHSM using the default alias for the key pair, master-key:

    $ dsconfig \
 set-crypto-manager-prop \
 --set key-manager-provider:SoftHSM \
 --offline \
 --no-prompt

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

  5. Start each DS server.