PingDS

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. Install the server files.

  2. Generate a deployment ID unless you already have one:

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

    About deployment IDs

    A deployment ID is a random string generated using the dskeymgr command. It is 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 are 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.

  3. Set the deployment ID as the value of the environment variable, DEPLOYMENT_ID:

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

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

  5. Finish configuring the server.

  6. Start the server:

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