elasticsearch/docs/reference/settings/ssl-settings.asciidoc

==== {component} TLS/SSL settings
You can configure the following TLS/SSL settings.

ifdef::server[]
+{ssl-prefix}.ssl.enabled+::
(<<static-cluster-setting,Static>>)
Used to enable or disable TLS/SSL on the {ssl-layer}. The default is `false`.
endif::server[]

+{ssl-prefix}.ssl.supported_protocols+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols]

ifdef::server[]
+{ssl-prefix}.ssl.client_authentication+::
(<<static-cluster-setting,Static>>)
Controls the server's behavior in regard to requesting a certificate
from client connections. Valid values are `required`, `optional`, and `none`.
`required` forces a client to present a certificate, while `optional`
requests a client certificate but the client is not required to present one.
ifndef::client-auth-default[]
Defaults to `required`.
endif::client-auth-default[]
ifdef::client-auth-default[]
Defaults to +{client-auth-default}+.
endif::client-auth-default[]
endif::server[]

+{ssl-prefix}.ssl.verification_mode+::
(<<static-cluster-setting,Static>>)
ifndef::verifies[]
The SSL settings in `pass:a[{ssl-prefix}.ssl]` control a _server context_ for TLS, which
defines the settings for the TLS connection. The use of `verification_mode` in
a TLS _server_ is discouraged. 
endif::verifies[]
Defines how to verify the certificates presented by another party in the TLS 
connection:
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values]

+{ssl-prefix}.ssl.cipher_suites+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values]

[#{ssl-context}-tls-ssl-key-trusted-certificate-settings]
===== {component} TLS/SSL key and trusted certificate settings

The following settings are used to specify a private key, certificate, and the
trusted certificates that should be used when communicating over an SSL/TLS connection.
ifdef::server[]
A private key and certificate must be configured.
endif::server[]
ifndef::server[]
A private key and certificate are optional and would be used if the server requires client authentication for PKI
authentication.
endif::server[]

===== PEM encoded files

When using PEM encoded files, use the following settings:

+{ssl-prefix}.ssl.key+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-pem]

+{ssl-prefix}.ssl.key_passphrase+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase]

+{ssl-prefix}.ssl.secure_key_passphrase+::
(<<secure-settings,Secure>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase]

+{ssl-prefix}.ssl.certificate+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate]

+{ssl-prefix}.ssl.certificate_authorities+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities]

===== Java keystore files

When using Java keystore files (JKS), which contain the private key, certificate
and certificates that should be trusted, use the following settings:

+{ssl-prefix}.ssl.keystore.path+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]

+{ssl-prefix}.ssl.keystore.password+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]

+{ssl-prefix}.ssl.keystore.secure_password+::
(<<secure-settings,Secure>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]

+{ssl-prefix}.ssl.keystore.key_password+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password]

+{ssl-prefix}.ssl.keystore.secure_key_password+::
(<<secure-settings,Secure>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password]

+{ssl-prefix}.ssl.truststore.path+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]

+{ssl-prefix}.ssl.truststore.password+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]

+{ssl-prefix}.ssl.truststore.secure_password+::
(<<secure-settings,Secure>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]

[#{ssl-context}-pkcs12-files]
===== PKCS#12 files

{es} can be configured to use PKCS#12 container files (`.p12` or `.pfx` files)
that contain the private key, certificate and certificates that should be trusted.

PKCS#12 files are configured in the same way as Java keystore files:

+{ssl-prefix}.ssl.keystore.path+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]

+{ssl-prefix}.ssl.keystore.type+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12]

+{ssl-prefix}.ssl.keystore.password+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]

+{ssl-prefix}.ssl.keystore.secure_password+::
(<<secure-settings,Secure>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]

+{ssl-prefix}.ssl.keystore.key_password+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password]

+{ssl-prefix}.ssl.keystore.secure_key_password+::
(<<secure-settings,Secure>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password]

+{ssl-prefix}.ssl.truststore.path+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]

+{ssl-prefix}.ssl.truststore.type+::
(<<static-cluster-setting,Static>>)
Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file.
//TBD:Should this use the ssl-truststore-type definition and default values?

+{ssl-prefix}.ssl.truststore.password+::
(<<static-cluster-setting,Static>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]

+{ssl-prefix}.ssl.truststore.secure_password+::
(<<secure-settings,Secure>>)
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]