Directory Services 7.2.5

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.

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.