How do I use externally created SSL keys with DS 6.x?
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.
Note
This article does not apply to DS 7 and later, because DS 7 introduces improvements to simplify key management. See Key Management for further information.
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:
-----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:
- 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.
- 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.
- 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:
- 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.
- 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.
- 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
Related Training
N/A
Related Issue Tracker IDs
N/A