--- title: PKCS#11 hardware security module description: 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. component: pingds version: 7.4 page_id: pingds:security-guide:pki-hsm canonical_url: https://docs.pingidentity.com/pingds/8.1/security-guide/pki-hsm.html llms_txt: https://docs.pingidentity.com/pingds/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2025-07-07T12:40:27Z keywords: ["Features", "LDAP", "Security", "Setup & Configuration", "Standards"] superseded_by: https://docs.pingidentity.com/pingds/8.1/security-guide/pki-hsm.html section_ids: pki-hsm-prepare: Prepare the HSM store_keys_for_securing_connections: Store keys for securing connections generate_a_tls_key_pair_for_securing_connections: Generate a TLS key pair for securing connections pki-hsm-create-provider: Create a PKCS#11 key manager provider pki-hsm-use-provider: Use the PKCS#11 key manager provider hsm-shared-master-key: Store the shared master key --- # 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](https://opendnssec.readthedocs.io/en/latest/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: ```bash $ 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 ``` * The user PIN is the one the DS server needs to access the device. * The SO PIN is to reinitialize the token. * The \ 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 \ 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: ```ini name = SoftHSM library = /usr/local/lib/softhsm/libsofthsm2.so slot = 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](https://docs.oracle.com/en/java/javase/17/security/pkcs11-reference-guide.html). * 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, [HSM support](https://docs.pingidentity.com/platform/8/platform-guide/hsm-support.html). 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: ```bash $ 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`: ```bash $ 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: ```bash $ 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: ```bash $ 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. ```bash $ 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: ```bash $ 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: ```bash $ 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 : 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](../install-guide/custom-replica.html). 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`: ```bash $ 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](#pki-hsm-create-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`: ```bash $ dsconfig \ set-crypto-manager-prop \ --set key-manager-provider:SoftHSM \ --offline \ --no-prompt ``` 4. For each DS server, apply [Setup profiles](../install-guide/setup-profiles.html) with the `setup-profile` command, and complete any necessary preliminary configuration. 5. Start each DS server.