Cryptographic Keys

• Choose the appropriate method to renew an expiring certificate:

  • If you set up the server with a deployment key, renew with the dskeymgr command:

    $ dskeymgr \
     create-tls-key-pair \
     --deploymentKey $DEPLOYMENT_KEY \
     --deploymentKeyPassword password \
     --keyStoreFile /path/to/opendj/config/keystore \
     --keyStorePasswordFile /path/to/opendj/config/keystore.pin \
     --hostname localhost \
     --hostname ds.example.com \
     --subjectDn CN=DS,O=ForgeRock

  • If you use a CA, renew the CA signature:

    1. Create a certificate signing request.

    2. Have the request signed by the CA you use.

    3. Import the signed certificate from the CA reply.

  • 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, see "Trust a Server Certificate".

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

  • If you set up the server with a deployment key, use the dskeymgr command:

    $ dskeymgr \
     create-tls-key-pair \
     --deploymentKey $DEPLOYMENT_KEY \
     --deploymentKeyPassword password \
     --keyStoreFile /path/to/opendj/config/keystore \
     --keyStorePasswordFile /path/to/opendj/config/keystore.pin \
     --hostname localhost \
     --hostname ds.example.com \
     --subjectDn CN=DS,O=ForgeRock

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

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

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

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

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

You can retire secret keys for confidential database backends:

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

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

   $ dskeymgr \
    create-deployment-key \
    --outputFile new.deployment.key \
    --deploymentKeyPassword password

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

   $ dskeymgr \
    export-master-key-pair \
    --alias new-master-key \
    --deploymentKey "$(<new.deployment.key)" \
    --deploymentKeyPassword password \
    --keyStoreFile /path/to/opendj/config/keystore \
    --keyStorePasswordFile /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 key for PKI, add the new CA certificate:

   $ dskeymgr \
    export-ca-cert \
    --alias new-ca-cert \
    --deploymentKey "$(<new.deployment.key)" \
    --deploymentKeyPassword password \
    --keyStoreFile /path/to/opendj/config/keystore \
    --keyStorePasswordFile /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 key 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 \
    --deploymentKey "$(<new.deployment.key)" \
    --deploymentKeyPassword password \
    --keyStoreFile /path/to/opendj/config/keystore \
    --keyStorePasswordFile /path/to/opendj/config/keystore.pin \
    --hostname localhost \
    --hostname ds.example.com \
    --subjectDn CN=DS,O=ForgeRock

   Also renew any client application key pairs that were generated using the old deployment key 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 \
    --trustStorePasswordFile /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 keys:

   1. Use the new deployment key to set up the server, and do not start the server at setup time.

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

   3. Renew the local key pair used for secure communications using the new deployment key.

   4. Start the server.

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

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

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.

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.

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, see "create-trust-manager-provider".

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

A wildcard certificate uses a * to replace the top-level subdomain in the subject FQDN. It can list domains in the subject alternative domain list:

• Generate a key pair with a wildcard certificate:

  $ dskeymgr \
   create-tls-key-pair \
   --deploymentKey $DEPLOYMENT_KEY \
   --deploymentKeyPassword password \
   --hostname localhost \
   --hostname "*.example.com" \
   --subjectDn CN=DS,CN=Example,CN=com \
   --keyStoreFile /path/to/opendj/config/keystore \
   --keyStorePasswordFile /path/to/opendj/config/keystore.pin

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.

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

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

4. (Optional) 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, see "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, see "Trust a CA Certificate".

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

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

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

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, see "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 using an alternate keystore type, make sure that you set up:

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

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

• Use the dskeymgr command to generate a deployment key for testing.

  This example records the deployment key in a file:

  $ dskeymgr \
   create-deployment-key \
   --deploymentKeyPassword password \
   --outputFile test.deployment.key

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

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

Applications like DS servers that can use a PKCS#12 truststore can use the config/keystore and config/keystore.pin from a test server set up with the deployment key.

• For applications that require a PEM format certificate, use the dskeymgr command:

  $ dskeymgr \
   export-ca-cert \
   --deploymentKey $DEPLOYMENT_KEY \
   --deploymentKeyPassword password \
   --outputFile ca-cert.pem

The procedures uses the sun.security.pkcs11.SunPKCS11 provider implementation with SoftHSM. If you use a different Java implementation, see the documentation for details on how to use PKCS#11 devices with your JVM:

1. Install SoftHSM, including the configuration and the SOFTHSM2_CONF environment variable.

   For details, see the SoftHSM documentation, using the following hints:

   • Make sure you can write tokens to SoftHSM:

     $ cat $SOFTHSM2_CONF
     # SoftHSM v2 configuration file
     
     # You must be able to write to the token dir when initializing the device:
     directories.tokendir = /path/to/softhsm/tokens
     objectstore.backend = file
     
     # ERROR, WARNING, INFO, DEBUG
     log.level = INFO

   • Keep track of the PINs that you enter when initializing the device:

     $ softhsm2-util --init-token --slot 0 --label "My token 1"
     *** SO PIN (4-255 characters) ***
     Please enter SO PIN:
     Please reenter SO PIN:
     *** User PIN (4-255 characters) ***
     Please enter user PIN:
     Please reenter user PIN:
     The token has been initialized.

     The SO PIN is to reinitialize the token.

     The user PIN is the one the DS server needs to access the device.

2. Generate a key pair on the device:

   1. To use the Java keytool command with the device, create a PKCS#11 configuration file that is used by the security provider implementation:

      $ cat /path/to/softhsm/hsm.conf
      name = SoftHSM
      library = /path/to/softhsm/2.0.0/lib/softhsm/libsofthsm2.so
      slot = 0
      attributes(generate, *, *) = {
         CKA_TOKEN = true
      }
      attributes(generate, CKO_CERTIFICATE, *) = {
         CKA_PRIVATE = false
      }
      attributes(generate, CKO_PUBLIC_KEY, *) = {
         CKA_PRIVATE = false
      }
      attributes(*, CKO_SECRET_KEY, *) = {
         CKA_PRIVATE = false
      }

      Notes regarding the configuration file:

      • The format is described in the Java PKCS#11 Reference Guide.

      • The library must point to the SoftHSM libsofthsm2.so library.

      • The slot must be one used when initializing the device.

   2. Using the configuration file, generate the key pair.

      The following example generates a key pair with the alias server-cert:

      $ keytool \
       -genkeypair \
       -alias server-cert \
       -keyalg EC \
       -keysize 2048 \
       -ext "san=dns:ds.example.com" \
       -dname "CN=ds.example.com,O=Example Corp,C=FR" \
       -keystore NONE \
       -storetype PKCS11 \
       -providerClass sun.security.pkcs11.SunPKCS11 \
       -providerArg /path/to/softhsm/hsm.conf
      Enter keystore password:

      The keystore password is the user PIN.

   3. Self-sign the public key certificate:

      $ keytool \
       -selfcert \
       -alias server-cert \
       -keystore NONE \
       -storetype PKCS11 \
       -providerClass sun.security.pkcs11.SunPKCS11 \
       -providerArg /path/to/softhsm/hsm.conf
      Enter keystore password:

      The keystore password is the user PIN.

      Using a CA-signed cert is similar, but not shown here.

1. Make sure you have the plain text PIN.

   With SoftHSM, this is the user PIN set when initializing the slot where you stored the keys.

2. Make sure that the Java environment can find SoftHSM with its configuration.

   For example, add a provider definition by using an extra Java security properties file as in the following example. In this example, 10 security providers are already defined in the system java.security file. The configuration must use the next available key, which is security.provider.11:

   # Define the additional security provider in the extra file:
   $ cat /path/to/opendj/config/java.security
   # Security provider for accessing SoftHSM:
   security.provider.11=sun.security.pkcs11.SunPKCS11 /path/to/softhsm/hsm.conf
   
   # Use the extra file when starting the DS server:
   $ grep java.security /path/to/opendj/config/java.properties
   start-ds.java-args=-server -Djava.security.properties=/path/to/opendj/config/java.security
   
   # Restart the DS server so the changes take effect:
   $ stop-ds --restart

3. Create the PKCS#11 key manager provider configuration.

   The following example creates a provider for SoftHSM with a protected PIN file:

   $ touch /path/to/opendj/config/softhsm.pin
   $ chmod 600 /path/to/opendj/config/softhsm.pin
   $ vi /path/to/opendj/config/softhsm.pin
   # Add the user PIN on the first and only line in the file, and save your work.
   $ dsconfig \
    create-key-manager-provider \
    --hostname localhost \
    --port 4444 \
    --bindDN uid=admin \
    --bindPassword password \
    --provider-name SoftHSM \
    --type pkcs11 \
    --set enabled:true \
    --set key-store-pin:"&{file:/path/to/opendj/config/softhsm.pin}" \
    --usePkcs12TrustStore /path/to/opendj/config/keystore \
    --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
    --no-prompt

   DS key manager providers also support storing the PIN in the configuration, in an environment variable, or in a Java property.

1. Set a connection handler or authorization mechanism to use the PKCS#11 key manager provider.

   The following example configures the LDAPS connection handler to use the SoftHSM provider:

   $ dsconfig \
    set-connection-handler-prop \
    --hostname localhost \
    --port 4444 \
    --bindDN uid=admin \
    --bindPassword password \
    --handler-name LDAPS \
    --set listen-port:1636 \
    --set enabled:true \
    --set use-ssl:true \
    --set key-manager-provider:SoftHSM \
    --usePkcs12TrustStore /path/to/opendj/config/keystore \
    --trustStorePasswordFile /path/to/opendj/config/keystore.pin \
    --no-prompt

2. Verify that the secure connection negotiation works with the HSM configured:

   $ ldapsearch \
    --hostname ds.example.com \
    --port 1636 \
    --useSSL \
    --baseDN dc=example,dc=com \
    "(uid=bjensen)" \
    cn
   The server is using the following certificate:
       Subject DN:  CN=ds.example.com, O=Example Corp, C=FR
       Issuer DN:  CN=ds.example.com, O=Example Corp, C=FR
       Validity:  <validity-period>
   Do you wish to trust this certificate and continue connecting to the server?
   Please enter "yes" or "no":yes
   dn: uid=bjensen,ou=People,dc=example,dc=com
   cn: Barbara Jensen
   cn: Babs Jensen