Improved HttpClient TLS documentation about server host name verifica…

…tion. (#9494)

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-configuration.adoc

@@ -30,37 +30,42 @@ The most common parameters are:
 
 `HttpClient` supports HTTPS requests out-of-the-box like a browser does.
 
-The support for HTTPS request is provided by a `SslContextFactory.Client`, typically configured in the `ClientConnector`.
+The support for HTTPS request is provided by a `SslContextFactory.Client` instance, typically configured in the `ClientConnector`.
 If not explicitly configured, the `ClientConnector` will allocate a default one when started.
 
 [source,java,indent=0]
 ----
 include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java[tags=tlsExplicit]
 ----
 
-The default `SslContextFactory.Client` verifies the certificate sent by the server by verifying the certificate chain.
-This means that requests to public websites that have a valid certificate (such as ``https://google.com``) will work out-of-the-box.
+The default `SslContextFactory.Client` verifies the certificate sent by the server by verifying the validity of the certificate with respect to the certificate chain, the expiration date, the server host name, etc.
+This means that requests to public websites that have a valid certificate (such as `+https://google.com+`) will work out-of-the-box, without the need to specify a KeyStore or a TrustStore.
 
-However, requests made to sites (typically ``localhost``) that have an invalid (for example, expired or with a wrong host) or self-signed certificate will fail (like they will in a browser).
+However, requests made to sites that return an invalid or a self-signed certificate will fail (like they will in a browser).
+An invalid certificate may be expired or have the wrong server host name; a self-signed certificate has a certificate chain that cannot be verified.
 
-Certificate validation is performed at two levels: at the TLS implementation level (in the JDK) and, optionally, at the application level.
+The validation of the server host name present in the certificate is important, to guarantee that the client is connected indeed with the intended server.
 
-By default, certificate validation at the TLS level is enabled, while certificate validation at the application level is disabled.
+The validation of the server host name is performed at two levels: at the TLS level (in the JDK) and, optionally, at the application level.
 
-You can configure the `SslContextFactory.Client` to skip certificate validation at the TLS level:
+By default, the validation of the server host name at the TLS level is enabled, while it is disabled at the application level.
+
+You can configure the `SslContextFactory.Client` to skip the validation of the server host name at the TLS level:
 
 [source,java,indent=0]
 ----
 include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java[tags=tlsNoValidation]
 ----
 
-You can enable certificate validation at the application level:
+When you disable the validation of the server host name at the TLS level, you are strongly recommended to enable it at the application level, otherwise you may risk to connect to a server different from the one you intend to connect to:
 
 [source,java,indent=0]
 ----
 include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java[tags=tlsAppValidation]
 ----
 
+You may have the validation of the server host name enabled at both the TLS level and application level, typically when you want to further restrict the client to connect only to a smaller set of server hosts than those allowed in the certificate sent by the server.
+
 Please refer to the `SslContextFactory.Client` link:{javadoc-url}/org/eclipse/jetty/util/ssl/SslContextFactory.Client.html[javadocs] for the complete list of configurable parameters.
 
 [[pg-client-http-configuration-tls-truststore]]

documentation/jetty-documentation/src/main/java/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java

@@ -129,7 +129,7 @@ public void tlsNoValidation()
     {
         // tag::tlsNoValidation[]
         SslContextFactory.Client sslContextFactory = new SslContextFactory.Client();
-        // Disable certificate validation at the TLS level.
+        // Disable the validation of the server host name at the TLS level.
         sslContextFactory.setEndpointIdentificationAlgorithm(null);
         // end::tlsNoValidation[]
     }
@@ -138,7 +138,7 @@ public void tlsAppValidation()
     {
         // tag::tlsAppValidation[]
         SslContextFactory.Client sslContextFactory = new SslContextFactory.Client();
-        // Only allow subdomains of domain.com.
+        // Only allow to connect to subdomains of domain.com.
         sslContextFactory.setHostnameVerifier((hostName, session) -> hostName.endsWith(".domain.com"));
         // end::tlsAppValidation[]
     }