PingDS

Install with existing cryptographic keys

When you set up a DS server with your own keys for PKI, you must still use a deployment ID and password.

In this case, the deployment ID and password generate the shared master key used to protect secret keys for encrypted data, such as backup files. If you have not yet learned about deployment IDs, read Deployment IDs.

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, see PKCS#11 hardware security module.

The setup command has options to simplify setting up a server with existing keys:

For…​ Use…​

Keystores containing server key pairs

--useJavaKeyStore
--useJceKeyStore
--usePkcs11KeyStore
--usePkcs12KeyStore
-W, --keyStorePassword[:env|:file]
-N, --certNickname

Truststores containing trusted CA or self-signed certificates

--useJavaTrustStore
--useJceTrustStore
--usePkcs11TrustStore
--usePkcs12TrustStore
-T, --trustStorePassword[:env|:file]

Important features to be aware of:

  • 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 does not support separate keystore and key passwords in keystore files.

  • If you are using an HSM, also see PKCS#11 hardware security module.

  • If you are using PEM format keys, see PEM format keys instead.

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:

Example

Follow steps similar to these to install a DS replica with existing cryptographic keys:

  1. Before proceeding, install the server files.
    For details, see Unpack files.

  2. Run the setup command with the appropriate options.

    The following example uses a PKCS#12 keystore file with the server’s key pair, and a PKCS#12 truststore file with the CA’s certificate.

    This example installs the server with the evaluation setup profile. Adapt the command for your use:

    # Set up a directory server for evaluation using existing keys:
$ /path/to/opendj/setup \
 --serverId evaluation-only \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --usePkcs12TrustStore /path/to/truststore \
 --trustStorePassword password \
 --certNickname ssl-key-pair \
 --usePkcs12KeyStore /path/to/keystore \
 --keyStorePassword password \
 --rootUserDN uid=admin \
 --rootUserPassword password \
 --monitorUserPassword password \
 --hostname localhost \
 --adminConnectorPort 4444 \
 --ldapPort 1389 \
 --enableStartTls \
 --ldapsPort 1636 \
 --httpsPort 8443 \
 --replicationPort 8989 \
 --bootstrapReplicationServer localhost:8989 \
 --profile ds-evaluation \
 --acceptLicense

  3. Finish configuring the server.

  4. Start the server:

    $ /path/to/opendj/bin/start-ds

When you set up the server to use existing keystore files, the server configuration directly references those files. If you read the server configuration, you find that a Key Manager Provider references the keystore, and that a Trust Manager Provider references the truststore.

If you provide keystore and truststore passwords as strings, the setup command records them in files in the opendj/config directory.

For details on using variables instead, see Property value substitution.