Updates to Hostname Verification [24.0.0.9, PH58796]

[adriankalafut]

Feature epic details

• For the title of this issue, type: Documentation, Development epic name
• Link to development epic:
• Target GA release:

Operating systems

Does the documentation apply to all operating systems?

• Yes
• No; specify operating systems: ______

Summary

Provide a concise summary of your feature. What is the update, why does it matter, and to whom? What do 80% of target users need to know to be most easily productive using your runtime update?

Configuration

List any new or changed properties, parameters, elements, attributes, etc. Include default values and configuration examples where relevant:

Updates to existing topics

To update existing topics, specify a link to the topics that are affected. Include a copy of the current text and the exact text to which it will change. For example: Change ABC to XYZ

Create a new topic

To create a topic, specify a first draft of the topic that you want added and the section in the navigation where the topic should go.

[dmuelle]

from @Zech-Hein

FYI - There is an open liberty doc page for trouble shooting security-SSL we could add info to
https://openliberty.io/docs/latest/troubleshooting.html#Troubleshooting_SSL

[adriankalafut]

We can add a Hostname verification subsection to the Transport Security
1.0 and mention:
WebSphere Liberty performs hostname verification on SSL certificates. If users want to disable hostname verification functionality, the verifyHostname attribute within the ssl tag must be initialized to false.

e.g. <ssl id="defaultSSLConfig"   keyStoreRef="defaultKeyStore"   trustStoreRef="defaultTrustStore"  verifyHostname=“true”/>

[ramkumar-k-9286]

Hi Adrian @adriankalafut

The suggested changes have been made to the Transport security page.

Draft Link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/transportSecurity-1.0.html

Please review the same.
Also, Please let me know if we need to make additional changes for this issue.

Regards,
Ramkumar.

CC @dmuelle

[Zech-Hein]

@ramkumar-k-9286 The quotes are a different symbol that will cause problems if customers try to copy/paste. can you update them?
you can see the difference below

trustStoreRef="defaultTrustStore"  verifyHostname=“true”

they should match what is used for trustStoreRef

[ramkumar-k-9286]

Hi Zech @Zech-Hein

The suggested correction is done.

Draft Link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/transportSecurity-1.0.html

Please review the same.
Also, Please let me know if we need to make additional changes for this issue.

Regards,
Ramkumar.

CC @dmuelle

[Zech-Hein]

@ramkumar-k-9286 That looks good.

One other update we would like to include in that same section is the following below...

to be:
Hostname verification
Hostname and IP address verification are enabled by default. The verification is enforced for target servers in all SSL connections using Open Liberty socket factories. However, you can specify a list of hostnames, IP addresses, or both to skip for verification.

Hostname verification can be disabled by setting the verifyHostname attribute within the ssl tag to false.
When Hostname verification is enabled, verification can be skipped/disabled for hostnames specified in the skipHostnameVerificationForHosts attribute within the ssl tag.

<ssl id="defaultSSLConfig" keyStoreRef="defaultKeyStore" trustStoreRef="defaultTrustStore" verifyHostname="true" skipHostnameVerificationForHosts="myHost.com" />

Hostname verification is also configurable for only HTTP connections by using the httpHostNameVerification attribute within the sslDefault tag. If httpHostNameVerification is set to true, and verifyHostname is set to false, hostname verification will still be enforced on HTTP connections, but not other connections.

[ramkumar-k-9286]

Hi Zech @Zech-Hein

The suggested changes have been made to the document.

Draft Link: https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/transportSecurity-1.0.html

Please review the same.
Also, Please let me know if we need to make additional changes for this issue.

Regards,
Ramkumar.

CC @dmuelle

[utle]

We need to update this article how can handle virtual host with HNV enabled by default.
https://www.ibm.com/docs/en/was-liberty/nd?topic=liberty-using-virtual-hosts
https://www.openliberty.io/docs/latest/virtual-hosts.html

[utle]

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/transportSecurity-1.0.html#hostverify

Hostname verification
In this article, sub-section hostname verify:

Replace the sub-section to:

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.

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.

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.

See host name verification troubleshoot for this issue - link to
https://openliberty.io/docs/latest/troubleshooting.html#Troubleshooting_SSL
Troubleshooting SSL and TLS

[utle]

https://www.openliberty.io/docs/latest/virtual-hosts.html
In this article we need to have a link to the sub-section Hostname and IP address verification

[utle]

https://openliberty.io/docs/latest/troubleshooting.html#Troubleshooting_SSL
Troubleshooting SSL and TLS
Add the following:
You receive the CWPKI0824E: SSL HANDSHAKE FAILURE: message that the Host name verification error
If you try to access an 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 doesn’t 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.

Avoid trouble: Avoid disabling hostname verification for production environments, as it can compromise security.

[utle]

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/secure-communication-tls.html
After section TLS and SSL add the following
Note: host name verification is enabled by default see the link for hostname verification.
https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/transportSecurity-1.0.html#hostverify

Hostname verification

[ramkumar-k-9286]

Hi @utle

Draft links for updated documents:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/transportSecurity-1.0.html#hostverify

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/troubleshooting.html#Troubleshooting_SSL

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/secure-communication-tls.html

Please review the same.

Regards,
Ramkumar.

CC @dmuelle

[utle]

https://ibmdocs-test.dcs.ibm.com/docs/en/SSAW57_liberty_test?topic=keys-generating-collective-controller-ssl
https://ibmdocs-test.dcs.ibm.com/docs/en/SSAW57_liberty_test?topic=keys-generating-collective-member-ssl

Related information link does not work for these two article.

The link does not work

[ramkumar-k-9286]

Hi David @dmuelle

Draft links for updated documents:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/transportSecurity-1.0.html#hostverify

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/troubleshooting.html#Troubleshooting_SSL

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/secure-communication-tls.html

Please review the same.

Regards,
Ramkumar.