--- title: PKCS#11 HSM description: "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." component: pingds version: 8.1 page_id: pingds:security-guide:pki-hsm canonical_url: https://docs.pingidentity.com/pingds/8.1/security-guide/pki-hsm.html revdate: 2026-02-12T14:50:39Z keywords: ["Features", "LDAP", "Security", "Setup & Configuration", "Standards"] section_ids: pki-hsm-prepare: Prepare the HSM and keys pki-hsm-create-provider: Let DS access the HSM pki-hsm-use-provider: Use the keys in the HSM hsm-shared-master-key: Store shared master keys in the HSM --- # 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](https://github.com/harrison314/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: ```ini name = BouncyHsm library = /path/to/BouncyHsm.Pkcs11.so slot = 1 ``` Learn about the configuration file format in the [Java PKCS#11 Reference Guide](https://docs.oracle.com/en/java/javase/25/security/pkcs11-reference-guide.html). Find recommendations for production deployments in the platform documentation page, [HSMs and platform software](https://docs.pingidentity.com/platform/8.1/platform-guide/hsm-support.html). 8. Verify Java can access the device using your configuration. The following example uses the Java `keytool` command to list the keys: ```console $ 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): ``` 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: ```console $ 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. ```console $ 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: ```console $ 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: ```console $ 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 : 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](../install-guide/custom-replica.html). 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](../install-guide/fips.html), 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 ``: ```console $ dsconfig \ set-crypto-manager-prop \ --set key-manager-provider: \ --set master-key-alias: \ --offline \ --no-prompt ``` The following example for FIPS compliance uses separate keys for key wrapping and signing backups: ```console $ dsconfig \ set-crypto-manager-prop \ --set key-manager-provider: \ --set master-key-alias: \ --set signing-key-alias: \ --offline \ --no-prompt ``` 5. For each DS server, apply [Setup profiles](../install-guide/setup-profiles.html) 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.