PingDS 7.5.1

Use your own cryptographic keys

When you set up a DS server with your own keys for PKI, account for the following points:

  • You must also use a deployment ID and password.

    Some DS features depend on the shared master key generated from the deployment ID and password. 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 hardware security module.

  • Make sure AM, IDM, and all other client applications can trust DS certificates.

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

For…​ Use…​

Keystores containing server key pairs

--useJavaKeyStore
--useJceKeyStore
--usePkcs11KeyStore
--providerArg (for PKCS#11)
--providerClass or
--providerName (for PKCS#11)
--usePkcs12KeyStore
-W, --keyStorePassword[:env|:file]
-N, --certNickname

Truststores containing trusted CA or self-signed certificates

--useJavaTrustStore
--useJceTrustStore
--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 read PKCS#11 hardware security module.

  • If you are using PEM format keys, read PEM format 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))

    (1) Replication requires both TLS server and TLS client roles.

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

  1. Before proceeding, install the server files.
    For details, refer to 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, refer to Property value substitution.