Document ssl.verification_mode (elastic/x-pack-elasticsearch#4253)

It is common for users to wish to adjust the verification_mode in SSL
settings, usually with the intention of skipping hostname
verification. This has been supported for a long time, but the
relevant configuration setting was not clearly documented, which would
sometimes lead users to set `verification_mode` to `none`, and disable
more checks than they intended.

This commit adds clearer documentation regarding the options available
for `verification_mode` and actively discourages the use of `none`.

Original commit: elastic/x-pack-elasticsearch@2fdf53b42f

docs/en/security/authentication/active-directory-realm.asciidoc

@@ -329,7 +329,11 @@ operation are supported: failover and load balancing
                                           connection will not be allowed. Due to their potential security impact,
                                           `ssl` settings are not exposed via the
                                           {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
++
                                           Values are `none`, `certificate`, and `full`. Defaults to `full`.
++
+                                          See {ref}/security-settings.html#ssl-tls-settings[`xpack.ssl.verification_mode`]
+                                          for an explanation of these values.
 | `ssl.supported_protocols`  | no       | Specifies the supported protocols for TLS/SSL.
 | `ssl.cipher_suites`        | no       | Specifies the cipher suites that should be supported when communicating
                                           with the Active Directory server.
@@ -485,4 +489,4 @@ NOTE: By default, when you configure {security} to connect to Active Directory
       configuration do not match, {security} does not allow a connection to the
       Active Directory server. This is done to protect against man-in-the-middle
       attacks. If necessary, you can disable this behavior by setting the
-      {ref}/security-settings.html#ssl-tls-settings[`ssl.verification_mode`] property to `none`.
+      {ref}/security-settings.html#ssl-tls-settings[`ssl.verification_mode`] property to `certificate`.

docs/en/security/authentication/ldap-realm.asciidoc

@@ -264,6 +264,8 @@ failover and load balancing modes of operation.
                                               `ssl` settings are not exposed via the
                                               {ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API].
                                               Values are `none`, `certificate`, and `full`. Defaults to `full`.
+                                              See {ref}/security-settings.html#ssl-tls-settings[`xpack.ssl.verification_mode`]
+                                              for an explanation of these values.
 | `ssl.supported_protocols`      | no       | Specifies the supported protocols for SSL/TLS.
 | `ssl.cipher_suites`            | no       | Specifies the cipher suites that should be supported when communicating
                                               with the LDAP server.
@@ -492,4 +494,4 @@ NOTE: By default, when you configure {security} to connect to an LDAP server
       configuration do not match, {security} does not allow a connection to the
       LDAP server. This is done to protect against man-in-the-middle attacks. If
       necessary, you can disable this behavior by setting the
-      `ssl.verification_mode` property to `none`.
+      `ssl.verification_mode` property to `certificate`.

docs/en/security/authentication/pki-realm.asciidoc

@@ -90,6 +90,10 @@ In particular this means:
 * The interface must _trust_ the certificate that is presented by the client
   by configuring either the `truststore` or `certificate_authorities` paths,
   or by setting `verification_mode` to `none`.
++
+  See {ref}/security-settings.html#ssl-tls-settings[`xpack.ssl.verification_mode`]
+  for an explanation of this setting.
+
 * The _protocols_ supported by the interface must be compatible with those
   used by the client.
 

docs/en/security/authentication/saml-realm.asciidoc

@@ -250,6 +250,9 @@ These settings are not used for any purpose other than loading metadata over htt
 | `ssl.verification_mode`         | no       | One of `full` (verify the hostname and the certicate path),
                                                `certificate` (verify the certificate path, but not the hostname) 
                                                or `none` (perform no verification).  Defaults to `full`.
++
+                                               See {ref}/security-settings.html#ssl-tls-settings[`xpack.ssl.verification_mode`]
+                                               for a more detailed explanation of these values.
 | `ssl.supported_protocols`       | no       | Specifies the supported protocols for TLS/SSL.
 | `ssl.cipher_suites`             | no       | Specifies the cipher suites that should be supported.
 |=======================

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

@@ -25,6 +25,8 @@ xpack.security.transport.ssl.truststore.path: certs/elastic-certificates.p12 <3>
 <1> If you used the `--dns` or `--ip` options with the `certutil cert` command
 and you want to enable strict hostname checking, set the verification mode to
 `full`.
+See <<ssl-tls-settings, `xpack.ssl.verification_mode`>> for a description of these values.
+
 <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
 use the `certs/${node.name}.p12` format, for example.
@@ -48,6 +50,7 @@ xpack.security.transport.ssl.certificate_authorities: [ "/home/es/config/x-pack/
 <1> If you used the `--dns` or `--ip` options with the `certutil cert` command
 and you want to enable strict hostname checking, set the verification mode to
 `full`.
+See <<ssl-tls-settings, `xpack.ssl.verification_mode`>> for a description of these values.
 <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

docs/en/settings/security-settings.asciidoc

@@ -364,6 +364,9 @@ Keystore format, or `PKCS12` to use PKCS#12 files. The default is `jks`.
 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 the value of `xpack.ssl.verification_mode`.
++
+See <<ssl-tls-settings,`xpack.ssl.verification_mode`>> for an explanation of
+these values.
 
 `ssl.supported_protocols`::
 Supported protocols with versions. Defaults to the value of
@@ -573,6 +576,9 @@ Keystore format, or `PKCS12` to use PKCS#12 files. The default is `jks`.
 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 the value of `xpack.ssl.verification_mode`.
++
+See <<ssl-tls-settings,`xpack.ssl.verification_mode`>> for an explanation of
+these values.
 
 `ssl.supported_protocols`::
 Supported protocols with versions. Defaults to the value of
@@ -884,6 +890,9 @@ If retrieving IDP metadata via https (see `idp.metadata.path`), one of `full`
 (verify the hostname and the certicate path), `certificate` (verify the
 certificate path, but not the hostname) or `none` (perform no verification).
 Defaults to `full`.
++
+See <<ssl-tls-settings,`xpack.ssl.verification_mode`>> for a more detailed
+explanation of these values.
 
 `ssl.supported_protocols`::
 If retrieving IDP metadata via https (see `idp.metadata.path`), specifies the
@@ -916,8 +925,19 @@ Defaults to `required`. This global setting is not applicable for HTTP, see
  <<http-tls-ssl-settings>>.
 
 `xpack.ssl.verification_mode`::
-Controls the verification of certificates. Valid values are `none`,
-`certificate`, and `full`. Defaults to `full`.
+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`.
 
 `xpack.ssl.cipher_suites`::
 Supported cipher suites can be found in Oracle's http://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html[

docs/en/settings/ssl-settings.asciidoc

@@ -31,7 +31,9 @@ endif::server[]
 ifdef::verifies[]
 +{ssl-prefix}.ssl.verification_mode+::
 Controls the verification of certificates. Valid values are `none`,
-`certificate`, and `full`. Defaults to the value of `xpack.ssl.verification_mode`.
+`certificate`, and `full`.
+See <<ssl-tls-settings, `xpack.ssl.verification_mode`>> for a description of these values.
+Defaults to the value of `xpack.ssl.verification_mode`.
 endif::verifies[]
 
 +{ssl-prefix}.ssl.cipher_suites+::