PingDS 8.0.0

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. 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 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

--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

  • 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 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.

Example

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 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:

    $ /path/to/opendj/setup \
 --serverId own-keys \
 --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 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 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 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 and Trust Manager Provider 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 to learn about using variables instead in the DS configuration.

  3. Finish configuring the server.

  4. Start the server:

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