Merge pull request #7512 from OpenLiberty/7472-Updates-to-Hostname-Ve…

…rification

7472-Hostname verification-ut-cmts-1

modules/ROOT/pages/secure-communication-tls.adoc

@@ -52,6 +52,10 @@ Open Liberty does not check certificate revocations and instead relies on the un
 
 Before the wide adoption of the TLS protocol, SSL was the standard protocol to secure web communications. Over time, many security vulnerabilities were identified for SSL and it is no longer in widespread use. However, for historical reasons, the term SSL is often used to refer to encrypted network connections even when TLS is in use. In Open Liberty, the term SSL is still used in feature and configuration names, even though TLS is the underlying protocol. Effectively, SSL is now a synonym for TLS.
 
+NOTE: Hostname verification is enabled by default. 
+
+For more information on Hostname verification, see feature:transportSecurity[display=Transport Security].
+
 == See also
 
 https://tools.ietf.org/html/rfc8446[RFC 8446: The Transport Layer Security (TLS) Protocol]

modules/ROOT/pages/troubleshooting.adoc

@@ -273,6 +273,47 @@ Exception thrown while trying to read configuration and update ManagedServiceFac
 This error occurs when a keystore element exists in the configuration without an ID field.
 If you use a minimal TLS configuration, set the `ID` field to `defaultKeyStore`.
 
+=== You receive the CWPKI0824E message that SSL handshake failure due to hostname verification error
+
+If you try to access a URL, you might see the following message.
+
+----
+CWPKI0824E: SSL HANDSHAKE FAILURE:  Host name verification error while connecting to host [testServer.com].  The host name used to access the server does not match the server certificate's [Subject Alternative Name [dnsName:server1.com, ipAddress:11.22.33.444]].  The extended error message from the SSL handshake exception is: [No subject alternative names matching host name testServer.com].
+----
+
+Hostname and IP address verification is a critical security check that prevents man-in-the-middle attacks by making sure that the client connects to the correct server. However, hostname verification can fail during an SSL handshake.
+
+The following list provides common reasons that hostname verification fails.
+
+==== Mismatched hostnames
+
+The hostname that is specified in the client’s URL does not match the Common Name (CN) or Subject Alternative Name (SAN) in the server’s SSL certificate.
+
+==== Incorrect SSL configuration
+
+The SSL configuration on the server might be set up with a certificate that does not include the correct hostname.
+
+==== Configuration error in client
+
+The client might be configured with an incorrect URL or might be using a deprecated hostname.
+
+You can resolve the hostname verification failure by addressing the following areas.
+
+- Verify the hostname or IP address: Check that the hostname or IP address in the URL that you are using matches the SAN or CN in the server's SSL certificate. If the URL is incorrect, update it with the correct hostname.
+
+- Review your SSL configuration: Make sure that the server SSL certificate is configured correctly. The SSL certificate must contain the SAN or CN of the hostname that the client is connecting to.
+
+- If the security of your environment is not impacted, you can skip hostname verification for specific hostnames, IP addresses, or both. Set the `skipHostnameVerificationForHosts` attribute in the SSL config to the specific hostnames, IP addresses, or both that you want to skip verification for. Separate multiple entries with commas.
+
+- Disable hostname verification temporarily when this security check is not a concern, such as in nonproduction environments, by setting the SSL config element with the attribute `verifyHostname` to `false`.
+The following message is then displayed:
+
+----
+CWPKI0063W: Hostname verification is disabled for [mySSLConfig]. TLS/SSL connections do not check server identities to verify that the client is communicating with the correct server.
+----
+
+NOTE: Avoid disabling hostname verification for production environments as it can compromise security.
+
 [#Troubleshooting_TAI]
 == Troubleshooting Trust Association Interceptor
 

modules/reference/pages/feature/transportSecurity/examples.adoc

@@ -7,7 +7,7 @@
 - <<#configure-specific, Configure specific TLS protocols>>
 - <<#outbound, Configure outbound TLS>>
 - <<#certs, Provide certificates from an environment variable or a file>>
-- <<#hostverify, Hostname verification>>
+- <<#hostverify, Hostname and IP address verification>>
 
 [#config]
 === Configure transport layer security (TLS)
@@ -170,24 +170,13 @@ cert_defaultKeyStore="-----BEGIN CERTIFICATE-----
 ----
 
 [#hostverify]
-=== Hostname verification
+=== Hostname and IP address verification
 
-In Open Liberty, hostname and IP address verification are enabled by default. This verification is enforced for target servers in all SSL connections by using the Open Liberty socket factories. However, you can specify a list of hostnames, IP addresses, or both to skip verification.
+In Open Liberty, hostname and IP address verification are enabled by default. This verification is enforced for target servers in all SSL connections through Open Liberty socket factories. However, you can specify a list of hostnames, IP addresses, or both to skip verification.
 
-To disable hostname verification entirely, set the `verifyHostname` attribute within the `ssl` tag to `false`.
+The verification makes sure that the hostname or IP address in the URL matches the Subject Alternative Name (SAN) in the SSL certificate of the server. If the SAN is not found, the property makes sure that the hostname in the URL matches the Common Name (CN). If a mismatch exists, the SSL connection is rejected.
 
-[source,xml]
-----
-<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" verifyHostname="false"/>
-----
-
-When hostname verification is enabled (`verifyHostname="true"`), you can specify hostnames or IP addresses to be skipped for verification by using the `skipHostnameVerificationForHosts` attribute within the `ssl` tag.
-
-[source,xml]
-----
-<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" verifyHostname="true" skipHostnameVerificationForHosts="myHost.com"/>
-----
-
-Additionally, hostname verification for only HTTP connections can be controlled separately by using the `httpHostNameVerification` attribute within the `sslDefault` tag. If `httpHostNameVerification` attribute is set to `true` and `verifyHostname` attribute is set to `false`, hostname verification can still be enforced on HTTP connections, but not on other connections.
+Typically, during hostname verification, when the hostname is used in the request, it checks against the DNSName entry in the SAN. If the SAN does not contain a DNSName entry, hostname verification uses the certificate owner's common name (CN). When an IP address is used in the request, hostname verification relies on the IP address information in the SAN only.
 
+For more information, see xref:ROOT:pages/troubleshooting.adoc#Troubleshooting_SSL[Troubleshooting SSL and TLS]