SSL in DS/OpenDJ

This book provides information on SSL in DS/OpenDJ, including connections and certificates.


Configuration


How do I configure LDAPS clients in DS/OpenDJ (All versions)?

The purpose of this article is to provide guidance on using SSL securely with LDAP clients in DS/OpenDJ.

Certificates

DS/OpenDJ supports SSL/TLS in two ways: the first is using a de-facto protocol called “LDAPS” often on port 636 and the second is using the standard START_TLS operation to switch a normal LDAP connection into TLS mode.

After configuring the server to provide either LDAPS or LDAP with START_TLS, you also need to configure the LDAP clients correctly; you will not have a secure connection unless the clients are configured correctly.

Most LDAP clients are written using a small number of different SSL toolkits, which need to be configured differently, but they all need either the server’s SSL certificate or the CA certificate that signed the server’s SSL certificate. You can extract these using the following command in the openssl command-line program:

$ openssl s_client -connect [hostname]:[port] -showcerts

replacing [hostname] and [port] with appropriate values.

The output will include all the certificates sent by the server, which you need to copy and paste into separate files. The certificate for a server created by DS/OpenDJ's setup tool will look like this:

Certificate chain
 0 s:/O=Administration Connector Self-Signed Certificate/CN=[hostname]
   i:/O=Administration Connector Self-Signed Certificate/CN=[hostname]
-----BEGIN CERTIFICATE-----
MIICFTCCAX6gAwIBAgIEU9tJhjANBgkqhkiG9w0BAQUFADBPMTkwNwYDVQQKEzBB
[...more base64...]
AsdGJP+jxHEh
-----END CERTIFICATE-----

You need to copy all the lines from BEGIN CERTIFICATE to END CERTIFICATE (inclusive) into a text file, in this case /path/to/my/server.pem.

However, if you have a certificate issued to you by a CA, the openssl output will look more like this:

Certificate chain
 0 s:/serialNumber=something-unique/OU=XY12345668/OU=See www.rapidssl.com/resources/cps (c)14/OU=Domain Control Validated - RapidSSL(R)/CN=[hostname]
   i:/C=US/O=GeoTrust, Inc./CN=RapidSSL CA
-----BEGIN CERTIFICATE-----
MIIFNjCCBB6gAwIBAgIDE4OoMA0GCSqGSIb3DQEBBQUAMDwxCzAJBgNVBAYTAlVT
[...base64 of the server certificate you can ignore...]
TqMs90rAdzwrQTsuaQdUhx8rE6bzkO5WOEIphNQToPpIOUygZm4x8QdG
-----END CERTIFICATE-----
 1 s:/C=US/O=GeoTrust, Inc./CN=RapidSSL CA
   i:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA
-----BEGIN CERTIFICATE-----
MIID1TCCAr2gAwIBAgIDAjbRMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT
[...base 64 of a certificate you can ignore...]
LEL2TxyJeN4mTvVvk0wVaydWTQBUbHq3tw==
-----END CERTIFICATE-----
 2 s:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA
   i:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA
-----BEGIN CERTIFICATE-----
MIIDVDCCAjygAwIBAgIDAjRWMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT
[...base 64 of the certificate you should copy...]
5fEWCRE11azbJHFwLJhWC9kXtNHjUStedejV0NxPNO3CBWaAocvmMw==
-----END CERTIFICATE-----

You should copy the last certificate to /path/to/my/ca.pem.

DS/OpenDJ SDK Clients

The ldapsearch (etc) tools provided with the DS/OpenDJ server will automatically trust certificates signed by CA certificates held in the server’s config/truststore file. The DS/OpenDJ documentation describes how to maintain that file.

If you are writing your own clients using the DS/OpenDJ SDK, you have to provide the trusted CA certificate in a JKS file and pass that to a TrustManager building the SSLContext object.

To add the trusted CA certificate to a JKS file, use the following command:

$ keytool -keystore /path/to/my/truststore -import -alias root-ca -file /path/to/my/ca.pem

You will be prompted for a password to protect the truststore and then prompted to trust the new certificate.

JNDI Clients

A Java® client written using JNDI needs to have the server’s certificate (or CA’s certificate) imported into the JVM's cacerts keystore. The following code snippet will trust any servers with certificates signed by a CA in the cacerts keystore:

Hashtable env = new Hashtable(11);
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldaps://[hostname]:[port]/");
env.put(Context.SECURITY_PROTOCOL, "ssl");
DirContext ctx = new InitialDirContext(env);

OpenSSL® Clients

Most native LDAP clients use the OpenSSL library. Examples include the ldapsearch program on most Linux® distributions and on the Mac® OS X® operating system, which uses a simple text file listing all the trusted CA certificates.

You can add the CA certificate to the system-wide list of trusted CAs, but the location of that file varies widely and so won’t be discussed further.

The other option is to create a local list of trusted CAs and to append your CA certificate to that list using the following commands.

$ touch /path/to/my/ca-certs.pem
$ cat /path/to/my/ca.pem >> /path/to/my/ca-certs.pem

To use the list of trusted CAs, you can set an environment variable using the following command:

$ LDAPTLS_CACERT=/path/to/my/ca-certs.pem
$ export LDAPTLS_CACERT

Alternatively, set the TLS_CACERT option in an appropriate ldap.conf file. Then just run the ldapsearch program using the following command:

$ ./ldapsearch --hostname ds1.example.com --port 4444 --baseDN "dc=example,dc=com" --searchScope base "(objectclass=*)"

Mozilla® NSS Clients

Some native LDAP clients use the Mozilla NSS library. An example is the ldapsearch program in Oracle® Solaris®. This library uses several databases inside a disk directory and you need to add the certificates to these databases.

To create a new set of NSS databases, create an empty directory and initialise it with the certutil command:

$ mkdir /path/to/my/nssdb
$ certutil -N -d /path/to/my/nssdb

The certutil command will prompt for a password, which is not important unless you are storing private keys in the databases.

If you are using a self-signed certificate for your server then you should import it as a trusted peer:

$ certutil -A -d /path/to/my/nssdb -n "opendj" -i /path/to/my/server.pem -a -t P,,

Alternatively, if you have a certificate signed by a CA, then import the CA certificate into the database. You need to configure NSS to trust SSL certificates signed by it as a CA:

$ certutil -A -d /path/to/my/nssdb -n "ca" -i /path/to/my/ca.pem -a -t C,,

To use the databases with the client, you need to pass the directory to the client, for example:

$ ./ldapsearch --hostname ds1.example.com --port 4444 --useSSL --trustAll --baseDN "dc=example,dc=com" --searchScope base "(objectclass=*)"

See Also

How do I troubleshoot connection via LDAPS issues in DS/OpenDJ (All versions)?

Invalid Padding length error when attempting to connect to DS 5 or OpenDJ 3.x via LDAPS

LDAPS client connections fail with SSLHandshakeException: no cipher suites in common in DS 5 and OpenDJ 3.x

Developer's Guide › Authenticating To the Directory

Administration Guide › Preparing For Secure Communications

Administration Guide › LDAP Client Access Over SSL

SSL and Custom Sockets in JNDI

Mozilla NSS certutil documentation

Related Training

ForgeRock Directory Services Core Concepts

Related Issue Tracker IDs

N/A


How do I troubleshoot connection via LDAPS issues in DS/OpenDJ (All versions)?

The purpose of this article is to provide information on troubleshooting connection via LDAPS issues in DS/OpenDJ. This article assumes you are connecting to DS/OpenDJ from AM/OpenAM using a secure LDAP connection (over SSL).

Load balancer configuration

If you are using a load balancer in front of DS/OpenDJ, you should ensure you have specified the appropriate details in the SSL certificates depending on your configuration:

  • If the load balancer is doing SSL pass-through, you only need to specify the DS/OpenDJ hostnames in the SSL certificates.
  • If the load balancer is using SSL, you need to specify the load balancer hostname as the Cert Subject and the DS/OpenDJ hostnames as the Subject Alternate Names.

To help pinpoint these issues, you should try the following tests and let us know the results when you submit a ticket with the troubleshooting data:

  1. Bypass the load balancer and point straight to a DS/OpenDJ server; retest to determine if the load balancer is causing the connection issues.
  2. Point the load balancer to an individual DS/OpenDJ server and retest. Repeat with the other DS/OpenDJ servers. If this works, it suggests there is an issue with the DS/OpenDJ Subject Alternative Name or with a known feature in the Oracle® JDK that prevents a triple handshake vulnerability. An issue can manifest as a result of the JDK feature if the load balancer does SSL session resumption with multiple different SSL certificates. This is discussed in the following Stack Overflow article and Puppet Server: Known Issues: SSL Server Certificate Change and Virtual IP Addresses. If it is affecting you, you will also see "server certificate change is restricted" errors in your server log, for example:
    javax.net.ssl.SSLHandshakeException: server certificate change is restrictedduring renegotiation
    

Java upgrades

Some Java® upgrades have caused LDAPS issues in DS/OpenDJ as indicated in the following table:

Troubleshooting connection issues

Caution

If you have made any changes to the keystore or truststore, you should make sure you have restarted DS/OpenDJ to ensure it is using the updated files before proceeding to troubleshoot.

There are a number of different types of data that you should collect to help us troubleshoot connection issues via LDAPS. If you are experiencing connection issues, you should collect the following data and submit it to us when you raise the ticket to enable us to help you more quickly:

  • Server logs
  • SSL debug logs
  • Keystore information
  • Current JVM options
  • Third-party tools output

Server logs

Server logs (Access and Error) record details about all the operations processed by the server, in addition to details of all server events, errors and warnings. If there are CONNECT messages in the Access log, you know that the DS/OpenDJ server is at least receiving TCP connections from AM/OpenAM.

These files are located in the /path/to/ds/logs directory where DS/OpenDJ is installed.

SSL debug logs

The SSL debug logs provide detailed SSL debugging information. 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/OpenDJ is installed. 

You can enable SSL debug logs by starting the DS/OpenDJ server with additional options:

OPENDJ_JAVA_ARGS='-server -Djavax.net.debug=SSL,handshake,trustmanager' bin/start-ds

Keystore information

Keystore information provides us with details about the contents of each keystore and truststore; keystores are used for private keys whereas truststores are used for public, signed certificates.

By default, truststore and/or keystore files and passwords are stored in different stores depending on their purpose:

  • ads-truststore for replication purposes.
  • admin-truststore and admin-keystore for administration purposes.
  • truststore and keystore for everything else.

These files are located in /path/to/ds/config; as of DS 6 and later, ads-truststore is located in /path/to/ds/db/ads-truststore for new installs.

See  Administration Guide › Changing Server Certificates for further information.

You can run the keytool command for each keystore and truststore to see the contents:

$ keytool -list -v -keystore [keystore] -storetype [storetype] -storepass [password]

replacing [keystore] with the full path and name of the keystore or truststore file, [storetype] with the type of keystore (for example JCEKS or JKS), and [password] with the corresponding keystore or truststore password.

Current JVM options

Current JVM settings can be useful when troubleshooting connection issues. See How do I collect JVM data for troubleshooting DS/OpenDJ (All versions)? for information on finding your current JVM settings.

Third-party tools output

There are two third-party tools, which can help with debugging LDAPS connection issues by providing information about the SSL connection as well as attempting a SSL handshake. These tools are:

  • openssl - you can run a command such as the following to provide this information:
    $ openssl s_client -connect [hostname:port] -showcerts
    Press Ctrl+C to quit openssl.
  • Keystore explorer - this is a GUI application that provides similar information. You need to specify the hostname and port to get the connection information.
Note

These are third-party tools that we suggest can be used for troubleshooting but are not supported by ForgeRock.

See Also

FAQ: SSL certificate management in DS/OpenDJ

AM/OpenAM (All versions) fail to connect to DS/OpenDJ using a secured connection with an ERROR: Connection factory became offline

How do I configure LDAPS clients in DS/OpenDJ (All versions)?

How do I make AM/OpenAM (All versions) communicate with a secured LDAP server?

Administration Guide › LDAP Client Access Over SSL

Administration Guide › Troubleshooting TLS/SSL Connections

Administration Guide › Server Logs

Configuration Reference › LDAP Connection Handler

Related Training

N/A

Related Issue Tracker IDs

OPENDJ-652 (Connections from Solaris 10 ldapclient can cause LDAPS request handler to spin)


How do I use externally created SSL keys with DS/OpenDJ (All versions)?

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

Overview

As a Java® application, DS/OpenDJ 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/OpenDJ's keystore.

In a typical scenario, the DS/OpenDJ 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/OpenDJ'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/OpenDJ'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 cancelled
    The 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 and later:
      $ ./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
    • Pre-DS 6:
      $ ./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/OpenDJ'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/OpenDJ'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 cancelled
    The 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 and later:
      $ ./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
    • Pre-DS 6:
      $ ./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 an external or CA Signed certificate for replication in DS/OpenDJ (All versions)?

FAQ: SSL certificate management in DS/OpenDJ

SSL in DS/OpenDJ

Administration Guide › LDAP Client Access Over SSL

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I prevent the use of weak SSL cipher suites in DS/OpenDJ?

The purpose of this article is to provide information on improving security in DS/OpenDJ by preventing the use of weak SSL cipher suites and protocols. This article covers the admin port, replication port and connection handlers (HTTP, LDAP and LDAPS).

Preventing the use of weak SSL cipher suites

You can restrict the use of weak SSL cipher suites for strengthening security as needed, by setting the ssl-protocol and ssl-cipher-suite properties to include only the protocols or cipher suites you want to use for the particular connection handler or connector. 

Note

The available protocols and cipher suites you can use depend on what is supported by your JVM. You should upgrade your JVM and/or install the Oracle® Java® JCE unlimited strength jars to use stronger ciphers. These jars can be downloaded from the following link for Java 8 and earlier: Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files Download. Java 9 and later uses the unlimited policy files by default.

To list the currently supported protocols and cipher suites, read the supportedTLSProtocols and supportedTLSCiphers attributes of the root DSE. For example:

$ ./ldapsearch --port 1389 --baseDN "" --searchScope base "(objectclass=*)" supportedTLSCiphers supportedTLSProtocols

See Administration Guide › To List Protocols and Cipher Suites for further information.

Admin port

The DS/OpenDJ command line tools like dsconfig and dsreplication communicate with the DS/OpenDJ server using the administration connection handler, which by default listens on all network interfaces on port 4444, and uses LDAPS. You should reconfigure the administration connection handler to remove the weak cipher suites and strengthen security as needed.

See How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) administration port? for further information.

Replication port

The replication connector uses the Crypto Manager for its SSL configuration. You should reconfigure the Crypto Manager to remove the weak cipher suites and strengthen security as needed.

See How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) replication port? for further information.

Connection handlers

Connection handlers are all configured in the same way using the dsconfig set-connection-handler-prop command. The only thing that changes is the handler-name option. 

The three connection handlers you should be concerned with are:

  • HTTP - this handler provides access to directory data over HTTP, including via the REST API.
  • LDAP - this handler provides secure connections from client applications using StartTLS .
  • LDAPS - this handler provides secure connections from client applications using LDAPS (LDAP/SSL).

See Administration Guide › To Restrict Protocols and Cipher Suites for information on configuring connection handlers to remove weak cipher suites and strengthen security as needed.

See Also

LDAPS client connections fail with SSLHandshakeException: no cipher suites in common in DS 5 and OpenDJ 3.x

Administration Guide › LDAP Client Access Over SSL

Administration Guide › RESTful Client Access Over HTTP

Administration Guide › TLS Protocols and Cipher Suites

Server Javadoc › Interface CryptoManager

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) administration port?

The purpose of this article is to provide administrative guidance to improve security on the DS/OpenDJ administration interface.

Improving security on the DS/OpenDJ admin interface

The DS/OpenDJ command line tools like dsconfig and dsreplication communicate with the DS/OpenDJ server using the administration connection handler, which by default listens on all network interfaces on port 4444, and uses LDAPS.

This can cause issues. You should reconfigure the administration connection handler to remove the weak cipher suites and improve security.

Reconfiguring the administration connection handler

You can restrict the list of protocols and cipher suites used by setting the ssl-protocol and ssl-cipher-suite connection handler properties to include only the protocols or cipher suites you want. For example, to restrict the cipher suites to TLS_RSA_WITH_AES_128_CBC_SHA256 use the dsconfig set-administration-connector-prop command as shown in the following example.

$ ./dsconfig set-administration-connector-prop --port 4444 --hostname ds1.example.com --bindDN "cn=Directory Manager" --bindPassword password --set ssl-cipher-suite:TLS_RSA_WITH_AES_128_CBC_SHA256 --no-prompt

To list the available protocols and cipher suites, read the supportedTLSProtocols and supportedTLSCiphers attributes of the root DSE using the following command. Install unlimited strength Java cryptography extensions for stronger ciphers.

$ ./ldapsearch --hostname localhost --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --baseDN "" --trustAll --useSSL --searchScope base "(&)" supportedTLSCiphers supportedTLSProtocols 

See Also

How do I configure DS/OpenDJ (All versions) to avoid the POODLE SSL vulnerability?

How do I protect DS/OpenDJ (All versions) from the FREAK SSL/TLS Vulnerability?

How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) replication port?

Administration Guide › LDAP Client Access Over SSL

Administration Guide › TLS Protocols and Cipher Suites

Related Training

N/A

Related Issue Tracker IDs

OPENDJ-668 (Cannot configure ssl-cipher-suites on admin connector)


How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) replication port?

The purpose of this article is to provide administrative guidance to improve security on the DS/OpenDJ replication channels. The replication connector uses the Crypto Manager for its SSL configuration.

Improving security on DS/OpenDJ replication channels

The replication connector uses the Crypto Manager for its SSL configuration. You are able to restrict the list of protocols and cipher suites used on the replication connector with the ssl-protocol and ssl-cipher-suite properties for Crypto Manager.

For example, to restrict the cipher suites to TLS_EMPTY_RENEGOTIATION_INFO_SCSV and TLS_RSA_WITH_AES_256_CBC_SHA and only allow TLS, use the dsconfig set-crypto-manager-prop commands as shown in the following example:

$ ./dsconfig set-crypto-manager-prop --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --add ssl-cipher-suite:TLS_EMPTY_RENEGOTIATION_INFO_SCSV --add ssl-cipher-suite:TLS_RSA_WITH_AES_256_CBC_SHA --trustAll --no-prompt

$ ./dsconfig set-crypto-manager-prop --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --add ssl-protocol:TLSv1 --add ssl-protocol:TLSv1.1 --add ssl-protocol:TLSv1.2 --trustAll --no-prompt

The available protocols and cipher suites you can use depend on what is supported by your JVM. To list which ones are supported, read the supportedTLSProtocols and supportedTLSCiphers attributes of the root DSE using the following command against an LDAPS connection that has default (unspecified protocol and cipher) SSL properties:

$ ./ldapsearch --port 636 --useSSL --trustAll --baseDN "" --searchScope base "(objectclass=*)" supportedTLSCiphers supportedTLSProtocols

To use stronger ciphers, you may wish to upgrade your JVM and/or install unlimited strength Java® cryptography extensions.

See the following for a description of the properties and other available settings: Server Javadoc › Interface CryptoManager.

Caution

These are advanced configuration parameters, setting them incorrectly can cause replication to fail. Care should be taken to keep configuration the same across all servers in the replication group.

See Also

How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) administration port?

LDAPS client connections fail with SSLHandshakeException: no cipher suites in common in DS 5 and OpenDJ 3.x

Server Javadoc › Interface CryptoManager

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I protect DS/OpenDJ (All versions) from the FREAK SSL/TLS Vulnerability?

The purpose of this article is to provide information on protecting DS/OpenDJ from the FREAK (Factoring Attack on RSA-EXPORT Keys or CVE-2015-0204) SSL/TLS Vulnerability. This vulnerability may affect you if you have configured DS/OpenDJ to use SSL and accept secure connections from LDAP clients (LDAPS).

Background

The FREAK vulnerability is based on the weak SSL cipher configuration on the server side (where the server accepts RSA_EXPORT cipher suites) and a client which uses older OpenSSL versions (OpenSSL before 0.9.8zd, 1.0.0 before 1.0.0p, and 1.0.1 before 1.0.1k); see Vulnerability Summary for CVE-2015-0204 for further information. However, DS/OpenDJ does not use OpenSSL (or any other OS security libraries) in any way.

DS/OpenDJ uses the SSL implementation provided by the JVM and uses all the ciphers supported by the JVM by default.

Protecting DS/OpenDJ

There are  a number of things you can do to protect DS/OpenDJ from the FREAK SSL/TLS Vulnerability:

  • Upgrade your JVM. You should preferably upgrade to the latest version, but you must have one of the following versions at a minimum to ensure your JVM contains the Oracle® security fixes: 6u91, 7u76 or 8u40.
Note

Java 8 is only supported if you are using OpenDJ 2.6.2 and later / DS.

  • Install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files that are applicable to your version of the JVM. These policy files are a separate download from Oracle.
  • Restrict the allowed cipher suites with the dsconfig command. For example:
    $ ./dsconfig set-connection-handler-prop --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --handler-name [handler_name] --add ssl-cipher-suite:[cipher_suite] --trustAll
    

See How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) replication port? and How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) administration port? for further information on preventing the use of weak cipher suites.

Example

This example configures the LDAP Connection Handler, LDAPS Connection Handler and the Admin Connector to only use the TLS_RSA_WITH_AES_256_CBC_SHA cipher. 

Remember that DS/OpenDJ only exposes the ciphers available from your JVM. This process configures the instance to only use those ciphers you wish DS/OpenDJ to expose; ciphers are not removed from the JVM.

  1. Start with a new DS/OpenDJ instance with the default ciphers exposed by the JVM. In this case, there are 18 ciphers with this JVM:
    LDAP Ciphers (port 389)
    
    $ ./ldapsearch --port 389 --baseDN "" --searchScope base "(objectclass=*)" supportedTLSCiphers
    dn: 
    supportedTLSCiphers: TLS_RSA_WITH_AES_256_CBC_SHA256
    supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
    supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
    supportedTLSCiphers: TLS_RSA_WITH_AES_256_CBC_SHA
    supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_256_CBC_SHA
    supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_256_CBC_SHA
    supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA256
    supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
    supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
    supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA
    supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA
    supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA
    supportedTLSCiphers: SSL_RSA_WITH_3DES_EDE_CBC_SHA
    supportedTLSCiphers: SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
    supportedTLSCiphers: SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
    supportedTLSCiphers: SSL_RSA_WITH_RC4_128_SHA
    supportedTLSCiphers: SSL_RSA_WITH_RC4_128_MD5
    supportedTLSCiphers: TLS_EMPTY_RENEGOTIATION_INFO_SCSV
    
    LDAPS Ciphers (port 636)
    
    $ ./ldapsearch --port 636 --useSSL --trustAll --baseDN "" --searchScope base "(objectclass=*)" supportedTLSCiphers
    dn: 
    supportedTLSCiphers: TLS_RSA_WITH_AES_256_CBC_SHA256
    supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
    supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
    supportedTLSCiphers: TLS_RSA_WITH_AES_256_CBC_SHA
    supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_256_CBC_SHA
    supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_256_CBC_SHA
    supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA256
    supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
    supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
    supportedTLSCiphers: TLS_RSA_WITH_AES_128_CBC_SHA
    supportedTLSCiphers: TLS_DHE_RSA_WITH_AES_128_CBC_SHA
    supportedTLSCiphers: TLS_DHE_DSS_WITH_AES_128_CBC_SHA
    supportedTLSCiphers: SSL_RSA_WITH_3DES_EDE_CBC_SHA
    supportedTLSCiphers: SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
    supportedTLSCiphers: SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
    supportedTLSCiphers: SSL_RSA_WITH_RC4_128_SHA
    supportedTLSCiphers: SSL_RSA_WITH_RC4_128_MD5
    supportedTLSCiphers: TLS_EMPTY_RENEGOTIATION_INFO_SCSV
    
  2. Now let's configure the instance to only use the TLS_RSA_WITH_AES_256_CBC_SHA cipher using the dsconfig commands applicable to your version:
    • DS 6 and later:
      • LDAP Connection Handler:
        $ ./dsconfig set-connection-handler-prop --hostname ds1.example.com --port 4444 --handler-name LDAP --bindDN "cn=Directory Manager" --bindPassword password --add "ssl-cipher-suite:TLS_RSA_WITH_AES_256_CBC_SHA" --trustAll --no-prompt
      • LDAPS Connection Handler:
        $ ./dsconfig set-connection-handler-prop --hostname ds1.example.com --port 4444 --handler-name LDAPS --bindDN "cn=Directory Manager" --bindPassword password --add "ssl-cipher-suite:TLS_RSA_WITH_AES_256_CBC_SHA" --trustAll --no-prompt
      • Admin Connector:
        $ ./dsconfig set-administration-connector-prop --hostname rep1.forgerock.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --set ssl-cipher-suite:TLS_RSA_WITH_AES_256_CBC_SHA --trustAll --no-prompt
    • Pre-DS 6:
      • LDAP Connection Handler:
        $ ./dsconfig set-connection-handler-prop --hostname ds1.example.com --port 4444 --handler-name "LDAP Connection Handler" --bindDN "cn=Directory Manager" --bindPassword password --add "ssl-cipher-suite:TLS_RSA_WITH_AES_256_CBC_SHA" --trustAll --no-prompt
      • LDAPS Connection Handler:
        $ ./dsconfig set-connection-handler-prop --hostname ds1.example.com --port 4444 --handler-name "LDAPS Connection Handler" --bindDN "cn=Directory Manager" --bindPassword password --add "ssl-cipher-suite:TLS_RSA_WITH_AES_256_CBC_SHA" --trustAll --no-prompt
      • Admin Connector:
        $ ./dsconfig set-administration-connector-prop --hostname rep1.forgerock.com --port4444 --bindDN "cn=Directory Manager" --bindPassword password --set ssl-cipher-suite:TLS_RSA_WITH_AES_256_CBC_SHA --trustAll --no-prompt
  3. Restart the instance.
  4. Finally, let's re-check the ciphers that are exposed after these changes:
    LDAPS Ciphers (port 389)
    
    $ ./ldapsearch --port 389 --baseDN "" --searchScope base "(objectclass=*)" supportedTLSCiphers
    dn: 
    supportedTLSCiphers: TLS_RSA_WITH_AES_256_CBC_SHA
    
    LDAPS Ciphers (port 636)
    
    $ ./ldapsearch --port 636 --useSSL --trustAll --baseDN "" --searchScope base "(objectclass=*)" supportedTLSCiphers
    dn: 
    supportedTLSCiphers: TLS_RSA_WITH_AES_256_CBC_SHA
    As you can see, there is only one cipher now.
Note

If you install a new instance on this server, it will use all ciphers available from the JVM and you will need to complete this process again, for the new instance.

See Also

Invalid Padding length error when attempting to connect to DS 5 or OpenDJ 3.x via LDAPS

How do I configure DS/OpenDJ (All versions) to avoid the POODLE SSL vulnerability?

SSL in DS/OpenDJ

Vulnerability Summary for CVE-2015-0204

Oracle Critical Patch Update Advisory - April 2015

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I configure DS/OpenDJ (All versions) to avoid the POODLE SSL vulnerability?

The purpose of this article is to provide assistance on avoiding the POODLE SSL vulnerability in DS/OpenDJ.

POODLE vulnerability

The POODLE vulnerability is a design defect in the SSL protocol that affects all SSL implementations. It is described by its discoverers in a detailed PDF document. More formally, it is CVE­-2014­-3566.

It is possible to prevent the attack by configuring the server to not allow any SSLv3 connections.

Caution

Disabling SSLv3 may prevent very old legacy client applications from working.

Because DS/OpenDJ uses the Java® Virtual Machine's SSL implementation, it is possible to prevent the use of SSLv3 by editing the JVM's deployment.properties file (consult the JVM documentation for details), or by passing -Ddeployment.security.SSLv3=false to DS/OpenDJ on startup using DS/OpenDJ's java.properties file. This article will discuss the third alternative, namely reconfiguring DS/OpenDJ itself; this is the recommended approach.

Reconfiguring DS/OpenDJ

You must reconfigure the following settings:

  • The LDAPS Connection Handler if it is being used - this deals with LDAP over SSL/TLS;
  • The LDAP Connection Handler if StartTLS is being used to negotiate SSL/TLS over a normal LDAP connection;
  • The HTTP Connection Handler if it is being used - this provides a RESTful API onto the directory;
  • The Administration Connector, which uses LDAPS;
  • The Crypto Manager, which affects replication and LDAP Pass Through Authentication.
Note

These changes take immediate effect, but will only impact new connections.

LDAPS / LDAP / HTTP Connection Handlers

To update the LDAPS Connection Handler, do the following using the dsconfig command applicable to your version:

  • DS 6 and later:
    $ ./dsconfig --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-connection-handler-prop --handler-name LDAPS --add ssl-protocol:TLSv1 --add ssl-protocol:TLSv1.1 --add ssl-protocol:TLSv1.2 --trustAll --no-prompt
    This command updates the LDAPS Connection Handler with the SSL protocols; an updated config.ldif for this section looks similar to this:
    dn: cn=LDAPS,cn=connection handlers,cn=config
    ...
    ...
    ...
    ds-cfg-ssl-protocol: TLSv1
    ds-cfg-ssl-protocol: TLSv1.1
    ds-cfg-ssl-protocol: TLSv1.2
  • Pre-DS 6:
    $ ./dsconfig --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-connection-handler-prop --handler-name "LDAPS Connection Handler" --add ssl-protocol:TLSv1 --add ssl-protocol:TLSv1.1 --add ssl-protocol:TLSv1.2 --trustAll --no-prompt
    This command updates the LDAPS Connection Handler with the SSL protocols; an updated config.ldif for this section looks similar to this:
    dn: cn=LDAPS Connection Handler,cn=Connection Handlers,cn=config
    ...
    ...
    ...
    ds-cfg-ssl-protocol: TLSv1
    ds-cfg-ssl-protocol: TLSv1.1
    ds-cfg-ssl-protocol: TLSv1.2

The procedure is similar for updating the LDAP Connection Handler and the HTTP Connection Handler, except for the --handler-name parameter. In DS 6 and later, the "Connection Handler" suffixes have been dropped from the handler-names.

Administration Connector

To update the Administration Connector, do the following:

$ ./dsconfig --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-administration-connector-prop --add ssl-protocol:TLSv1 --add ssl-protocol:TLSv1.1 --add ssl-protocol:TLSv1.2 --trustAll --no-prompt

This command updates the Administration Connector with the SSL protocols; an updated config.ldif for this section looks similar to this:

dn: cn=Administration Connector,cn=config
...
...
...
ds-cfg-ssl-protocol: TLSv1
ds-cfg-ssl-protocol: TLSv1.1
ds-cfg-ssl-protocol: TLSv1.2

Crypto Manager

To update the Crypto Manager, do the following:

$ ./dsconfig --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password set-crypto-manager-prop --add ssl-protocol:TLSv1 --add ssl-protocol:TLSv1.1 --add ssl-protocol:TLSv1.2 --trustAll --no-prompt

This command updates the Crypto Manager with the SSL protocols; an updated config.ldif for this section looks similar to this:

dn: cn=Crypto Manager,cn=config
...
...
...
ds-cfg-ssl-protocol: TLSv1
ds-cfg-ssl-protocol: TLSv1.1
ds-cfg-ssl-protocol: TLSv1.2

See Also

How do I protect DS/OpenDJ (All versions) from the FREAK SSL/TLS Vulnerability?

How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) replication port?

How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) administration port?

This POODLE Bites: Exploiting The SSL 3.0 Fallback (PDF)

CVE-2014-3566

Related Training

N/A

Related Issue Tracker IDs

N/A


Frequently Asked Questions


FAQ: SSL certificate management in DS/OpenDJ

The purpose of this FAQ is to provide answers to commonly asked questions regarding SSL certificate management in DS/OpenDJ.

Frequently asked questions

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/OpenDJ as your LDAP server.

See Administration Guide › 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/OpenDJ keystore as described in How do I use externally created SSL keys with DS/OpenDJ (All versions)?

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/OpenDJ?

A. Yes, DS/OpenDJ can be configured to perform mutual SSL authentication during the SSL handshake. See Administration Guide › Preparing For Secure Communications for information on adding the client application's certificate for mutual SSL authentication.

Additionally, DS/OpenDJ supports SASL/External authentication using the user's certificate. See Developer's Guide › 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:

  1. 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
  2. Pre-DS 5 only: Run the bin/dsjavaproperties command to apply the changes you have made to the java.properties file:
    $ ./dsjavaproperties
    This command has been removed in DS 5.
  3. Restart the DS/OpenDJ 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/OpenDJ is installed. 

See Also

LDAP connection fails with No subject alternative DNS name matching error in AM 5.1.x, 6.x and DS 5.5.1, 5.5.2, 6.x

LDAPS client connections fail with SSLHandshakeException: no cipher suites in common in DS 5 and OpenDJ 3.x

Invalid Padding length error when attempting to connect to DS 5 or OpenDJ 3.x via LDAPS

SSL in DS/OpenDJ

Administration Guide › Client Certificate Validation and the Directory

Administration Guide › Changing Server Certificates

Security Guide › Managing Certificates and Private Keys

Related Training

ForgeRock Directory Services Core Concepts (DS-400)


Known Issues


LDAP connection fails with No subject alternative DNS name matching error in AM 5.1.x, 6.x and DS 5.5.1, 5.5.2, 6.x

The purpose of this article is to provide assistance if your LDAP/LDAPS connection fails with a "java.security.cert.CertificateException: No subject alternative DNS name matching" error. This issue can affect AM and DS.

Symptoms

The "No subject alternative DNS name matching" error can be seen in various AM debug logs with different contexts, for example:

  • Configuration debug log:
    ERROR: SMSEntry: Unable to initalize(exception):
    SMSException Exception Code:5
    Message:Unexpected LDAP exception occurred.
    --------------------------------------------------
    The lower level exception message
    Connect Error: No operational connection factories available
    The lower level exception:
    Connect Error: No operational connection factories available
       at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:206)
       at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:144)
       at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:113)
    ...
    Caused by: Connect Error: The LDAP connection has failed because an error occurred during the SSL handshake: java.security.cert.CertificateException: No subject alternative DNS name matching host1.example.com found.
    ...
    Caused by: javax.net.ssl.SSLHandshakeException: General SSLEngine problem
       at sun.security.ssl.Handshaker.checkThrown(Handshaker.java:1478)
       at sun.security.ssl.SSLEngineImpl.checkTaskThrown(SSLEngineImpl.java:535)
       at sun.security.ssl.SSLEngineImpl.writeAppRecord(SSLEngineImpl.java:1214)
       at sun.security.ssl.SSLEngineImpl.wrap(SSLEngineImpl.java:1186)
       at javax.net.ssl.SSLEngine.wrap(SSLEngine.java:469)
    ...
    Caused by: java.security.cert.CertificateException: No subject alternative DNS name matching host1.example.com found.
    
  • IdRepo debug log:
    ERROR: An error occurred while trying to initiate persistent search connection
    Connect Error: No operational connection factories available
       at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:206)
       at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:144)
       at org.forgerock.opendj.ldap.LdapException.newLdapException(LdapException.java:113)
    ...
    Caused by: Connect Error: The LDAP connection has failed because an error occurred during the SSL handshake: java.security.cert.CertificateException: No subject alternative DNS name matching host1.example.com found
    ...
    Caused by: javax.net.ssl.SSLHandshakeException: General SSLEngine problem
       at sun.security.ssl.Handshaker.checkThrown(Handshaker.java:1529)
       at sun.security.ssl.SSLEngineImpl.checkTaskThrown(SSLEngineImpl.java:535)
       at sun.security.ssl.SSLEngineImpl.writeAppRecord(SSLEngineImpl.java:1214)
       at sun.security.ssl.SSLEngineImpl.wrap(SSLEngineImpl.java:1186)
       at javax.net.ssl.SSLEngine.wrap(SSLEngine.java:469)
    ...
    Caused by: java.security.cert.CertificateException: No subject alternative DNS name matching host1.example.com found.
    
    
  • OpenDJ-SDK debug log:
    WARNING: Connection factory 'CachedConnectionPool(size=0[in:0 + out:0 + pending:0], maxSize=10, blocked=0, ldapClient=org.forgerock.opendj.ldap.LdapClientImpl@57c4d233)' is no longer operational: Connect Error: The LDAP connection has failed because an error occurred during the SSL handshake: java.security.cert.CertificateException: No subject alternative DNS name matching host1.example.com found.
    

Amster

You may also see a similar error when trying to install AM using Amster:

"stderr": "SLF4J: Failed to load class \"org.slf4j.impl.StaticLoggerBinder\".\nSLF4J: Defaulting to no-operation (NOP) logger implementation\nSLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.\nFailed to execute the 'install-openam' command: java.security.cert.CertificateException: No subject alternative DNS name matching host1.example.com found.",

Upgrade

You may encounter this error during an AM upgrade as well; in which case, you will also see an error similar to the following in the web application container log (for example, catalina.out for Apache Tomcat™):

org.forgerock.openam.upgrade.UpgradeException: Unable to parse product versions for comparison. Current: null war: ForgeRock Access Management 6.0.0 Build 3676519ec1 (2018-May-08 10:07)
Note

If you see the "Unable to parse product versions for comparison" error without the "No subject alternative DNS name matching" error, you should refer to AM/OpenAM (All versions) upgrade fails when com.iplanet.am.version is empty or corrupted for further information on resolving this known upgrade issue.

Recent Changes

There are various changes that could cause this issue, including (but not limited to):

  • Upgraded to, or installed AM 5.1.x; or AM 6 or later.
  • Upgraded to, or installed DS 5.5.1 or later.
  • Upgraded Java® to 1.7.0_191 or later; or 1.8.0_181 or later (including Oracle® JDK and OpenJDK).
  • Created a new data store (configuration, identity or CTS) or changed the DNS name of an existing one.
  • Changed server certificates.
  • Enabled SSL (changed the connection from LDAP to LDAPS).

Causes

Changes introduced in recent AM and DS versions (AM 5.1.x; AM 6 or later; DS 5.5.1 or later) have made LDAP SSL hostname validation stricter. AM checks the hostname in the LDAP server certificate correctly matches the hostname used to connect to the secured directory server (for example, DS or Active Directory®) and DS checks that the server it is trying to connect to has a certificate that matches the hostname.

These changes affect any secured LDAP/LDAPS connections:

  • AM connecting to a configuration store, identity store, CTS store etc.
  • Connections from LDAP command line tools such as ldapsearch.
  • Connections from admin tools such as dsconfig and dsreplication.
  • Connections to DS using the external REST2LDAP interface or DSML gateway; this includes IDM connecting to an external DS repository as that uses the REST2LDAP interface.
  • DS connecting to other LDAP servers when configured for pass-through authentication.

Java

Java 1.7.0_191 and 1.8.0_181 introduced changes to improve LDAP support by enabling endpoint identification algorithms by default for LDAPS connections; this also results in stricter hostname validation. For further information see:

Solution

This issue can be resolved by ensuring the hostname you are connecting to the LDAP server with matches the hostnames specified in the server certificate via the SAN (Subject Alternative Name). The SAN allows you to specify multiple hostnames and takes precedence over the Subject/CN entry in the certificate; you should list all the DNS hostnames that you expect to connect to the LDAP server in the SAN. See Administration Guide › Setting Up Server Certificates for further information.

Put simply, this means the hostname in the error (for example, host1.example.com) should be added to the SAN in the LDAP server certificate. The server certificate is located in the JVM truststore used by AM, which is $JAVA_HOME/jre/lib/security/cacerts by default. In the AM configuration, you should also check that the hostname specified for the LDAP connection is correct (and matches what is in the certificate's SAN).

Alternatives

The following options can be used to switch off stricter hostname validation; however this would make your deployment less secure and as such is not recommended: 

  • You can switch off hostname checks in DS by setting the org.forgerock.opendj.hostNameVerificationDisabled environment variable to true. See Javadoc › SSL_HOST_NAME_VALIDATION_DISABLED_PROPERTY for further information. 
  • You can switch off hostname validation in Java by setting the com.sun.jndi.ldap.object.disableEndpointIdentification JVM option to true. 

See Also

How do I configure LDAPS clients in DS/OpenDJ (All versions)?

How do I make AM/OpenAM (All versions) communicate with a secured LDAP server?

How do I import a certificate into the truststore used by AM/OpenAM (All versions) for SSL?

FAQ: SSL certificate management in AM/OpenAM and Policy Agents

FAQ: SSL certificate management in DS/OpenDJ

Best practice for upgrading to AM 6.x

SSL in DS/OpenDJ

SSL in AM/OpenAM and Policy Agents

Upgrade Guide

Related Training

N/A

Related Issue Tracker IDs

OPENAM-13984 (Upgrade/Install Document need for stricter Hostname Matching for LDAP certificates)


SSLHandshakeException or ClassCastException when using an HSM and Java 11 with ForgeRock products

The purpose of this article is to provide assistance if you encounter an SSLHandshakeException or ClassCastException when using a hardware security module (HSM) via the PKCS11 module with Java® 11. This issue affects all ForgeRock products that are compatible with Java 11 (AM, DS, IDM and IG 6.5 and later).

Symptoms

In DS/OpenDJ, you will see the following in the logs:

Unable to connect to the server: 91 (Connect Error) Additional Information: The LDAP connection has failed because an error occurred during the SSL handshake: java.io.EOFException

If you enable SSL debug logging, you will see one of the following errors depending on whether you are using TLS 1.3 or storing EC keys:

  • Using TLS 1.3 with Java 11:
    javax.net.ssl.SSLHandshakeException: Cannot produce CertificateVerify signature 
       at java.base/sun.security.ssl.Alert.createSSLException(Alert.java:128) 
       at java.base/sun.security.ssl.TransportContext.fatal(TransportContext.java:321) 
       at java.base/sun.security.ssl.TransportContext.fatal(TransportContext.java:264) 
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyMessage.<init>(CertificateVerify.java:905) 
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyProducer.onProduceCertificateVerify(CertificateVerify.java:1077)
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyProducer.produce(CertificateVerify.java:1070) 
       at java.base/sun.security.ssl.SSLHandshake.produce(SSLHandshake.java:436) 
       at java.base/sun.security.ssl.ClientHello$T13ClientHelloConsumer.goServerHello(ClientHello.java:1224) 
       at java.base/sun.security.ssl.ClientHello$T13ClientHelloConsumer.consume(ClientHello.java:1160) 
       at java.base/sun.security.ssl.ClientHello$ClientHelloConsumer.onClientHello(ClientHello.java:849) 
       at java.base/sun.security.ssl.ClientHello$ClientHelloConsumer.consume(ClientHello.java:810) 
       at java.base/sun.security.ssl.SSLHandshake.consume(SSLHandshake.java:392) 
       at java.base/sun.security.ssl.HandshakeContext.dispatch(HandshakeContext.java:444) 
       at java.base/sun.security.ssl.HandshakeContext.dispatch(HandshakeContext.java:421) 
       at java.base/sun.security.ssl.TransportContext.dispatch(TransportContext.java:178) 
       at java.base/sun.security.ssl.SSLTransport.decode(SSLTransport.java:164) 
       at java.base/sun.security.ssl.SSLSocketImpl.decode(SSLSocketImpl.java:1152) 
       at java.base/sun.security.ssl.SSLSocketImpl.readHandshakeRecord(SSLSocketImpl.java:1063) 
       at java.base/sun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:402) 
       at TLSServer$ServerThread.run(TLSServer.java:92) 
    Caused by: java.security.InvalidKeyException: No installed provider supports this key: sun.security.pkcs11.P11Key$P11PrivateKey 
       at java.base/java.security.Signature$Delegate.chooseProvider(Signature.java:1163) 
       at java.base/java.security.Signature$Delegate.engineInitSign(Signature.java:1204) 
       at java.base/java.security.Signature.initSign(Signature.java:546) 
       at java.base/sun.security.ssl.SignatureScheme.getSignature(SignatureScheme.java:473) 
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyMessage.<init>(CertificateVerify.java:895) 
    
  • Storing EC keys in the PKCS11 module and using Java 11:
    java.lang.ClassCastException: class sun.security.pkcs11.P11Key$P11PrivateKey cannot be cast to class java.security.interfaces.ECPrivateKey (sun.security.pkcs11.P11Key$P11PrivateKey is in module jdk.crypto.cryptoki of loader 'platform'; java.security.interfaces.ECPrivateKey is in module java.base of loader 'bootstrap') 
       at java.base/sun.security.ssl.SignatureScheme.getPreferableAlgorithm(SignatureScheme.java:436) 
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyMessage.<init>(CertificateVerify.java:867) 
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyProducer.onProduceCertificateVerify(CertificateVerify.java:1077)
       at java.base/sun.security.ssl.CertificateVerify$T13CertificateVerifyProducer.produce(CertificateVerify.java:1070) 
       at java.base/sun.security.ssl.SSLHandshake.produce(SSLHandshake.java:436) 
       at java.base/sun.security.ssl.ClientHello$T13ClientHelloConsumer.goServerHello(ClientHello.java:1224) 
       at java.base/sun.security.ssl.ClientHello$T13ClientHelloConsumer.consume(ClientHello.java:1160) 
       at java.base/sun.security.ssl.ClientHello$ClientHelloConsumer.onClientHello(ClientHello.java:849) 
       at java.base/sun.security.ssl.ClientHello$ClientHelloConsumer.consume(ClientHello.java:810) 
    

You can enable SSL debugging as indicated in the following articles depending on your product:

Recent Changes

Upgraded to Java 11.

Implemented an HSM via the PKCS11 module and kept the default protocol (TLS 1.3 is the default protocol used for a PKCS11 HSM).

Used EC keys stored in PKCS11.

Causes

There are two JDK bugs that are causing these issues:

These errors are a result of bugs in the JDK rather than being issues with ForgeRock products.

Solution

Until the JDK bugs are fixed, you can workaround these issues as follows:

  • SSLHandshakeException error - you can either use TLS 1.2 or you can downgrade Java to JDK 1.8.
  • ClassCastException error - the only workaround for this issue is to downgrade Java to JDK 1.8.

See Also

Security Guide › Using a Hardware Security Module

Integrator's Guide › Configuring IDM For a Hardware Security Module (HSM) Device

How do I configure AM/OpenAM (All versions) to use a Hardware Security Module (HSM) for signing SAML assertions?

Federation related pages do not display in the console with a java.lang.NoClassDefFoundError: sun/misc/CharacterEncoder error in AM 6.5.x

Related Training

N/A

Related Issue Tracker IDs

OPENDJ-5761 (java.security.InvalidKeyException during SSL Handshake with keys in SoftHSM)


LDAPS client connections fail with SSLHandshakeException: no cipher suites in common in DS 5 and OpenDJ 3.x

The purpose of this article is to provide assistance if ldapsearch fails with a "javax.net.ssl.SSLHandshakeException: no cipher suites in common" error in DS/OpenDJ when connecting via LDAPS if you are using Java® 7.

Symptoms

The following error is shown when searching using the ldapsearch command if you are connecting to DS/OpenDJ via LDAPS:

java.net.SocketException: Socket Closed 
at java.net.PlainSocketImpl.setOption(PlainSocketImpl.java:201) 
at java.net.Socket.setSoTimeout(Socket.java:1017) 
at com.sun.net.ssl.internal.ssl.SSLSocketImpl.setSoTimeout(SSLSocketImpl.java:2107) 
at org.opends.server.tools.LDAPConnection.connectToHost(LDAPConnection.java:507) 
at org.opends.server.tools.LDAPSearch.mainSearch(LDAPSearch.java:1777) 
at org.opends.server.tools.LDAPSearch.main(LDAPSearch.java:580) 
Cannot send the simple bind request: SSLHandshakeException(Remote host closed connection during handshake) 
Result Code: 81 (Server Connection Closed) 

An error similar to the following is shown in the DS/OpenDJ access log when the above error is received:

[21/Sep/2014:10:07:52 +0200] DISCONNECT conn=9359 reason="I/O Error" msg="An IO error occurred while reading a request from the client: javax.net.ssl.SSLHandshakeException: no cipher suites in common"

Recent Changes

Upgraded to Java 7 (pre-update 51).

Configured LDAPS (LDAP/SSL) between the client and the server.

Causes

The SSL error is caused by the client failing to encode the SSL handshake protocol properly; the no cipher suites in common relates to the client offering cipher suites that are not supported by the server.

This issue occurs when using DH (Diffie-Hellman) based cipher suites (such as: TLS_DHE_RSA_WITH_AES_128_CBC_SHA) and is a known Java 7 issue: JDK-8014618 : Need to strip leading zeros in TlsPremasterSecret of DHKeyAgreement

You can check which cipher suites are being used by performing a simple search for "supportedTLSCiphers supportedTLSProtocols" as described in Administration Guide › To List Protocols and Cipher Suites.

Solution

This issue can be resolved by upgrading to at least Java 7u51 or by using non-DH cipher suites.

To use non-DH cipher suites:

You can either configure your client to use non-DH cipher suites or configure the LDAPS connection handler in DS/OpenDJ to offer a limited set of cipher suites using the dsconfig set-connection-handler-prop command.

For example, to permit TLS_RSA_WITH_AES_128_CBC_SHA and SSL_RSA_WITH_RC4_128_SHA cipher suites, you would use a command similar to the following:

$ ./dsconfig set-connection-handler-prop --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --handler-name "LDAPS Connection Handler" --add ssl-cipher-suite:TLS_EMPTY_RENEGOTIATION_INFO_SCSV --add ssl-cipher-suite:TLS_RSA_WITH_AES_128_CBC_SHA --add ssl-cipher-suite:SSL_RSA_WITH_RC4_128_SHA -n -X
Note

The TLS_EMPTY_RENEGOTIATION_INFO_SCSV cipher suite is a special cipher suite used by Java and should always be included.

See Also

FAQ: SSL certificate management in DS/OpenDJ

Invalid Padding length error when attempting to connect to DS 5 or OpenDJ 3.x via LDAPS

How do I troubleshoot connection via LDAPS issues in DS/OpenDJ (All versions)?

How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) administration port?

How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) replication port?

SSL in DS/OpenDJ

Configuration Reference › LDAP Connection Handler

OpenDJ: Troubleshooting LDAP SSL connections

Related Training

N/A

Related Issue Tracker IDs

N/A


Invalid Padding length error when attempting to connect to DS 5 or OpenDJ 3.x via LDAPS

The purpose of this article is to provide assistance if you receive a "javax.net.ssl.SSLHandshakeException: Invalid Padding length" error when attempting to connect to DS/OpenDJ via LDAPS if you are using Java® 7.

Symptoms

The following error is shown intermittently when attempting to connect to DS/OpenDJ via LDAPS:

LDAP local: ldap_simple_bind_s Can't contact LDAP server

An error similar to the following is shown in the DS/OpenDJ log when the above error is received:

[21/Sep/2014:10:07:52 +0200] CONNECT conn=23 from=100.10.0.10:8080 to=100.10.10.10:1636 protocol=LDAPS
[21/Sep/2014:10:07:52 +0200] DISCONNECT conn=2 reason="I/O Error" msg="An IO error occurred while reading a request from the client: javax.net.ssl.SSLHandshakeException: Invalid Padding length: 227"

Recent Changes

Upgraded to Java 7.

Configured LDAPS (LDAP/SSL) between the client and the server.

Causes

The SSL error is caused by the client failing to encode the SSL handshake protocol properly; the invalid padding length refers to a block size error occurring when specific block based encryption is used.

This issue occurs when using DH (Diffie-Hellman) based cipher suites (such as: TLS_DHE_RSA_WITH_AES_128_CBC_SHA) and is a known issue on Linux® systems using Java 7: SSL intermittent problem when using DH-based ciphers in Java 7 with Linux although it can affect other operating systems.

You can check which cipher suites are being used by performing a simple search for "supportedTLSCiphers supportedTLSProtocols" as described in Administration Guide › To List Protocols and Cipher Suites.

Solution

This issue can be resolved by upgrading to Java 8 or by using non-DH cipher suites.

To use non-DH cipher suites:

You can either configure your client to use non-DH cipher suites or configure the LDAPS connection handler in DS/OpenDJ to offer a limited set of cipher suites using the dsconfig set-connection-handler-prop command.

For example, to permit TLS_RSA_WITH_AES_128_CBC_SHA and SSL_RSA_WITH_RC4_128_SHA cipher suites, you would use a command similar to the following:

$ ./dsconfig set-connection-handler-prop --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --handler-name "LDAPS Connection Handler" --add ssl-cipher-suite:TLS_EMPTY_RENEGOTIATION_INFO_SCSV --add ssl-cipher-suite:TLS_RSA_WITH_AES_128_CBC_SHA --add ssl-cipher-suite:SSL_RSA_WITH_RC4_128_SHA -n -X
Note

The TLS_EMPTY_RENEGOTIATION_INFO_SCSV cipher suite is a special cipher suite used by Java and should always be included.

See Also

LDAPS client connections fail with SSLHandshakeException: no cipher suites in common in DS 5 and OpenDJ 3.x

How do I troubleshoot connection via LDAPS issues in DS/OpenDJ (All versions)?

How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) administration port?

How do I prevent the use of weak SSL cipher suites on DS/OpenDJ (All versions) replication port?

SSL in DS/OpenDJ

Administration Guide › TLS Protocols and Cipher Suites

Configuration Reference › LDAP Connection Handler

OpenDJ: Troubleshooting LDAP SSL connections

Related Training

N/A

Related Issue Tracker IDs

N/A


DS (All versions) fails to start when using a JKS keystore from an earlier version

The purpose of this article is to provide assistance if DS fails to start when using a JKS keystore, which was likely copied from an earlier version of OpenDJ. You will see "An error occurred while trying to load the keystore contents from file /path/to/ds/keystore: IOException(DerInputStream.getLength(): lengthTag=109, too big.)" message when this happens.

Symptoms

The following error is shown when DS fails to start:

category=CORE severity=NOTICE msgID=139 msg=The Directory Server has sent an alert notification generated by class org.opends.server.core.DirectoryServer (alert type org.opends.server.DirectoryServerShutdown, alert ID org.opends.messages.core-141): The Directory Server has started the shutdown process. The shutdown was initiated by an instance of class org.opends.server.core.DirectoryServer and the reason provided for the shutdown was An error occurred while trying to start the Directory Server: InitializationException: An error occurred while attempting to initialize the SSL context for use in the LDAP Connection Handler: An error occurred while trying to load the keystore contents from file /path/to/ds/keystore: IOException(DerInputStream.getLength(): lengthTag=109, too big.) (id=org.opends.messages.extension-62) (LDAPConnectionHandler.java:416 LDAPConnectionHandler.java:114 ConnectionHandler.java:134 AdministrationConnector.java:95 ConnectionHandlerConfigManager.java:240 ConnectionHandlerConfigManager.java:203 DirectoryServer.java:1546 DirectoryServer.java:1317 DirectoryServer.java:4210)

Recent Changes

Installed DS 5 or later, and used a keystore from an earlier version of OpenDJ.

Causes

The default keystore format in DS 5 and later is PKCS#12. If you use a different keystore type (such as a JKS keystore from an earlier version of OpenDJ) DS will fail to start due to the keystore incompatibility.

The default keystore type in OpenDJ 3.5.x and earlier was JKS. Changes were made in DS 5 to simplify the default keystore and truststore configuration; this included changing the default keystore format to PKCS#12. See Release Notes › Important Changes to Existing Functionality (setup tool) for further information.

Solution

This issue can be resolved using one of the following approaches:

  • Convert your existing JKS keystore to PKCS#12 using keytool, for example:
    $ keytool -importkeystore -srckeystore [existing_JKS_keystore] -srcstoretype JKS -srcstorepass password -destkeystore new-keystore -deststoretype PKCS12 -deststorepass password -destkeypass password
  • Change the Default Key Manager to JKS using dsconfig, for example:
    $ ./dsconfig set-key-manager-provider-prop --provider-name "Default Key Manager" --set key-store-type:JKS --hostname ds1.example.com --port 4444 --bindDn "cn=Directory Manager" --bindPassword password --trustAll --no-prompt
    
    You can now continue to use the JKS keystore with DS.

See Also

SSL in DS/OpenDJ

Security Guide › Managing Certificates and Private Keys

Related Training

N/A

Related Issue Tracker IDs

N/A


Enabling or initializing replication interactively fails in DS (All versions) and OpenDJ 3.x with There is an error with the certificate presented by the server

The purpose of this article is to provide assistance if you cannot enable or initialize replication in interactive mode in DS/OpenDJ. You will see "There is an error with the certificate presented by the server" error.

Symptoms

The following error is shown when attempting to enable or initialize replication interactively using the dsreplication menu with option 1 (Enable Replication) or option 3 (Initialize Replication on one Server):

Establishing connections ..... 
Error reading data from server localhost:4444. There is an error with the certificate presented by the server.
Details: simple bind failed: localhost:4444

You should also be aware that:

  • Using option 4 (Initialize All Servers) appears to be successful, but the servers are not in sync.
  • You can enable or initialize replication successfully via the command line. 

Recent Changes

Upgraded to, or installed DS 5 or later.

Upgraded to, or installed OpenDJ 3.x.

Causes

This is a trust issue caused by the order of operations in how you enabled/initialized replication interactively:

  • If you launch dsreplication on Master 1 and use Master 1's connection details for the first server, replication is not enabled or initialized because Master 1 does not trust Master 2's replication certificate.
  • If you launch dsreplication on Master 1 and use Master 2's connection details for the first server, Master 1 connects to Master 2, retrieves the replication certificate and sets up a trust relationship; this allows replication to be successfully enabled or initialized.

Solution

This issue can be resolved by specifying the correct connection details for the first server. Per the explanation above, you must specify the remote server as the first server (rather than the local server) to allow a trust relationship to be formed.

Alternatively, you can use the command line to enable and/or initialize replication:

  • Enable replication using the dsreplication command applicable to your version:
    • DS 5 and later:
      $ ./dsreplication configure --adminUid admin --adminPassword password --baseDn dc=example,dc=com --host1 ds1.example.com --port1 4444 --bindDn1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 8989 --host2 ds2.example.com --port2 4444 --bindDn2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 8989 --trustAll --no-prompt
    • Pre-DS 5:
      $ ./dsreplication enable --adminUID admin --adminPassword password --baseDN dc=example,dc=com --host1 ds1.example.com --port1 4444 --bindDN1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 8989 --host2 ds2.example.com --port2 4444 --bindDN2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 8989 --trustAll --no-prompt
  • Initialize the new server to ensure both servers have the same data:
    $ ./dsreplication initialize --adminUID admin --adminPassword password --baseDN dc=example,dc=com --hostSource ds1.example.com --portSource 4444 --hostDestination ds2.example.com --portDestination 4444 --trustAll --no-prompt

See Administration Guide › To Configure Replication Interactively for further information. 

See Also

Replication in DS/OpenDJ

Administration Guide › Configuring Replication

Related Training

N/A

Related Issue Tracker IDs

OPENDJ-3475 (Docs: Replication (interactively) fails when using the local master as the "First Servers" )


Copyright and TrademarksCopyright © 2018 - 2019 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...