[7.x][DOCS] Adds common definitions for security settings (#51017) (#53242)

Co-Authored-By: Tim Vernum <tim@adjective.org>

docs/reference/settings/common-defs.asciidoc

@@ -0,0 +1,149 @@
+tag::ssl-certificate[]
+Specifies the path for the PEM encoded certificate (or certificate chain) that is
+associated with the key.
+//TBD: This setting can be used only if `ssl.key` is set.
+end::ssl-certificate[]
+
+tag::ssl-certificate-authorities[]
+List of paths to PEM encoded certificate files that should be trusted.
+//TBD: You cannot use this setting and `ssl.truststore.path` at the same time.
+end::ssl-certificate-authorities[]
+
+tag::ssl-cipher-suites-values[]
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values-java11]
+end::ssl-cipher-suites-values[]
+
+tag::ssl-cipher-suites-values-java11[]
+Supported cipher suites vary depending on which version of Java you use. For
+example, for version 11 the default value is `TLS_AES_256_GCM_SHA384`, 
+`TLS_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, 
+`TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`,   
+`TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, 
+`TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, 
+`TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`, `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`,  
+`TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, 
+`TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`, `TLS_RSA_WITH_AES_256_GCM_SHA384`,
+`TLS_RSA_WITH_AES_128_GCM_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA256`,
+`TLS_RSA_WITH_AES_128_CBC_SHA256`, `TLS_RSA_WITH_AES_256_CBC_SHA`,
+`TLS_RSA_WITH_AES_128_CBC_SHA`.
++
+--
+NOTE: The default cipher suites list above includes TLSv1.3 ciphers and ciphers
+that require the _Java Cryptography Extension (JCE) Unlimited Strength
+Jurisdiction Policy Files_ for 256-bit AES encryption. If TLSv1.3 is not
+available, the TLSv1.3 ciphers `TLS_AES_256_GCM_SHA384` and
+`TLS_AES_128_GCM_SHA256` are not included in the default list. If 256-bit AES is
+unavailable, ciphers with `AES_256` in their names are not included in the
+default list. Finally, AES GCM has known performance issues in Java versions
+prior to 11 and is included in the default list only when using Java 11 or above.
+
+For more information, see Oracle's
+https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2[Java Cryptography Architecture documentation].
+--
+end::ssl-cipher-suites-values-java11[]
+
+tag::ssl-key-pem[]
+Path to a PEM encoded file containing the private key.
+//TBD: You cannot use this setting and `ssl.keystore.path` at the same time.
+end::ssl-key-pem[]
+
+tag::ssl-key-passphrase[]
+The passphrase that is used to decrypt the private key. Since the key might not
+be encrypted, this value is optional.
+//TBD: You cannot use this setting and `ssl.secure_key_passphrase` at the same time.
+end::ssl-key-passphrase[]
+
+tag::ssl-keystore-key-password[]
+The password for the key in the keystore. The default is the keystore password.
+//TBD: You cannot use this setting and `ssl.keystore.secure_key_password` at the same time.
+end::ssl-keystore-key-password[]
+
+tag::ssl-keystore-password[]
+The password for the keystore.
+//TBD: You cannot use this setting and `ssl.keystore.secure_password` at the same time.
+end::ssl-keystore-password[]
+
+tag::ssl-keystore-path[]
+The path for the keystore file that contains a private key and certificate.
+//TBD: It must be either a Java keystore (jks) or a PKCS#12 file.
+//TBD: You cannot use this setting and `ssl.key` at the same time.
+end::ssl-keystore-path[]
+
+tag::ssl-keystore-secure-key-password[]
+The password for the key in the keystore. The default is the keystore password.
+//TBD: You cannot use this setting and `ssl.keystore.key_password` at the same time.
+end::ssl-keystore-secure-key-password[]
+
+tag::ssl-keystore-secure-password[]
+The password for the keystore.
+//TBD: You cannot use this setting and `ssl.keystore.password` at the same time.
+end::ssl-keystore-secure-password[]
+
+tag::ssl-keystore-type-pkcs12[]
+The format of the keystore file. It must be either `jks` or `PKCS12`. If the
+keystore path ends in ".p12", ".pfx", or ".pkcs12", this setting defaults 
+to `PKCS12`. Otherwise, it defaults to `jks`.
+end::ssl-keystore-type-pkcs12[]
+
+tag::ssl-secure-key-passphrase[]
+The passphrase that is used to decrypt the private key. Since the key might not
+be encrypted, this value is optional. 
+//TBD: You cannot use this setting and `ssl.key_passphrase` at the same time.
+end::ssl-secure-key-passphrase[]
+
+tag::ssl-supported-protocols[]
+Supported protocols with versions. Valid protocols: `SSLv2Hello`,
+`SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. If the JVM's SSL provider supports TLSv1.3,
+the default is `TLSv1.3,TLSv1.2,TLSv1.1`. Otherwise, the default is
+`TLSv1.2,TLSv1.1`.
++
+--
+NOTE: If `xpack.security.fips_mode.enabled` is `true`, you cannot use `SSLv2Hello` 
+or `SSLv3`. See <<fips-140-compliance>>.
+
+--
+end::ssl-supported-protocols[]
+
+tag::ssl-truststore-password[]
+The password for the truststore.
+//TBD: You cannot use this setting and `ssl.truststore.secure_password` at the same time.
+end::ssl-truststore-password[]
+
+tag::ssl-truststore-path[]
+The path for the keystore that contains the certificates to trust. It must be
+either a Java keystore (jks) or a PKCS#12 file.
+//TBD: You cannot use this setting and `ssl.certificate_authorities` at the same time.
+end::ssl-truststore-path[]
+
+tag::ssl-truststore-secure-password[]
+Password for the truststore.
+//TBD: You cannot use this setting and `ssl.truststore.password` at the same time.
+end::ssl-truststore-secure-password[]
+
+tag::ssl-truststore-type[]
+The format of the truststore file. It must be either `jks` or `PKCS12`. If the
+file name ends in ".p12", ".pfx" or "pkcs12", the default is `PKCS12`.
+Otherwise, it defaults to `jks`.
+end::ssl-truststore-type[]
+
+tag::ssl-truststore-type-pkcs11[]
+The format of the truststore file. For the Java keystore format, use `jks`. For
+PKCS#12 files, use `PKCS12`. For a PKCS#11 token, use `PKCS11`. The default is
+`jks`.
+end::ssl-truststore-type-pkcs11[]
+
+tag::ssl-verification-mode-values[]
+Valid values are:
+- `full`, which verifies that the provided certificate is signed by a trusted
+authority (CA) and also verifies that the server's hostname (or IP address)
+matches the names identified within the certificate.
+- `certificate`, which verifies that the provided certificate is signed by a
+trusted authority (CA), but does not perform any hostname verification.
+- `none`, which performs _no verification_ of the server's certificate. This
+mode disables many of the security benefits of SSL/TLS and should only be used
+after very careful consideration. It is primarily intended as a temporary
+diagnostic mechanism when attempting to resolve TLS errors; its use on
+production clusters is strongly discouraged.
++
+The default value is `full`.
+end::ssl-verification-mode-values[]

docs/reference/settings/security-settings.asciidoc

@@ -9,13 +9,13 @@ By default, the {es} {security-features} are disabled when you have a basic or
 trial license. To enable {security-features}, use the `xpack.security.enabled`
 setting.
 
-You configure `xpack.security` settings  to
-<<anonymous-access-settings, enable anonymous access>>
-and perform message authentication,
-<<field-document-security-settings, set up document and field level security>>,
-<<realm-settings, configure realms>>,
-<<ssl-tls-settings, encrypt communications with SSL>>, and
-<<auditing-settings, audit security events>>.
+You configure `xpack.security` settings to
+<<anonymous-access-settings,enable anonymous access>> and perform message
+authentication,
+<<field-document-security-settings,set up document and field level security>>,
+<<realm-settings,configure realms>>,
+<<ssl-tls-settings,encrypt communications with SSL>>,and
+<<auditing-settings,audit security events>>.
 
 All of these settings can be added to the `elasticsearch.yml` configuration file,
 with the exception of the secure settings, which you add to the {es} keystore.
@@ -354,7 +354,7 @@ The scope of the user search. Valid values are `sub_tree`, `one_level` or
 `base`. `one_level` only searches objects directly contained within the
 `base_dn`. `sub_tree` searches all objects contained under `base_dn`.
 `base` specifies that the `base_dn` is the user object, and that it is
-the only user considered. Defaults to  `sub_tree`.
+the only user considered. Defaults to `sub_tree`.
 
 `user_search.filter`::
 Specifies the filter used to search the directory in attempts to match
@@ -459,78 +459,72 @@ An `s` at the end indicates seconds, or `ms` indicates milliseconds.
 Defaults to `5s` (5 seconds ).
 
 `ssl.key`::
-Path to a PEM encoded file containing the private key, which is used if the 
-LDAP server requires client authentication. `ssl.key` and `ssl.keystore.path` 
-cannot be used at the same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-key-pem]
++
+If the LDAP server requires client authentication, it uses this file. You cannot
+use this setting and `ssl.keystore.path` at the same time.
 
 `ssl.key_passphrase`::
-The passphrase that is used to decrypt the private key. This value is
-optional as the key may not be encrypted.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase]
 
 `ssl.secure_key_passphrase` (<<secure-settings,Secure>>)::
-The passphrase that is used to decrypt the private key.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase]
 
 `ssl.certificate`::
-Path to a PEM encoded file containing the certificate (or certificate chain)
-that will be presented to clients when they connect.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-certificate]
++
+This certificate is presented to clients when they connect.
 
 `ssl.certificate_authorities`::
-List of paths to PEM encoded certificate files that should be trusted. 
-`ssl.certificate_authorities` and `ssl.truststore.path` cannot be used at the 
-same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities]
++
+You cannot use this setting and `ssl.truststore.path` at the same time.
 
 `ssl.keystore.path`::
-The path to the Java Keystore file that contains a private key and certificate.
-`ssl.key` and `ssl.keystore.path` may not be used at the same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]
++
+You cannot use this setting and `ssl.key` at the same time.
 
 `ssl.keystore.type`::
-The format of the keystore file. Should be `jks` to use the Java
-Keystore format, `PKCS12` to use PKCS#12 files, or `PKCS11` to use a PKCS#11 token.
-The default is `jks`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12]
 
 `ssl.keystore.password`::
-The password to the keystore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]
 
 `ssl.keystore.secure_password` (<<secure-settings,Secure>>)::
-The password to the keystore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]
 
 `ssl.keystore.key_password`::
-The password for the key in the keystore. Defaults to the keystore password.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password]
 
 `ssl.keystore.secure_key_password`::
-The password for the key in the keystore. Defaults to the keystore password.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password]
 
 `ssl.truststore.path`::
-The path to the Java Keystore file that contains the certificates to trust.
-`ssl.certificate_authorities` and `ssl.truststore.path` cannot be used at the same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]
++
+You cannot use this setting and `ssl.certificate_authorities` at the same time.
 
 `ssl.truststore.password`::
-The password to the truststore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]
 
 `ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
-The password to the truststore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]
 
 `ssl.truststore.type`::
-The format of the keystore file. Should be `jks` to use the Java
-Keystore format, `PKCS12` to use PKCS#12 files, or `PKCS11` to use a PKCS#11 token.
-The default is `jks`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-type-pkcs11]
 
 `ssl.verification_mode`::
 Indicates the type of verification when using `ldaps` to protect against man
-in the middle attacks and certificate forgery. Values are `none`, `certificate`,
-and `full`. Defaults to `full`.
-+
-See <<ssl-tls-settings,`ssl.verification_mode`>> for an explanation of these values.
+in the middle attacks and certificate forgery.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values]
 
 `ssl.supported_protocols`::
-Supported protocols for TLS/SSL (with versions). Defaults to `TLSv1.3,TLSv1.2,TLSv1.1` if
-the JVM supports TLSv1.3, otherwise `TLSv1.2,TLSv1.1`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols]
 
 `ssl.cipher_suites`:: Specifies the cipher suites that should be supported when 
 communicating with the LDAP server. 
-Supported cipher suites can be found in Oracle's http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html[
-Java Cryptography Architecture documentation]. See <<ssl-tls-settings,`ssl.cipher_suites`>>
-for the default value.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values]
 
 `cache.ttl`::
 Specifies the time-to-live for cached user entries. A user and a hash of its 
@@ -716,81 +710,73 @@ An `s` at the end indicates seconds, or `ms` indicates milliseconds.
 Defaults to `5s` (5 seconds ).
 
 `ssl.certificate`::
-Path to a PEM encoded file containing the certificate (or certificate chain)
-that will be presented to clients when they connect. 
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-certificate]
++
+This certificate is presented to clients when they connect. 
 
 `ssl.certificate_authorities`::
-List of paths to PEM encoded certificate files that should be trusted. 
-`ssl.certificate_authorities` and `ssl.truststore.path` cannot be used at the 
-same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities]
++
+You cannot use this setting and `ssl.truststore.path` at the same time.
 
 `ssl.key`::
-Path to the PEM encoded file containing the private key, which is used when the 
-Active Directory server requires client authentication. `ssl.key` and 
-`ssl.keystore.path` cannot be used at the same time.
-
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-key-pem]
++
+If the Active Directory server requires client authentication, it uses this file.
+You cannot use this setting and `ssl.keystore.path` at the same time.
 
 `ssl.key_passphrase`::
-The passphrase that is used to decrypt the private key. This value is
-optional as the key might not be encrypted.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase]
 
 `ssl.secure_key_passphrase` (<<secure-settings,Secure>>)::
-The passphrase that is used to decrypt the private key. This value is
-optional as the key might not be encrypted.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase]
 
 `ssl.keystore.key_password`::
-The password for the key in the keystore. Defaults to the keystore password.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password]
 
 `ssl.keystore.secure_key_password` (<<secure-settings,Secure>>)::
-The password for the key in the keystore. Defaults to the keystore password.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password]
 
 `ssl.keystore.password`::
-The password to the keystore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]
 
 `ssl.secure_keystore.password` (<<secure-settings,Secure>>)::
-The password to the keystore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]
+//TBD: Why/how is this different than `ssl.keystore.secure_password`?
 
 `ssl.keystore.path`::
-The path to the Java Keystore file that contains a private key and certificate.
-`ssl.key` and `ssl.keystore.path` cannot be used at the same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]
++
+You cannot use this setting and `ssl.key` at the same time.
 
 `ssl.keystore.type`::
-The format of the keystore file. Should be `jks` to use the Java
-Keystore format, `PKCS12` to use PKCS#12 files, or `PKCS11` to use a PKCS#11 token.
-The default is `jks`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12]
 
 `ssl.truststore.password`::
-The password to the truststore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]
 
 `ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
-The password to the truststore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]
 
 `ssl.truststore.path`::
-The path to the Java Keystore file that contains the certificates to trust.
-`ssl.certificate_authorities` and `ssl.truststore.path` cannot be used at the 
-same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]
++
+You cannot use this setting and `ssl.certificate_authorities` at the same time.
 
 `ssl.truststore.type`::
-The format of the truststore file. Should be `jks` to use the Java
-Keystore format, `PKCS12` to use PKCS#12 files, or `PKCS11` to use a PKCS#11 token.
-The default is `jks`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-type-pkcs11]
 
 `ssl.verification_mode`::
 Indicates the type of verification when using `ldaps` to protect against man
-in the middle attacks and certificate forgery. Values are `none`, `certificate`,
-and `full`. Defaults to `full`.
-+
-See <<ssl-tls-settings,`ssl.verification_mode`>> for an explanation of these values.
+in the middle attacks and certificate forgery.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values]
 
 `ssl.supported_protocols`::
-Supported protocols for TLS/SSL (with versions). Defaults to `TLSv1.3,TLSv1.2,TLSv1.1` if
-the JVM supports TLSv1.3, otherwise `TLSv1.2,TLSv1.1`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols]
 
 `ssl.cipher_suites`:: Specifies the cipher suites that should be supported when 
-communicating with the Active Directory server. 
-Supported cipher suites can be found in Oracle's http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html[
-Java Cryptography Architecture documentation]. See <<ssl-tls-settings,`ssl.cipher_suites`>> for
-the default values.
+communicating with the Active Directory server.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values]
 
 `cache.ttl`::
 Specifies the time-to-live for cached user entries. A user and a hash of its 
@@ -839,10 +825,11 @@ for SSL. This setting cannot be used with `truststore.path`.
 Algorithm for the truststore. Defaults to `SunX509`.
 
 `truststore.password`::
-The password for the truststore. Must be provided if `truststore.path` is set.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]
+If `truststore.path` is set, this setting is required.
 
 `truststore.secure_password` (<<secure-settings,Secure>>)::
-The password for the truststore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]
 
 `truststore.path`::
 The path of a truststore to use. Defaults to the trusted certificates configured
@@ -1039,9 +1026,9 @@ Service Provider metadata or manually configured within the IdP to allow for
 signature validation. This setting can only be used if `signing.key` is set.
 
 `signing.keystore.path`::
-The path to the keystore that contains a private key and certificate.
-Must be either a Java Keystore (jks) or a PKCS#12 file.
-`signing.key` and `signing.keystore.path` cannot be used at the same time.
+The path to the keystore that contains a private key and certificate. It must be
+either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
+`signing.key` at the same time.
 
 `signing.keystore.type`::
 The type of the keystore in `signing.keystore.path`.
@@ -1085,9 +1072,9 @@ the Service Provider metadata or manually configured within the IdP to enable
 message encryption. This setting can be used only if `encryption.key` is set.
 
 `encryption.keystore.path`::
-The path to the keystore that contains a private key and certificate.
-Must be either a Java Keystore (jks) or a PKCS#12 file.
-`encryption.key` and `encryption.keystore.path` cannot be used at the same time.
+The path to the keystore that contains a private key and certificate. It must be
+either a Java keystore (jks) or a PKCS#12 file. You cannot use this setting and
+`encryption.key` at the same time.
 
 `encryption.keystore.type`::
 The type of the keystore (`encryption.keystore.path`).
@@ -1119,95 +1106,88 @@ NOTE: These settings are not used for any purpose other than loading metadata
 over https.
 
 `ssl.key`::
-Specifies the path to the PEM encoded private key to use for http client 
-authentication (if required). `ssl.key` and `ssl.keystore.path` cannot be used 
-at the same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-key-pem]
++
+If HTTP client authentication is required, it uses this file. You cannot use
+this setting and `ssl.keystore.path` at the same time.
 
 `ssl.key_passphrase`::
-Specifies the
-passphrase to decrypt the PEM encoded private key (`ssl.key`) if it is
-encrypted. Cannot be used with `ssl.secure_key_passphrase`. 
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase]
++
+You cannot use this setting and `ssl.secure_key_passphrase` at the same time. 
 
 `ssl.secure_key_passphrase` (<<secure-settings,Secure>>)::
-Specifies the
-passphrase to decrypt the PEM encoded private key (`ssl.key`) if it is
-encrypted. Cannot be used with `ssl.key_passphrase`. 
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase]
++
+You cannot use this setting and `ssl.key_passphrase` at the same time.
 
 `ssl.certificate`::
-Specifies the
-path to the PEM encoded certificate (or certificate chain) that is associated
-with the key (`ssl.key`). This setting can be used only if `ssl.key` is set.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-certificate]
++
+This setting can be used only if `ssl.key` is set.
 
 `ssl.certificate_authorities`::
-Specifies the
-paths to the PEM encoded certificate authority certificates that should be
-trusted. `ssl.certificate_authorities` and `ssl.truststore.path` cannot be
-used at the same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities]
++
+This setting and `ssl.truststore.path` cannot be used at the same time.
 
 `ssl.keystore.path`::
-Specifies the path to
-the keystore that contains a private key and certificate.
-Must be either a Java Keystore (jks) or a PKCS#12 file.
-`ssl.key` and `ssl.keystore.path` cannot be used at the same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]
++
+It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this
+setting and `ssl.key` at the same time.
 
 `ssl.keystore.type`::
-The type of the keystore (`ssl.keystore.path`). Must be either `jks` or `PKCS12`.
-If the keystore path ends in ".p12", ".pfx" or "pkcs12", this setting defaults 
-to `PKCS12`. Otherwise, it defaults to `jks`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12]
 
 `ssl.keystore.password`::
-The password to the keystore (`ssl.keystore.path`). This setting cannot be used 
-with `ssl.keystore.secure_password`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]
++
+You cannot use this setting and `ssl.keystore.secure_password` at the same time.
 
 `ssl.keystore.secure_password` (<<secure-settings,Secure>>)::
-The password to the keystore (`ssl.keystore.path`).
-This setting cannot be used with `ssl.keystore.password`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]
++
+You cannot use this setting and `ssl.keystore.password` at the same time.
 
 `ssl.keystore.key_password`::
-The password for the key in the keystore (`ssl.keystore.path`).
-Defaults to the keystore password. This setting cannot be used with 
-`ssl.keystore.secure_key_password`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password]
++
+You cannot use this setting and `ssl.keystore.secure_key_password` at the same
+time.
 
 `ssl.keystore.secure_key_password` (<<secure-settings,Secure>>)::
-The password for the key in the keystore (`ssl.keystore.path`).
-Defaults to the keystore password. This setting cannot be used with 
-`ssl.keystore.key_password`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password]
+You cannot use this setting and `ssl.keystore.key_password` at the same time.
 
 `ssl.truststore.path`::
-The path to the
-keystore that contains the certificates to trust.
-Must be either a Java Keystore (jks) or a PKCS#12 file.
-`ssl.certificate_authorities` and `ssl.truststore.path` cannot be used at the
-same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]
++
+You cannot use this setting and `ssl.certificate_authorities` at the same time.
 
 `ssl.truststore.type`::
-The type of the truststore (`ssl.truststore.path`). Must be either `jks` or
-`PKCS12`. If the keystore path ends in ".p12", ".pfx" or "pkcs12", this setting 
-defaults to `PKCS12`. Otherwise, it defaults to `jks`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-type]
 
 `ssl.truststore.password`::
-The password to the truststore (`ssl.truststore.path`). This setting cannot be 
-used with `ssl.truststore.secure_password`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]
++
+You cannot use this setting and `ssl.truststore.secure_password` at the same
+time.
 
 `ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
-The password to the truststore (`ssl.truststore.path`). This setting cannot be 
-used with `ssl.truststore.password`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]
++
+This setting cannot be used with `ssl.truststore.password`.
 
 `ssl.verification_mode`::
-One of `full`
-(verify the hostname and the certificate path), `certificate` (verify the
-certificate path, but not the hostname) or `none` (perform no verification).
-Defaults to `full`.
-+
-See <<ssl-tls-settings,`ssl.verification_mode`>> for a more detailed explanation of these values.
+Controls the verification of certificates.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values]
 
 `ssl.supported_protocols`::
-Specifies the supported protocols for TLS/SSL. Defaults to `TLSv1.3,TLSv1.2,TLSv1.1` if
-the JVM supports TLSv1.3, otherwise `TLSv1.2,TLSv1.1`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols]
 
 `ssl.cipher_suites`::
-Specifies the
-cipher suites that should be supported.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values]
 
 [float]
 [[ref-kerberos-settings]]
@@ -1401,87 +1381,90 @@ NOTE: These settings are _only_ used for the back-channel communication between
 {es} and the OpenID Connect Provider
 
 `ssl.key`::
-Specifies the path to the PEM encoded private key to use for http client
-authentication (if required). `ssl.key` and `ssl.keystore.path` cannot be used
-at the same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-key-pem]
++
+If HTTP client authentication is required, it uses this file. You cannot use
+this setting and `ssl.keystore.path` at the same time.
 
 `ssl.key_passphrase`::
-Specifies the passphrase to decrypt the PEM encoded private key (`ssl.key`) if it is
-encrypted. Cannot be used with `ssl.secure_key_passphrase`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase]
++
+You cannot use this setting and `ssl.secure_key_passphrase` at the same
+time.
 
 `ssl.secure_key_passphrase` (<<secure-settings,Secure>>)::
-Specifies the passphrase to decrypt the PEM encoded private key (`ssl.key`) if it is
-encrypted. Cannot be used with `ssl.key_passphrase`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase]
++
+You cannot use this setting and `ssl.key_passphrase` at the same time.
 
 `ssl.certificate`::
-Specifies the path to the PEM encoded certificate (or certificate chain) that is associated
-with the key (`ssl.key`). This setting can be used only if `ssl.key` is set.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-certificate]
++
+This setting can be used only if `ssl.key` is set.
 
 `ssl.certificate_authorities`::
-Specifies the paths to the PEM encoded certificate authority certificates that should be
-trusted. `ssl.certificate_authorities` and `ssl.truststore.path` cannot be
-used at the same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities]
++
+This setting and `ssl.truststore.path` cannot be used at the same time.
 
 `ssl.keystore.path`::
-Specifies the path to the keystore that contains a private key and certificate.
-Must be either a Java Keystore (jks) or a PKCS#12 file.
-`ssl.key` and `ssl.keystore.path` cannot be used at the same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]
++
+It must be either a Java keystore (jks) or a PKCS#12 file. You cannot use this
+setting and `ssl.key` at the same time.
 
 `ssl.keystore.type`::
-The type of the keystore (`ssl.keystore.path`). Must be either `jks` or `PKCS12`.
-If the keystore path ends in ".p12", ".pfx" or "pkcs12", this setting defaults
-to `PKCS12`. Otherwise, it defaults to `jks`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12]
 
 `ssl.keystore.password`::
-The password to the keystore (`ssl.keystore.path`). This setting cannot be used
-with `ssl.keystore.secure_password`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]
++
+You cannot use this setting and `ssl.keystore.secure_password` at the same time.
 
 `ssl.keystore.secure_password` (<<secure-settings,Secure>>)::
-The password to the keystore (`ssl.keystore.path`).
-This setting cannot be used with `ssl.keystore.password`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]
++
+You cannot use this setting and `ssl.keystore.password` at the same time.
 
 `ssl.keystore.key_password`::
-The password for the key in the keystore (`ssl.keystore.path`).
-Defaults to the keystore password. This setting cannot be used with
-`ssl.keystore.secure_key_password`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password]
++
+You cannot use this setting and `ssl.keystore.secure_key_password` at the same
+time.
 
 `ssl.keystore.secure_key_password` (<<secure-settings,Secure>>)::
-The password for the key in the keystore (`ssl.keystore.path`).
-Defaults to the keystore password. This setting cannot be used with
-`ssl.keystore.key_password`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password]
++
+You cannot use this setting and `ssl.keystore.key_password` at the same time.
 
 `ssl.truststore.path`::
-The path to the keystore that contains the certificates to trust.
-Must be either a Java Keystore (jks) or a PKCS#12 file.
-`ssl.certificate_authorities` and `ssl.truststore.path` cannot be used at the
-same time.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]
++
+You cannot use this setting and `ssl.certificate_authorities` at the same time.
 
 `ssl.truststore.type`::
-The type of the truststore (`ssl.truststore.path`). Must be either `jks` or
-`PKCS12`. If the keystore path ends in ".p12", ".pfx" or "pkcs12", this setting
-defaults to `PKCS12`. Otherwise, it defaults to `jks`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-type]
 
 `ssl.truststore.password`::
-The password to the truststore (`ssl.truststore.path`). This setting cannot be
-used with `ssl.truststore.secure_password`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]
++
+You cannot use this setting and `ssl.truststore.secure_password` at the same
+time.
 
 `ssl.truststore.secure_password` (<<secure-settings,Secure>>)::
-The password to the truststore (`ssl.truststore.path`). This setting cannot be
-used with `ssl.truststore.password`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]
++
+You cannot use this setting and `ssl.truststore.password` at the same time.
 
 `ssl.verification_mode`::
-One of `full` (verify the hostname and the certificate path), `certificate` (verify the
-certificate path, but not the hostname) or `none` (perform no verification).
-Defaults to `full`.
-+
-See <<ssl-tls-settings,`ssl.verification_mode`>> for a more detailed explanation of these values.
+Controls the verification of certificates.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values]
 
 `ssl.supported_protocols`::
-Specifies the supported protocols for TLS/SSL. Defaults to `TLSv1.3,TLSv1.2,TLSv1.1` if
-the JVM supports TLSv1.3, otherwise `TLSv1.2,TLSv1.1`.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols]
 
 `ssl.cipher_suites`::
-Specifies the cipher suites that should be supported.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values]
 
 [float]
 [[load-balancing]]
@@ -1522,75 +1505,6 @@ cause of the failure and assist with resolving the problem.
 Set to `false` to disable these messages.
 NOTE: This defaults to `false` when `xpack.security.fips_mode.enabled` is `true`.
 
-==== Default values for TLS/SSL settings
-In general, the values below represent the default values for the various TLS
-settings.
-The prefixes for these settings are based on the context in which they are
-used (e.g. `xpack.security.authc.realms.ldap.corp_ldap.ssl.verification_mode`
-or `xpack.security.transport.ssl.supported_protocols`).
-
-For more information, see
-<<encrypting-communications>>.
-
-`*.ssl.supported_protocols`::
-Supported protocols with versions. Valid protocols: `SSLv2Hello`,
-`SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. Defaults to `TLSv1.3,TLSv1.2,TLSv1.1` if
-the JVM supports TLSv1.3, otherwise `TLSv1.2,TLSv1.1`.
-+
---
-NOTE: If `xpack.security.fips_mode.enabled` is `true`, you cannot use `SSLv2Hello` 
-or `SSLv3`. See <<fips-140-compliance>>.
---
-
-`*.ssl.client_authentication`::
-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.
-Defaults to `required`, except for HTTP, which defaults to `none`. See
- <<http-tls-ssl-settings>>.
-
-`*.ssl.verification_mode`::
-Controls the verification of certificates. Valid values are:
-- `full`, which verifies that the provided certificate is signed by a trusted
-       authority (CA) and also verifies that the server's hostname (or IP
-       address) matches the names identified within the certificate.
-- `certificate`, which verifies that the provided certificate is signed by a
-       trusted authority (CA), but does not perform any hostname verification.
-- `none`, which performs _no verification_ of the server's certificate. This mode
-       disables many of the security benefits of SSL/TLS and should only be
-       used after very careful consideration. It is primarily intended as a
-       temporary diagnostic mechanism when attempting to resolve TLS errors,
-       and its use on production clusters is strongly discouraged.
-+
-The default value is `full`.
-
-`*.ssl.cipher_suites`::
-Supported cipher suites can be found in Oracle's
-https://docs.oracle.com/en/java/javase/11/security/oracle-providers.html#GUID-7093246A-31A3-4304-AC5F-5FB6400405E2[Java
- Cryptography Architecture documentation].
-Defaults to `TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`,
-`TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`,
-`TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`,
-`TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`,
-`TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256`,
-`TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`,
-`TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`, `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`,
-`TLS_RSA_WITH_AES_256_GCM_SHA384`, `TLS_RSA_WITH_AES_128_GCM_SHA256`,
-`TLS_RSA_WITH_AES_256_CBC_SHA256`, `TLS_RSA_WITH_AES_128_CBC_SHA256`,
-`TLS_RSA_WITH_AES_256_CBC_SHA`, `TLS_RSA_WITH_AES_128_CBC_SHA`.
-+
---
-NOTE: The default cipher suites list above includes TLSv1.3 ciphers and ciphers
-that require the _Java Cryptography Extension (JCE) Unlimited Strength
-Jurisdiction Policy Files_ for 256-bit AES encryption. If TLSv1.3 is not
-available, the TLSv1.3 ciphers TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`
-will not be included in the default list. If 256-bit AES is unavailable, ciphers
-with `AES_256` in their names wil not be included in the default list. Finally,
-AES GCM has known performance issues in Java versions prior to 11 and will only
-be included in the default list when using Java 11 or above.
---
-
 [float]
 [[tls-ssl-key-settings]]
 ===== TLS/SSL key and trusted certificate settings

docs/reference/settings/ssl-settings.asciidoc

@@ -1,7 +1,5 @@
-==== {component} TLS/SSL Settings
-You can configure the following TLS/SSL settings. If the settings are not configured,
-the {ref}/security-settings.html#ssl-tls-settings[Default TLS/SSL Settings]
-are used.
+==== {component} TLS/SSL settings
+You can configure the following TLS/SSL settings.
 
 ifdef::server[]
 +{ssl-prefix}.ssl.enabled+::
@@ -9,10 +7,7 @@ Used to enable or disable TLS/SSL. The default is `false`.
 endif::server[]
 
 +{ssl-prefix}.ssl.supported_protocols+::
-Supported protocols with versions. Valid protocols: `SSLv2Hello`,
-`SSLv3`, `TLSv1`, `TLSv1.1`, `TLSv1.2`, `TLSv1.3`. Defaults to `TLSv1.3,TLSv1.2,TLSv1.1` if
-the JVM supports TLSv1.3, otherwise `TLSv1.2,TLSv1.1`.
-
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols]
 
 ifdef::server[]
 +{ssl-prefix}.ssl.client_authentication+::
@@ -21,7 +16,7 @@ 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 `none``.
+Defaults to `none`.
 endif::client-auth-default[]
 ifdef::client-auth-default[]
 Defaults to +{client-auth-default}+.
@@ -30,16 +25,15 @@ endif::server[]
 
 ifdef::verifies[]
 +{ssl-prefix}.ssl.verification_mode+::
-Controls the verification of certificates. Valid values are `none`,
-`certificate`, and `full`. Defaults to `full`.
+Controls the verification of certificates.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values]
 endif::verifies[]
 
 +{ssl-prefix}.ssl.cipher_suites+::
-Supported cipher suites can be found in Oracle's http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html[
-Java Cryptography Architecture documentation]. Defaults to ``.
+include::{docdir}/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
+===== {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.
@@ -50,102 +44,96 @@ ifndef::server[]
 A private key and certificate are optional and would be used if the server requires client authentication for PKI
 authentication.
 endif::server[]
-If none of the settings below are specified, the {ref}/security-settings.html#ssl-tls-settings[Default TLS/SSL Settings] are used.
 
-
-===== PEM Encoded Files
+===== PEM encoded files
 
 When using PEM encoded files, use the following settings:
 
 +{ssl-prefix}.ssl.key+::
-Path to a PEM encoded file containing the private key.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-key-pem]
 
 +{ssl-prefix}.ssl.key_passphrase+::
-The passphrase that is used to decrypt the private key. This value is optional
-as the key might not be encrypted.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase]
 
 +{ssl-prefix}.ssl.secure_key_passphrase+ (<<secure-settings,Secure>>)::
-The passphrase that is used to decrypt the private key. This value is optional
-as the key might not be encrypted.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase]
 
 +{ssl-prefix}.ssl.certificate+::
-Path to a PEM encoded file containing the certificate (or certificate chain)
-that will be presented when requested.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-certificate]
 
 +{ssl-prefix}.ssl.certificate_authorities+::
-List of paths to the PEM encoded certificate files that should be trusted.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities]
 
-===== Java Keystore Files
+===== 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+::
-Path to the keystore that holds the private key and certificate.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]
 
 +{ssl-prefix}.ssl.keystore.password+::
-Password to the keystore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]
 
 +{ssl-prefix}.ssl.keystore.secure_password+ (<<secure-settings,Secure>>)::
-Password to the keystore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]
 
 +{ssl-prefix}.ssl.keystore.key_password+::
-Password for the private key in the keystore. Defaults to the
-same value as +{ssl-prefix}.ssl.keystore.password+.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password]
 
 +{ssl-prefix}.ssl.keystore.secure_key_password+ (<<secure-settings,Secure>>)::
-Password for the private key in the keystore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password]
 
 +{ssl-prefix}.ssl.truststore.path+::
-Path to the truststore file.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]
 
 +{ssl-prefix}.ssl.truststore.password+::
-Password to the truststore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]
 
 +{ssl-prefix}.ssl.truststore.secure_password+ (<<secure-settings,Secure>>)::
-Password to the truststore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]
 
 [#{ssl-context}-pkcs12-files]
-===== PKCS#12 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:
+PKCS#12 files are configured in the same way as Java keystore files:
 
 +{ssl-prefix}.ssl.keystore.path+::
-Path to the PKCS#12 file that holds the private key and certificate.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]
 
 +{ssl-prefix}.ssl.keystore.type+::
-Set this to `PKCS12` to indicate that the keystore is a PKCS#12 file.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12]
 
 +{ssl-prefix}.ssl.keystore.password+::
-Password to the PKCS#12 file.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]
 
 +{ssl-prefix}.ssl.keystore.secure_password+ (<<secure-settings,Secure>>)::
-Password to the PKCS#12 file.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]
 
 +{ssl-prefix}.ssl.keystore.key_password+::
-Password for the private key stored in the PKCS#12 file.
-Defaults to the same value as +{ssl-prefix}.ssl.keystore.password+.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password]
 
 +{ssl-prefix}.ssl.keystore.secure_key_password+ (<<secure-settings,Secure>>)::
-Password for the private key stored in the PKCS#12 file.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password]
 
 +{ssl-prefix}.ssl.truststore.path+::
-Path to the PKCS#12 file that holds the certificates to be trusted.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]
 
 +{ssl-prefix}.ssl.truststore.type+::
 Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file.
+//TBD:Should this use the ssl-truststore-type-pkcs11 or ssl-truststore-type definition and default values?
 
 +{ssl-prefix}.ssl.truststore.password+::
-Password to the PKCS#12 file.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]
 
 +{ssl-prefix}.ssl.truststore.secure_password+ (<<secure-settings,Secure>>)::
-Password to the PKCS#12 file.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]
 
 [#{ssl-context}-pkcs11-tokens]
-===== PKCS#11 Tokens
+===== PKCS#11 tokens
 
 {es} can be configured to use a PKCS#11 token that contains the private key,
 certificate and certificates that should be trusted.
@@ -155,9 +143,10 @@ via the following settings:
 
 +{ssl-prefix}.keystore.type+::
 Set this to `PKCS11` to indicate that the PKCS#11 token should be used as a keystore.
+//TBD: Is the default value `jks`?
 
 +{ssl-prefix}.truststore.type+::
-Set this to `PKCS11` to indicate that the PKCS#11 token should be used as a truststore.
+include::{docdir}/settings/common-defs.asciidoc[tag=ssl-truststore-type-pkcs11]
 
 [NOTE]
 When configuring the PKCS#11 token that your JVM is configured to use as

x-pack/docs/en/security/fips-140-compliance.asciidoc

@@ -50,12 +50,12 @@ and able to run {es} successfully in a FIPS 140-2 enabled JVM.
 ==== TLS
 
 SSLv2 and SSLv3 are not allowed by FIPS 140-2, so `SSLv2Hello` and `SSLv3` cannot
-be used for <<ssl-tls-settings, `ssl.supported_protocols`>>
+be used for <<ssl-tls-settings,`ssl.supported_protocols`>>.
 
 NOTE: The use of TLS ciphers is mainly governed by the relevant crypto module
 (the FIPS Approved Security Provider that your JVM uses). All the ciphers that
 are configured by default in {es} are FIPS 140-2 compliant and as such can be
-used in a FIPS 140-2 JVM. (see <<ssl-tls-settings, `ssl.cipher_suites`>>)
+used in a FIPS 140-2 JVM. See <<ssl-tls-settings,`ssl.cipher_suites`>>.
 
 [float]
 ==== TLS Keystores and keys
@@ -71,9 +71,8 @@ options, and for trust material you can use `*.certificate_authorities`.
 
 FIPS 140-2 compliance dictates that the length of the public keys used for TLS
 must correspond to the strength of the symmetric key algorithm in use in TLS.
-Depending on the value of <<ssl-tls-settings, `ssl.cipher_suites`>> that
-you select to use, the TLS keys must have corresponding length according to
-the following table:
+Depending on the value of `ssl.cipher_suites` that you select to use, the TLS
+keys must have corresponding length according to the following table:
 
 [[comparable-key-strength]]
 .Comparable key strengths

x-pack/docs/en/security/securing-communications/enabling-cipher-suites.asciidoc

@@ -17,9 +17,8 @@ encryption with key lengths greater than 128 bits, such as 256-bit AES encryptio
 
 After installation, all cipher suites in the JCE are available for use but requires
 configuration in order to use them. To enable the use of stronger cipher suites
-with {es} {security-features}, configure the `cipher_suites` parameter. See the
-{ref}/security-settings.html#ssl-tls-settings[Configuration Parameters for TLS/SSL]
-section of this document for specific parameter information.
+with {es} {security-features}, configure the
+<<ssl-tls-settings,`cipher_suites` parameter>>.
 
 NOTE: The _JCE Unlimited Strength Jurisdiction Policy Files_ must be installed
       on all nodes in the cluster to establish an improved level of encryption

x-pack/docs/en/security/securing-communications/tls-transport.asciidoc

@@ -24,8 +24,7 @@ xpack.security.transport.ssl.truststore.path: elastic-certificates.p12 <3>
 -----------------------------------------------------------
 <1> If you used the `--dns` or `--ip` options with the `elasticsearch-certutil cert` command
 and you want to enable strict hostname checking, set the verification mode to
-`full`.
-See <<ssl-tls-settings, `xpack.security.transport.ssl.verification_mode`>> for a description of these values.
+`full`. For a description of these values, see <<transport-tls-ssl-settings>>.
 
 <2> If you created a separate certificate for each node, then you might need to
 customize this path on each node. If the filename matches the node name, you can
@@ -53,8 +52,7 @@ xpack.security.transport.ssl.certificate_authorities: [ "/home/es/config/ca.crt"
 --------------------------------------------------
 <1> If you used the `--dns` or `--ip` options with the `elasticsearch-certutil cert` command
 and you want to enable strict hostname checking, set the verification mode to
-`full`.
-See <<ssl-tls-settings, `xpack.security.transport.ssl.verification_mode`>> for a description of these values.
+`full`. For a description of these values, see <<transport-tls-ssl-settings>>.
 <2> The full path to the node key file. This must be a location within the
     {es} configuration directory.
 <3> The full path to the node certificate. This must be a location within the