[DOCS] Add ssl.verification_mode to secure settings (#93083)

Co-authored-by: Adam Locke <adam.locke@elastic.co>

docs/reference/settings/common-defs.asciidoc

@@ -149,20 +149,28 @@ Otherwise, it defaults to `jks`.
 end::ssl-truststore-type[]
 
 tag::ssl-verification-mode-values[]
-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; its use on
-production clusters is strongly discouraged.
+.Valid values
+[%collapsible%open]
+=====
+`full`::
+Validates that the provided certificate: has an issue date that's
+within the `not_before` and `not_after` dates; chains to a trusted Certificate
+Authority (CA); has a `hostname` or IP address that matches the names within
+the certificate.
+
+`certificate`::
+Validates the provided certificate and verifies that it's signed by a 
+trusted authority (CA), but doesn't check the certificate `hostname`.
+
+`none`::
+Performs no certificate validation.
 +
-The default value is `full`.
-end::ssl-verification-mode-values[]
+IMPORTANT: Setting certificate validation to `none` disables many security
+benefits of SSL/TLS, which is very dangerous. Only set this value if instructed
+by Elastic Support as a temporary diagnostic mechanism when attempting to
+resolve TLS errors.
+=====
++
+Defaults to `full`.
+end::ssl-verification-mode-values[]

docs/reference/settings/security-settings.asciidoc

@@ -1513,6 +1513,7 @@ This setting cannot be used with `ssl.truststore.password`.
 // tag::saml-ssl-verification-mode-tag[]
 `ssl.verification_mode` {ess-icon}::
 (<<static-cluster-setting,Static>>)
+Controls the verification of certificates.
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values]
 // end::saml-ssl-verification-mode-tag[]
 

docs/reference/settings/ssl-settings.asciidoc

@@ -26,12 +26,16 @@ Defaults to +{client-auth-default}+.
 endif::client-auth-default[]
 endif::server[]
 
-ifdef::verifies[]
 +{ssl-prefix}.ssl.verification_mode+::
 (<<static-cluster-setting,Static>>)
-Controls the verification of certificates.
-include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values]
+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>>)

docs/reference/setup/install/docker/docker-compose.yml

@@ -84,7 +84,6 @@ services:
       - xpack.security.http.ssl.key=certs/es01/es01.key
       - xpack.security.http.ssl.certificate=certs/es01/es01.crt
       - xpack.security.http.ssl.certificate_authorities=certs/ca/ca.crt
-      - xpack.security.http.ssl.verification_mode=certificate
       - xpack.security.transport.ssl.enabled=true
       - xpack.security.transport.ssl.key=certs/es01/es01.key
       - xpack.security.transport.ssl.certificate=certs/es01/es01.crt
@@ -124,7 +123,6 @@ services:
       - xpack.security.http.ssl.key=certs/es02/es02.key
       - xpack.security.http.ssl.certificate=certs/es02/es02.crt
       - xpack.security.http.ssl.certificate_authorities=certs/ca/ca.crt
-      - xpack.security.http.ssl.verification_mode=certificate
       - xpack.security.transport.ssl.enabled=true
       - xpack.security.transport.ssl.key=certs/es02/es02.key
       - xpack.security.transport.ssl.certificate=certs/es02/es02.crt
@@ -164,7 +162,6 @@ services:
       - xpack.security.http.ssl.key=certs/es03/es03.key
       - xpack.security.http.ssl.certificate=certs/es03/es03.crt
       - xpack.security.http.ssl.certificate_authorities=certs/ca/ca.crt
-      - xpack.security.http.ssl.verification_mode=certificate
       - xpack.security.transport.ssl.enabled=true
       - xpack.security.transport.ssl.key=certs/es03/es03.key
       - xpack.security.transport.ssl.certificate=certs/es03/es03.crt