--- title: Use your own cryptographic keys description: When you set up a DS server with your own keys for PKI, account for the following points: component: pingds version: 8.1 page_id: pingds:install-guide:setup-own-keys canonical_url: https://docs.pingidentity.com/pingds/8.1/install-guide/setup-own-keys.html revdate: 2026-01-28T18:16:26Z keywords: ["Install", "LDAP", "Security", "Setup & Configuration"] section_ids: setup_options: Setup options important_features: Important features replication_and_tls: Replication and TLS client_operations_and_tls: Client operations and TLS example: Example --- # Use your own cryptographic keys | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When you set up a DS server with your own keys for PKI, account for the following points:- Use a deployment ID and password. Some DS features depend on the shared master key generated from the [deployment ID and password](../security-guide/pki.html#about-deployment-ids). For example, the `dsbackup` command depends on the shared master key for encryption. - If you plan to store the shared master key in an HSM, read the documentation carefully *before you install DS*. When you set up the server, you must avoid accidentally encrypting data while using the wrong shared master key. For details, refer to [PKCS#11 HSM](../security-guide/pki-hsm.html). - Make sure AM, IDM, and all other client applications can trust DS server certificates. Learn about trusting server certificates in the documentation for each client application. | ## Setup options The `setup` command has options to simplify setting up a server with existing keys: | For | Use | | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Keystores containing server key pairs | `--keyStorePath` `--keyStoreType` `-W, --keyStorePassword[:env\|:file]` `--keyStoreProviderName` (for PKCS#11) `--keyStoreProviderArg` (for PKCS#11) `--keyStoreProviderClass` (for FIPS) `-N, --certNickname` | | Truststores containing trusted CA or self-signed certificates | `--trustStorePath` `--trustStoreType` `-T, --trustStorePassword[:env\|:file]` `--trustStoreProviderName` (for PKCS#11) `--trustStoreProviderArg` (for PKCS#11) `--trustStoreProviderClass` (for FIPS) | ## Important features * If the keystore file that holds the server key pair protects the server key with a password, that password must match the password for the entire store. DS doesn't support accessing a keystore and accessing keystore entries with separate passwords. * If you are using an HSM, also read [PKCS#11 HSM](../security-guide/pki-hsm.html). * If you are using PEM format keys, read [PEM format keys](../security-guide/key-management.html#use-pem-keys). * CAs can optionally set X.509 key usage extensions in server certificates. If the CA does set key usage extensions, make sure it includes at least the required settings: | Protocol | X.509 extension | Required settings | | ----------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP | `KeyUsage` | `digitalSignature` `keyEncipherment` | | | `ExtendedKeyUsage` | `serverAuth` (TLS server authentication) | | LDAP | `KeyUsage` | `digitalSignature` `keyEncipherment` | | | `ExtendedKeyUsage` | `serverAuth` (TLS server authentication) | | Replication | `KeyUsage` | `digitalSignature` `keyEncipherment` | | | `ExtendedKeyUsage` | `clientAuth` (TLS client authentication)(1) `serverAuth` (TLS server authentication) `1.3.6.1.4.1.36733.2.1.10.1` (for [Trusted replicas (advanced)](../config-guide/repl-trusted.html)) | (1) Replication requires both TLS server and TLS client roles. ### Replication and TLS Public CAs sign certificates for public networks where servers and client applications are separate entities. By default, these CAs issue separate certificates for servers and client applications. This makes sense in a network of web servers and web browsers. In contrast, replication traffic is peer-to-peer. In replication, each server plays both client and server roles using the same certificate for mutual TLS (mTLS) authentication. Whether it's requesting or responding, it's still the same server. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For replication, ask your CA for an mTLS certificate for server-to-server authentication, not a web server certificate.Work with your CA to make sure the replication certificate has `clientAuth` and `serverAuth` in its `ExtendedKeyUsage`. | ### Client operations and TLS Make sure certificates have the `clientAuth` extension when the server acts as a client *and the remote server requires certificate-based client authentication for TLS*. This can arise when DS acts as: * An [LDAP proxy](../config-guide/proxy.html), a client of remote LDAP servers. * An [OpenTelemetry](../monitoring-guide/opentelemetry.html) client, pushing data to a remote OTLP endpoint. * A client of IDM for [password synchronization](https://docs.pingidentity.com/pingidm/8.1/pwd-plugin-guide/chap-sync-dj.html). ## Example Follow steps similar to these to install a DS replica with existing cryptographic keys: 1. [Install the server files](install-files.html). 2. Generate a deployment ID unless you already have one: ```console $ /path/to/opendj/bin/dskeymgr create-deployment-id --deploymentIdPassword password your-deployment-id ``` Save the deployment ID and its deployment password. Keep the ID and the password safe, and keep the password secret. Use the same deployment ID and password for all the servers in the same environment. > **Collapse: About deployment IDs** > > A *deployment ID* is a random string generated using the `dskeymgr` command. It's a deployment identifier, not a key, but it is used with a password to generate keys. > > A *deployment ID password* is a secret string at least 8 characters long that you choose. > > The two form a pair. You must have the deployment ID password to use the deployment ID. > > Each deployment requires a *single, unique deployment ID and its password*. DS uses the pair to: > > * Protect the keys to encrypt and decrypt backup files and directory data. > > * Generate the TLS key pairs to protect secure connections, unless you provide your own. > > Store your deployment ID and password in a safe place, and reuse them when configuring other servers in the same deployment. > > The DS `setup` and `dskeymgr` commands use the pair to generate the following: > > * (Required) A shared master key for the deployment. > > DS replicas share secret keys for data encryption and decryption. DS servers encrypt backend data, backup files, and passwords, and each replica must be able to decrypt data encrypted on another peer replica. > > To avoid exposing secret keys, DS servers encrypt secret keys with a shared master key. DS software uses a deployment ID and its password to derive the master key. > > * (Optional) A private PKI for trusted, secure connections. > > A PKI serves to secure network connections from clients and other DS servers. The PKI is a trust network, requiring trust in the CA that signs public key certificates. > > Building a PKI can be complex. You can use self-signed certificates, but you must distribute each certificate to each server and client application. You can pay an existing CA to sign certificates, but that has a cost, and leaves control of trust with a third party. You can set up a CA or certificate management software, but that can be a significant effort and cost. As a shortcut to setting up a private CA, DS software uses deployment IDs and passwords. > > DS software uses the deployment ID and its password to generate key pairs without storing the CA private key. > > Learn more in [Deployment IDs](../security-guide/pki.html#about-deployment-ids). 3. Set the deployment ID as the value of the environment variable, `DEPLOYMENT_ID`: ```console $ export DEPLOYMENT_ID=your-deployment-id ``` Examples in the documentation show this environment variable as a reminder to use your own deployment ID. 4. Run the `setup` command with the appropriate options. The example command uses these keys: * A CA certificate with alias `ca-cert` in a `truststore` file. You provide this. * A server key pair with alias `ssl-key-pair` in a `keystore` file. You provide this. * A shared master key with alias `master-key`. You don't provide this directly. It's based on the deployment ID and password. The example has your keys in separate PKCS#12 truststore and keystore files for emphasis. Use a single store file for all your keys if it's easier to deploy and manage. Set up a directory server using your own keys. Adapt the command for your use: ```console $ /path/to/opendj/setup \ --serverId own-keys \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --trustStorePath /path/to/truststore \ --trustStoreType PKCS12 \ --trustStorePassword password \ --certNickname ssl-key-pair \ --keyStorePath /path/to/keystore \ --keyStoreType PKCS12 \ --keyStorePassword password \ --rootUserDN uid=admin \ --rootUserPassword password \ --monitorUserPassword password \ --hostname localhost \ --adminConnectorPort 4444 \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --httpsPort 8443 \ --replicationPort 8989 \ --bootstrapReplicationServer rs1.example.com:8989 \ --bootstrapReplicationServer rs2.example.com:8989 \ --acceptLicense ``` **Uses of keys in the example** | Store | Key | Uses | | --------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/path/to/keystore` | `ssl-key-pair` | Server key pair presented to client applications when establishing a secure TLS connection as a server.The connectors for administration, HTTP, LDAP, and replication use this through the [Key Manager Provider](../configref/objects-key-manager-provider.html) configuration.Include one key pair for all secure TLS connections. | | `/path/to/truststore` | `ca-cert` | CA certificate to trust other server certificates:- When establishing a TLS connection as a client. Replication uses mTLS. For the server certificates used for replication, always trust the CA certificate or certificates for each server if they're self-signed. - To trust client application certificates when a connector's `ssl-client-auth-policy` is `required` or `optional`.The connectors for administration, HTTP, LDAP, and replication use this through the [Trust Manager Provider](../configref/objects-trust-manager-provider.html) configuration.Trust as many CA or self-signed certificates as necessary. | | `/path/to/opendj/config/keystore` | `master-key` | Shared master key to wrap and unwrap symmetric keys for data encryption.The DS Crypto Manager uses this.All the DS servers in the deployment must share the same master key for wrapping and unwrapping symmetric keys. Provide the same deployment ID and password for each DS server in the same replicated deployment. | When DS uses existing store files, its configuration directly references the files. Don't move the files without changing any applicable [Key Manager Provider](../configref/objects-key-manager-provider.html) and [Trust Manager Provider](../configref/objects-trust-manager-provider.html) settings in the server configuration. When you provide keystore and truststore passwords as strings like this example, the `setup` command records them in `opendj/config/ssl-filename.pin` files. filename represents the name of the store file. In this example, the password files are: * `/path/to/opendj/config/ssl-keystore.pin` * `/path/to/opendj/config/ssl-truststore.pin` Read [Property value substitution](../configref/expressions.html) to learn about using variables instead in the DS configuration. 5. Finish configuring the server. 6. Start the server: ```console $ /path/to/opendj/bin/start-ds ```