Supported SSL/TLS versions by JDK version
editSupported SSL/TLS versions by JDK version
editElasticsearch 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
editThe 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
editFor 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
editWithin 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
editEdit 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
editTo 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
editSSL/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.