elasticsearch/x-pack/docs/en/security/securing-communications/tls-versions-jdk.asciidoc

[role="xpack"]
[[jdk-tls-versions]]
=== Supported SSL/TLS versions by JDK version

{es} relies on your JDK's implementation of SSL and TLS.

Different JDK versions support different versions of SSL, and this may affect how {es} operates.

[NOTE]
====
This support applies when running on the default JSSE provider in the JDK.
JVMs that are configured to use a <<fips-140-compliance, 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 {es} <<jvm-version,compatible JDKs>> but is disabled by default.
See <<jdk-enable-tls-protocol>>.

`TLSv1`::
TLS v1.0 is supported on all {es} <<jvm-version,compatible JDKs>>.
Some newer JDKs, including the JDK bundled with {es}, disable TLS v1.0 by default.
See <<jdk-enable-tls-protocol>>.

`TLSv1.1`::
TLS v1.1 is supported on all {es} <<jvm-version,compatible JDKs>>.
Some newer JDKs, including the JDK bundled with {es}, disable TLS v1.1 by default.
See <<jdk-enable-tls-protocol>>.

`TLSv1.2`::
TLS v1.2 is supported on all {es} <<jvm-version,compatible JDKs>>.
It is enabled by default on all JDKs that are supported by {es}, 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 {es} supports).
TLS v1.3 is supported and enabled by default on the JDK that is bundled with {es}.
+
NOTE: Although {es} 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.

[[jdk-enable-tls-protocol]]
==== Enabling additional SSL/TLS versions on your JDK

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.

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

===== Locate the configuration file for your JDK

For the {es} **bundled JDK**, the configuration file is in a sub directory of
the {es} 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 {es},
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
{es}, then the configuration file will be in:

* `$JAVA_HOME/conf/security/java.security`

===== Copy the disabledAlgorithms setting

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:
[source,text]
--------------------------------------------------
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 {es} 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 the `es.java.security` file in your {es} 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`:

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

===== Enable your custom security configuration

To enable your custom security policy, add a file in the <<set-jvm-options, `jvm.options.d`>>
directory within your {es} configuration directory.

To enable your custom security policy, create a file named
`java.security.options` within the <<set-jvm-options, jvm.options.d>>
directory of your {es} configuration directory, with this content:

[source,text]
----
-Djava.security.properties=/path/to/your/es.java.security
----

==== Enabling TLS versions in {es}

SSL/TLS versions can be enabled and disabled within {es} via the
<<ssl-tls-settings,`ssl.supported_protocols` settings>>.

{es} will only support the TLS versions that are enabled by the
<<jdk-tls-versions,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 {es}.