How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I use externally created SSL keys with DS 5.x or 6.x?

Last updated Apr 8, 2021

The purpose of this article is to provide guidance when SSL/TLS key material (private keys, certificates) are provided to DS from an external source.


Overview

DS 7 introduces improvements to simplify key management. See Security Guide › Key Management for further information. 

Pre-DS 7

As a Java® application, DS uses Java keystore files for storing all cryptographic related information, such as the server's private key, the server's signed certificate and any issuing CA certificates.

The keytool command provided with Java is designed to always keep the private key securely inside the keystore file. However, in many environments (especially UNIX® environments) it is possible that keys and certificates are provided through some other mechanism and they may need to be imported into DS's keystore.

In a typical scenario, the DS administrator will be given two or three files:

  • the server's private key.
  • the server's signed certificate.
  • the signing CA's certificate (or even multiple CA certificates, if a CA hierarchy is being used).

The names and extensions of the files used for all three is not standardized in any way. However, they are all text files, so you may need to look at them first to understand which file is which.

A private key may be encrypted with a passphrase. It will look a little like this:

-----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: DES-EDE3-CBC,F57A187E0BB25947 [base-64 encoded information] -----END RSA PRIVATE KEY-----

An unencrypted private key looks like this:

-----BEGIN RSA PRIVATE KEY----- [base-64 encoded information] -----END RSA PRIVATE KEY-----

A server or CA certificate looks like this:

-----BEGIN CERTIFICATE----- [base-64 encoded information] -----END CERTIFICATE-----

This article covers using externally created SSL keys in the following scenarios:

StartTLS (LDAP) using externally created SSL keys:

  1. Convert the information into an encrypted PKCS#12 file. The value you choose for -name is used in the next step and will be the nickname that you set in DS's connection handler: $ openssl pkcs12 -export -in server.pem -inkey private.key -out server.p12 -name key-2015 -CAfile ca.pem -caname ca-root Enter pass phrase for private.key: Enter Export Password:  Verifying - Enter Export Password:If the private.key file is encrypted, you will be prompted for its passphrase. You will always be prompted twice for the PKCS#12 (export) password.
  2. Import the PKCS#12 file into DS's keystore: $ keytool -importkeystore -destkeystore /path/to/ds/config/keystore -deststorepass `cat /path/to/ds/config/keystore.pin` -srckeystore server1.p12 -srcstoretype PKCS12 -destkeypass `cat /path/to/ds/config/keystore.pin` Enter source keystore password: Entry for alias key-2015 successfully imported. Import command completed: 1 entries successfully imported, 0 entries failed or cancelledThe source keystore password is the PKCS#12 export password entered in the previous step.
  3. Configure the connection handler to use the imported keypair using the dsconfig command applicable to your version. This example will update the LDAP Connection Handler, which is configured to allow StartTLS:
    • DS 6.x: $ ./dsconfig set-connection-handler-prop --handler-name LDAP --set ssl-cert-nickname:key-2015 --hostname ds1.example.com --port 4444 --trustAll --bindDN "cn=Directory Manager" --bindPassword password --no-prompt
    • DS 5.x: $ ./dsconfig set-connection-handler-prop --handler-name "LDAP Connection Handler" --set ssl-cert-nickname:key-2015 --hostname ds1.example.com --port 4444 --trustAll --bindDN "cn=Directory Manager" --bindPassword password --no-prompt

LDAPS (LDAP/SSL) using externally created SSL keys:

  1. Convert the information into an encrypted PKCS#12 file. The value you choose for -name is used in the next step and will be the nickname that you set in DS's connection handler: $ openssl pkcs12 -export -in server.pem -inkey private.key -out server.p12 -name key-2015 -CAfile ca.pem -caname ca-root Enter pass phrase for private.key: Enter Export Password:  Verifying - Enter Export Password:If the private.key file is encrypted, you will be prompted for its passphrase. You will always be prompted twice for the PKCS#12 (export) password.
  2. Import the PKCS#12 file into DS's keystore: $ keytool -importkeystore -destkeystore /path/to/ds/config/keystore -deststorepass `cat /path/to/ds/config/keystore.pin` -srckeystore server1.p12 -srcstoretype PKCS12 -destkeypass `cat /path/to/ds/config/keystore.pin` Enter source keystore password: Entry for alias key-2015 successfully imported. Import command completed: 1 entries successfully imported, 0 entries failed or cancelledThe source keystore password is the PKCS#12 export password entered in the previous step.
  3. Configure the connection handler to use the imported keypair using the dsconfig command applicable to your version. This example will update the LDAPS Connection Handler, which is configured to allow LDAP/SSL (LDAPS):
    • DS 6.x: $ ./dsconfig set-connection-handler-prop --handler-name LDAPS --set ssl-cert-nickname:key-2015 --hostname ds1.example.com --port 4444 --trustAll --bindDN "cn=Directory Manager" --bindPassword password --no-prompt
    • DS 5.x: $ ./dsconfig set-connection-handler-prop --handler-name "LDAPS Connection Handler" --set ssl-cert-nickname:key-2015 --hostname ds1.example.com --port 4444 --trustAll --bindDN "cn=Directory Manager" --bindPassword password --no-prompt

See Also

How do I configure a CA Signed certificate for replication in DS 5.x or 6.x - [replication is NOT enabled]?

FAQ: SSL certificate management in DS 5.x or 6.x

SSL in DS

Administration Guide › LDAP Client Access Over SSL

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.