FAQ: SSL certificate management in DS 6.x
The purpose of this FAQ is to provide answers to commonly asked questions regarding SSL certificate management in DS.
1 reader recommends this article
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.
Frequently asked questions
- Q. Can I import my own certificates into the ads-truststore for replication purposes?
- Q. Can I use SSL certificates received from an external source?
- Q. Can I share a single keystore across multiple DS servers?
- Q. How do I convert a PKCS#12 file to JKS format?
- Q. Can I configure mutual SSL authentication with DS?
- Q. How do I debug a SSL handshake error?
Q. Can I import my own certificates into the ads-truststore for replication purposes?
A. Yes, you can import your own certificates into the ads-truststore if you are using DS as your LDAP server.
See To Replace the Key Pair Used for Replication for further information.
Q. Can I use SSL certificates received from an external source?
A. Yes you can. If you receive a SSL certificate from an external source, you need to import this into your DS keystore as described in How do I use externally created SSL keys with DS 6.x?
Q. Can I share a single keystore across multiple DS servers?
A. No, private keys should remain on the server and never be shared/copied from one node to another due to the increased security risks. Sharing the same keystore (holding the private key and associated digital certificate) across instances is not an out of the box (OOTB) configuration or supported deployment approach:
- ForgeRock does not recommend moving from the OOTB deployment pattern (where each node has its own key pair to maximize the security posture) to sharing the same keys and certificates between instances as this is contrary to the purpose of the private key. The OOTB configuration is standard best practice to protect against individual key/certificate/keystore compromise and ensures each keystore is accessed by its own pin (password). This configuration limits your exposure if a key, certificate or keystore is compromised on a single instance. If keystores were shared and one node was compromised, all other nodes would be compromised as well.
- Sharing key material requires the keystore and pin file from one DS node to be copied/shared between instances. Normally these files never leave the host on which they are deployed; they should remain secure and “private” as intended.
Q. How do I convert a PKCS#12 file to JKS format?
A. If you want to keep the JKS Trustmanager Provider for the LDAPS connector and have received a PKCS#12 file, you need to import the keypair from PKCS12 into JKS Trustmanager Provider using the following keytool command:
$ keytool -importkeystore -srckeystore [MY_FILE.p12] -srcstoretype pkcs12 -srcalias [ALIAS_SRC] -destkeystore [MY_KEYSTORE.jks] -deststoretype jks -deststorepass [PASSWORD_JKS] -destalias [ALIAS_DEST] -destkeypass [PASSWORD_JKS]Q. Can I configure mutual SSL authentication with DS?
A. Yes, DS can be configured to perform mutual SSL authentication during the SSL handshake. See Preparing For Secure Communications for information on adding the client application's certificate for mutual SSL authentication.
Additionally, DS supports SASL/External authentication using the user's certificate. See Authenticating Client Applications With a Certificate.
Q. How do I debug a SSL handshake error?
A. You can debug a SSL handshake error by adding SSL debugging to the JVM:
- Update the start-ds.java-args property in the java.properties file (located in the /path/to/ds/config directory) to include: -Djavax.net.debug=ssl,handshake,trustmanager
- Restart the DS server.
When enabled, the SSL debug logs are output to the server.out file, which is located in the /path/to/ds/logs directory where DS is installed.
See Also
Client Certificate Validation and the Directory
Managing Certificates and Private Keys