This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.

« Enabling cipher suites for stronger encryption Security files »

› › ›

Supported SSL/TLS versions by JDK version

edit

Supported SSL/TLS versions by JDK version

edit

Elasticsearch relies on your JDK’s implementation of SSL and TLS.

Different JDK versions support different versions of SSL, and this may affect how Elasticsearch operates.

This support applies when running on the default JSSE provider in the JDK. JVMs that are configured to use a FIPS 140-2 security provider might have a custom TLS implementation, which might support TLS protocol versions that differ from this list.

Check your security provider’s release notes for information on TLS support.

SSLv3: SSL v3 is supported on all Elasticsearch compatible JDKs but is disabled by default. See Enabling additional SSL/TLS versions on your JDK.
TLSv1: TLS v1.0 is supported on all Elasticsearch compatible JDKs. Some newer JDKs, including the JDK bundled with Elasticsearch, disable TLS v1.0 by default. See Enabling additional SSL/TLS versions on your JDK.
TLSv1.1: TLS v1.1 is supported on all Elasticsearch compatible JDKs. Some newer JDKs, including the JDK bundled with Elasticsearch, disable TLS v1.1 by default. See Enabling additional SSL/TLS versions on your JDK.
TLSv1.2: TLS v1.2 is supported on all Elasticsearch compatible JDKs. It is enabled by default on all JDKs that are supported by Elasticsearch, including the bundled JDK.
TLSv1.3: TLS v1.3 is supported on JDK11 and later, and JDK8 builds newer than 8u261 (including the most recent release of each JDK8 distribution that Elasticsearch supports). TLS v1.3 is supported and enabled by default on the JDK that is bundled with Elasticsearch.

Although Elasticsearch supports running on older JDK8 builds without TLS v1.3, we recommend upgrading to a JDK version that includes TLS v1.3 for better support and updates.

Enabling additional SSL/TLS versions on your JDK

edit

The set of supported SSL/TLS versions for a JDK is controlled by a java security properties file that is installed as part of your JDK.

This configuration file lists the SSL/TLS algorithms that are disabled in that JDK. Complete these steps to remove a TLS version from that list and use it in your JDK.

Locate the configuration file for your JDK.
Copy the jdk.tls.disabledAlgorithms setting from that file, and add it to a custom configuration file within the Elasticsearch configuration directory.
In the custom configuration file, remove the value for the TLS version you want to use from jdk.tls.disabledAlgorithms.
Configure Elasticsearch to pass a custom system property to the JDK so that your custom configuration file is used.

Locate the configuration file for your JDK

edit

For the Elasticsearch bundled JDK, the configuration file is in a sub directory of the Elasticsearch home directory ($ES_HOME):

Linux: $ES_HOME/jdk/conf/security/java.security
Windows: $ES_HOME/jdk/conf/security/java.security
macOS:$ES_HOME/jdk.app/Contents/Home/conf/security/java.security

For JDK8, the configuration file is within the jre/lib/security directory of the Java installation. If $JAVA_HOME points to the home directory of the JDK that you use to run Elasticsearch, then the configuration file will be in:

$JAVA_HOME/jre/lib/security/java.security

For JDK11 or later, the configuration file is within the conf/security directory of the Java installation. If $JAVA_HOME points to the home directory of the JDK that you use to run Elasticsearch, then the configuration file will be in:

$JAVA_HOME/conf/security/java.security

Copy the disabledAlgorithms setting

edit

Within the JDK configuration file is a line that starts with jdk.tls.disabledAlgorithms=. This setting controls which protocols and algorithms are disabled in your JDK. The value of that setting will typically span multiple lines.

For example, in OpenJDK 16 the setting is:

jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, RC4, DES, MD5withRSA, \
    DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL

Create a new file in your in your Elasticsearch configuration directory named es.java.security. Copy the jdk.tls.disabledAlgorithms setting from the JDK’s default configuration file into es.java.security. You do not need to copy any other settings.

Enable required TLS versions

edit

Edit the es.java.security file in your Elasticsearch configuration directory, and modify the jdk.tls.disabledAlgorithms setting so that any SSL or TLS versions that you wish to use are no longer listed.

For example, to enable TLSv1.1 on OpenJDK 16 (which uses the jdk.tls.disabledAlgorithms settings shown previously), the es.java.security file would contain the previously disabled TLS algorithms except TLSv1.1:

jdk.tls.disabledAlgorithms=SSLv3, TLSv1, RC4, DES, MD5withRSA, \
    DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL

Enable your custom security configuration

edit

To enable your custom security policy, add a file in the jvm.options.d directory within your Elasticsearch configuration directory.

To enable your custom security policy, create a file named java.security.options within the jvm.options.d directory of your Elasticsearch configuration directory, with this content:

-Djava.security.properties=/path/to/your/es.java.security

Enabling TLS versions in Elasticsearch

edit

SSL/TLS versions can be enabled and disabled within Elasticsearch via the ssl.supported_protocols settings.

Elasticsearch will only support the TLS versions that are enabled by the underlying JDK. If you configure ssl.supported_procotols to include a TLS version that is not enabled in your JDK, then it will be silently ignored.

Similarly, a TLS version that is enabled in your JDK, will not be used unless it is configured as one of the ssl.supported_protocols in Elasticsearch.

« Enabling cipher suites for stronger encryption Security files »