PingDS 7.5.1

Key management

Update keys

When you update keys, DS servers load them and begin using them for new connections. This section covers common rotation operations, such as renewing and replacing keys.

Renew a TLS certificate

  1. Choose the appropriate method to renew an expiring certificate:

    1. If the certificate depends on a deployment ID and password, renew it with the dskeymgr command:

      $ dskeymgr \
 create-tls-key-pair \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --keyStoreFile /path/to/opendj/config/keystore \
 --keyStorePassword:file /path/to/opendj/config/keystore.pin \
 --hostname localhost \
 --hostname ds.example.com \
 --subjectDn CN=DS,O=ForgeRock

      For more command options, refer to dskeymgr. The default validity for the certificate is one year.

    2. If you use a CA, renew the CA signature:

      • Create a certificate signing request.

      • Have the request signed by the CA you use.

      • Import the signed certificate from the CA reply.

    3. If you used a self-signed certificate, sign it again, and distribute the new certificate as appropriate.

      Have each server and client application that trusted the old certificate import the renewed certificate.

      For details, refer to Trust a server certificate.

Replace a TLS key pair

  1. Choose the appropriate method to replace or rotate a key pair used for secure communications:

    1. If the certificate depends on a deployment ID and password, use the dskeymgr command:

      $ dskeymgr \
 create-tls-key-pair \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --keyStoreFile /path/to/opendj/config/keystore \
 --keyStorePassword:file /path/to/opendj/config/keystore.pin \
 --hostname localhost \
 --hostname ds.example.com \
 --subjectDn CN=DS,O=ForgeRock

      The default validity for the certificate is one year.

    2. If you provided your own keys in the server keystore, do the following:

      • Generate a new key pair in the server keystore with a new alias.

      • If you use a CA, get the certificate signed by the CA.

      • If you use a self-signed certificate, distribute the certificate for import by all servers and clients that trust your server.

      • Once the old key pair is no longer used anywhere, delete the keys using the keytool -delete command with the old alias.

Retire secret keys

You do not need to retire secret keys for the following, because encryption is only performed once per key:

  • Backup uses a new secret key for each file.

  • Confidential replication changelog backends use a new secret key for each file.

You can retire secret keys for confidential database backends:

  1. Change the cipher-key-length property for the backend.

    Each time you change the setting, the server generates a new secret key. After you retire the key, DS servers will only use that key for decryption, not for encryption.

    The server keeps the retired key in the backend indefinitely for decryption.

Replace deployment IDs

Follow these steps if you must:

  • Renew an expiring deployment ID-based CA.

    The default validity period is 10 years.

  • Replace a lost or compromised deployment ID password.

  1. Generate a new deployment ID with a new password:

    $ dskeymgr \
 create-deployment-id \
 --outputFile new.deployment.id \
 --deploymentIdPassword password

    For more command options, refer to dskeymgr. The default validity for the deployment ID is 10 years.

  2. On each server, add the new shared master key:

    $ dskeymgr \
 export-master-key-pair \
 --alias new-master-key \
 --deploymentId "$(<new.deployment.id)" \
 --deploymentIdPassword password \
 --keyStoreFile /path/to/opendj/config/keystore \
 --keyStorePassword:file /path/to/opendj/config/keystore.pin

    Servers continue to use the existing shared master key to decrypt existing symmetric keys. Do not overwrite a shared master key that is already in use.

  3. On each server that uses the deployment ID and password for PKI, add the new CA certificate:

    $ dskeymgr \
 export-ca-cert \
 --alias new-ca-cert \
 --deploymentId "$(<new.deployment.id)" \
 --deploymentIdPassword password \
 --keyStoreFile /path/to/opendj/config/keystore \
 --keyStorePassword:file /path/to/opendj/config/keystore.pin

    Also distribute the new CA certificate to any client applications that rely on the old CA certificate.

  4. On each server that uses the deployment ID and password for PKI, renew the key pair used for secure communications.

    Before completing this step, make sure you have added the new CA certificate on all servers. Any peer servers missing the new CA certificate will not trust the new keys:

    $ dskeymgr \
 create-tls-key-pair \
 --deploymentId "$(<new.deployment.id)" \
 --deploymentIdPassword password \
 --keyStoreFile /path/to/opendj/config/keystore \
 --keyStorePassword:file /path/to/opendj/config/keystore.pin \
 --hostname localhost \
 --hostname ds.example.com \
 --subjectDn CN=DS,O=ForgeRock

    For more command options, refer to dskeymgr. The default validity for the certificate is one year.

    Also renew any client application key pairs that were generated using the old deployment ID and password.

  5. On each server, update the master key alias to use the new key:

    $ dsconfig \
 set-crypto-manager-prop \
 --set master-key-alias:new-master-key \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

  6. Stop trusting the old CA certificate by removing all references to it.

    For example, remove the old CA certificate from all client and server truststores.

  7. When installing a new server after replacing deployment IDs:

    • Use the new deployment ID and password to set up the server, and do not start the server at setup time.

    • Copy the keystore and PIN from an existing server, overwriting the existing keystore and PIN.

      This adds the older shared master key to the new server’s keystore.

    • Renew the local key pair used for secure communications using the new deployment ID and password.

    • Start the server.

Use new keys

Generate a key pair (wildcard certificate)

A wildcard certificate uses a * to replace the leading subdomain. The wildcard hostname appears in the certificate’s list of subject alternative names:

  1. Generate a key pair with a wildcard certificate:

    $ dskeymgr \
 create-tls-key-pair \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --hostname localhost \
 --hostname "*.example.com" \
 --subjectDn CN=DS,CN=Example,CN=com \
 --keyStoreFile /path/to/opendj/config/keystore \
 --keyStorePassword:file /path/to/opendj/config/keystore.pin

    For more command options, refer to dskeymgr. The default validity for the certificate is one year.

Generate a key pair (CA-signed certificate)

  1. Generate a server key pair in the existing server keystore.

    Many client applications will check that the server’s DNS name in the certificate matches the server hostname.

    Find the hostname for the server in the status command output. When creating the key pair, set it as a DNSName in the certificate’s SubjectAlternativeName list. If the server can respond on multiple FQDNs, use multiple subject alternative names.

  2. Create a certificate signing request .csr file for the generated certificate.

  3. Have the CA sign the request in the .csr file.

    Refer to the instructions from your CA on how to provide the request.

    The CA returns the signed certificate, for example, in a .crt file.

  4. If you have set up your own CA and signed the certificate, or are using a CA whose certificate is not included in the Java runtime environment, import the CA certificate into the DS keystore and truststore so that it can be trusted.

    For an example command, refer to Trust a CA certificate.

  5. Import the signed certificate, such as the .crt file, from the CA reply into the keystore where you generated the key pair.

  6. If you use a CA certificate that is not known to clients, such as a CA that you set up yourself rather than a well-known CA, import the CA certificate into the client application truststore. For an example command, refer to Trust a CA certificate.

    Otherwise, the client application cannot trust the signature on the server certificate.

Generate a key pair (self-signed certificate)

  1. Generate a server key pair in the existing server keystore.

    The certificate is considered self-signed, because the issuer DN and subject DN are the same.

    Many client applications will check that the server’s DNS name in the certificate matches the server hostname.

    Find the hostname for the server in the status command output. When creating the key pair, set it as a DNSName in the certificate’s SubjectAlternativeName list.

Use an alternative keystore type

To use an alternative keystore implementation, start with a different keystore type when generating the keypair.

When generating a key pair for TLS with the keytool command, set the -keyalg option to EC or RSA for compatibility with TLSv1.3.

The -keyalg DSA option is not compatible with TLSv1.3.

  1. Use one of the keystore types supported by the Java runtime environment:

    Java Keystore

    The basic Java keystore type is JKS:

    $ keytool \
 -genkeypair \
 -keyalg EC \
 -alias new-keys \
 -ext "san=dns:ds.example.com" \
 -dname "CN=ds.example.com,O=Example Corp,C=FR" \
 -keystore /path/to/new-keystore.jks \
 -storetype JKS \
 -storepass:env KEYSTORE_PASSWORD \
 -keypass:env KEYSTORE_PASSWORD

    This is the keystore type if you do not specify a -storetype option.

    Java Cryptography Extension Keystore

    The JCEKS type implements additional Java cryptography extensions and stronger protection for private keys:

    $ keytool \
 -genkeypair \
 -keyalg EC \
 -alias new-keys \
 -ext "san=dns:ds.example.com" \
 -dname "CN=ds.example.com,O=Example Corp,C=FR" \
 -keystore /path/to/new-keystore.jceks \
 -storetype JCEKS \
 -storepass:env KEYSTORE_PASSWORD \
 -keypass:env KEYSTORE_PASSWORD
    PKCS#11 device

    A PKCS#11 device, such as an HSM, can be used as a keystore.

    For details, refer to PKCS#11 hardware security module.

    PKCS#12 Keystore

    The PKCS12 type lets you use a PKCS#12 format file. This is the default for DS servers. It is a standard format and is interoperable with other systems that do not use Java:

    $ keytool \
 -genkeypair \
 -keyalg EC \
 -alias new-keys \
 -ext "san=dns:ds.example.com" \
 -dname "CN=ds.example.com,O=Example Corp,C=FR" \
 -keystore /path/to/new-keystore \
 -storetype PKCS12 \
 -storepass:env KEYSTORE_PASSWORD \
 -keypass:env KEYSTORE_PASSWORD

  2. After setting up an alternate keystore type, make sure that you configure:

    • A key manager provider to open the correct keystore with the correct credentials.

    • Any components using the key manager provider to use the correct certificate alias.

Add a new keystore

These steps demonstrate adding a new PKCS#12 keystore with existing server keys. Follow these steps if you have existing keys in a PKCS#12 keystore:

  1. Create a Key Manager Provider that references your keystore:

    $ dsconfig \
 create-key-manager-provider \
 --provider-name MyKeystore \
 --type file-based \
 --set enabled:true \
 --set key-store-file:/path/to/keystore \
 --set key-store-pin:password \
 --set key-store-type:PKCS12 \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

  2. For each configuration object that needs to use the keys in the keystore, update the key-manager-provider and ssl-cert-nickname properties:

    $ dsconfig \
 set-connection-handler-prop \
 --handler-name LDAPS \
 --set key-manager-provider:MyKeystore \
 --set ssl-cert-nickname:ssl-key-pair \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

    Many configuration objects use key manager providers. For a full list, refer to the page of configuration properties that start with K, and review the key-manager-provider properties links.

    Do not update the key manager provider for the Crypto Manager. The Crypto Manager needs access to the shared master key.

Generate a test deployment ID

  1. Use the dskeymgr command to generate a deployment ID for testing.

    This example records the deployment ID in a file:

    $ dskeymgr \
 create-deployment-id \
 --deploymentIdPassword password \
 --outputFile test.deployment.id

    If you do not specify the deployment ID password or file containing the password, the tool prompts you for the password interactively.

    Use this deployment ID when setting up test servers. The test servers trust each others' certificates.

Trust certificates

Trust a client certificate

These steps let the DS server trust a self-signed client application certificate:

If you control the application, issue the client a certificate from a private CA instead.

For an example, refer to Certificate-based authentication.

  1. Import the self-signed client certificate.

    The following example imports the client certificate into the default truststore:

    $ keytool \
 -import \
 -trustcacerts \
 -alias myapp-cert \
 -file myapp-cert.pem \
 -keystore /path/to/opendj/config/keystore \
 -storepass:file /path/to/opendj/config/keystore.pin \
 -storetype PKCS12 \
 -noprompt

Certificate was added to keystore

    If the truststore was provided during the setup process, specify the truststore and password.

Trust a server certificate

These steps let a client trust the DS server.

If the server certificate was signed by a well-known CA, the client may not have to configure any further trust.

To trust a certificate signed using a deployment ID and password, get the CA certificate. Either:

  • Copy the server’s truststore file and PIN.

  • Export the CA certificate as a PEM format file, as described in PEM format keys.

For an unknown CA or a self-signed server certificate, follow these steps:

  1. Export the CA certificate from its truststore or the server certificate from the server keystore.

    You can export the certificate in PEM format using the keytool -exportcert -rfc command.

    Some client applications can use the PEM format directly.

  2. If the client uses a Java truststore, import the certificate into the client truststore.

    You can import the server certificate using the keytool -import -trustcacerts command.

Trust a CA certificate

These steps let the DS server trust a CA. If the CA’s certificate is included with Java, you can let the server use the JVM truststore.

If the CA is not well-known, you can import the trusted CA certificate into a truststore:

  1. Import the certificate as a CA certificate.

    The following example imports the CA certificate into the default truststore:

    $ keytool \
 -import \
 -trustcacerts \
 -alias my-ca-cert \
 -file ca.pem \
 -keystore /path/to/opendj/config/keystore \
 -storepass:file /path/to/opendj/config/keystore.pin \
 -storetype PKCS12 \
 -noprompt

Certificate was added to keystore

    If the truststore was provided during the setup process, specify the truststore and password.

  2. If no trust manager provider is configured to access the truststore, create one.

    For reference, refer to create-trust-manager-provider.

    Also, configure connection handlers to use the new trust manager provider.

Add a new truststore

These steps demonstrate adding a new PKCS#12 truststore with existing trusted certificates. Follow these steps if you have existing certificates in a PKCS#12 truststore:

  1. Create a Trust Manager Provider that references your truststore:

    $ dsconfig \
 create-trust-manager-provider \
 --provider-name MyTruststore \
 --type file-based \
 --set enabled:true \
 --set trust-store-file:/path/to/truststore \
 --set trust-store-pin:password \
 --set trust-store-type:PKCS12 \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

  2. For each configuration object that needs to trust the certificates in the truststore, update the trust-manager-provider property:

    $ dsconfig \
 set-connection-handler-prop \
 --handler-name LDAPS \
 --set trust-manager-provider:MyTruststore \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

    Many configuration objects use trust manager providers. For a full list, refer to the page of configuration properties that start with T, and review the trust-manager-provider properties links.

Show deployment ID information

The dskeymgr show-deployment-id command displays key information about a given deployment ID, such as the expiration date for the derived CA certificate:

$ dskeymgr show-deployment-id ASIQ8nH5BypHIB7AmmmJZ5VfCVKZXg5CBVN1bkVDAIT3myJF1rRsipI
Not before: 2024-03-15T06:42:38Z
Not after: 2034-03-13T06:42:38Z
Version: 1
Serial number: 84F79B2245D6B46C8A92
Provider name: SunEC

If you depend on an expiring deployment ID CA, refer to Replace deployment IDs.

PEM format keys

DS servers can read keys and trusted certificates from files that contain keys in Privacy-Enhanced Mail (PEM) format:

  1. Choose or create a directory for PEM format keys.

    This example uses /path/to/opendj/pem:

    $ mkdir -p /path/to/opendj/pem

  2. Use the dskeymgr command to generate PEM format keys.

    • Add a master key using the deployment ID and password, even if you have your own CA and server keys:

      $ dskeymgr \
 export-master-key-pair \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --outputFile /path/to/opendj/pem/master-key.pem

    • Add a trusted CA certificate.

      This example exports a deployment ID CA certificate:

      $ dskeymgr \
 export-ca-cert \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --outputFile /path/to/opendj/pem/ca-cert.pem

    • Add server keys.

      This example exports a server key pair based on a deployment ID:

      $ dskeymgr \
 create-tls-key-pair \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --hostname localhost \
 --hostname ds.example.com \
 --subjectDn CN=DS,O=ForgeRock \
 --outputFile /path/to/opendj/pem/ssl-key-pair.pem

      For more command options, refer to dskeymgr. The default validity for the certificate is one year.

  3. Allow only the user running the server to read any PEM files that contain private keys.

    The keys are not encrypted, so you must protect the PEM files. For example, if the server runs with user ID opendj, restrict access to that user:

    $ sudo chown opendj /path/to/opendj/pem/*.pem && \
  sudo chmod 600 /path/to/opendj/pem/master-key.pem && \
  sudo chmod 600 /path/to/opendj/pem/ssl-key-pair.pem

  4. Configure a PEM key manager provider for the master key and server keys:

    $ dsconfig \
 create-key-manager-provider \
 --provider-name PEM \
 --type pem \
 --set enabled:true \
 --set pem-directory:/path/to/opendj/pem \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

  5. Configure a PEM trust manager provider for trusted certificates, such as CA certificates:

    $ dsconfig \
 create-trust-manager-provider \
 --provider-name PEM \
 --type pem \
 --set enabled:true \
 --set pem-directory:/path/to/opendj/pem \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

  6. Configure other components to use the new providers by setting their key-manager-provider and trust-manager-provider properties.

    When using PEM keys, the alias or ssl-cert-nickname property is filename of the key. In this example:

    • The master key alias is master-key.pem.

    • The CA certificate alias is ca-cert.pem.

    • The TLS keys alias is ssl-key-pair.pem.

Notice that the PEM key manager provider, and the PEM trust manager provider share the same pem-directory. This works because the key manager provider loads key pairs, and the trust manager provider loads trusted certificates. When the PEM files change, the server regularly reloads the files. For details, refer to Pem Key Manager Provider and Pem Trust Manager Provider.