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

Overview

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:

An unencrypted private key looks like this:

A server or CA certificate looks like this:

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

• StartTLS (LDAP)
• LDAPS (LDAP/SSL)

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. This example will update the LDAP Connection Handler, which is configured to allow StartTLS: $ ./dsconfig set-connection-handler-prop --handler-name LDAP --set ssl-cert-nickname:key-2015 --hostname ds.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. This example will update the LDAPS Connection Handler, which is configured to allow LDAP/SSL (LDAPS): $ ./dsconfig set-connection-handler-prop --handler-name LDAPS --set ssl-cert-nickname:key-2015 --hostname ds.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 6.x - [replication is NOT enabled]?

FAQ: SSL certificate management in DS 6.x

SSL in DS

LDAP Client Access Over SSL

Related Training

N/A

Related Issue Tracker IDs

N/A