IBM Support

Hostname verification for WebSphere Application Server traditional

News


Abstract

Beginning with PH58798, WebSphere traditional performs hostname verification on SSL certificates.

Content

Fix
When an interim fix or fix pack (8.5.5.27, 9.0.5.21) containing PH58798 is applied, the WebSphere runtimes automatically perform additional verification of certificates.  This means that when WebSphere is acting as a client, the runtime now checks to make sure that the hostname value from the server certificate's Subject Alternative Name (SAN) matches the hostname value used when establishing the connection. New configuration properties are available to accommodate certificates that do not pass this verification step.
Possible Side Effects
The changes introduced by PH58798 affect all outbound connections. This means that any outbound connection could potentially fail after PH58798 is applied if the host targeted by the outbound connection does not present a certificate with a SAN value that matches its hostname. Potential areas of impact include intra-cell communication, outbound calls from a WebSphere server to another middleware server such as a Database, or outbound calls from a web application running on a WebSphere server to any other host.

Here is an example of the type of error printed to the logs when a hostname verification failure occurs:
CWPKI0062E: SSL HANDSHAKE FAILURE: Host name verification error while connecting to host [example.ibm.com]. The host name used to access the server does not match the server certificate's [Subject Alternative Name [dnsName:notexample.ibm.com,dnsName:otherserver.ibm.com]]. The extended error message from the SSL handshake exception is: [No subject alternative names matching example.ibm.com found].
Resolution

To resolve a hostname verification failure, update the target host's certificates with ones that contain a SAN value matching the hostname used to connect to the server. This is the recommended approach to ensure that the environment maintains the highest possible level of security.
As a temporary workaround, another option is to disable hostname verification by setting com.ibm.ssl.verifyHostname to false, or by setting com.ibm.ssl.skipHostnameVerificationForHosts to the list of hosts for which hostname verification should be disabled. Refer to the next section for more details on how to configure these properties.

New Properties
A new collection of properties can be used to configure or disable the hostname verification behavior. Whenever possible, IBM strongly recommends applying the resolution step described above instead of disabling the hostname verification behavior.

These properties can be configured as Global Security Custom Properties, which apply to the entire cell. The properties can be configured for clients (for example wsadmin and other scripting tools) in the ssl.client.props file. Note that for Network Deployment environments, the syncNode script must be used to synchronize each node after the property is applied to the Deployment Manager.
Property Name Values (defaults in bold) Description
com.ibm.ssl.verifyHostname
true
false
 When this property is set to true, it enforces hostname and IP address verification for target servers in all SSL connections that the client initiates. WebSphere ensures that for any connection established through the WebSphere-provided SSLSocketFactory, which is the default SSLSocketFactory on the JVM, the hostname or IP address that is specified in the client's URL matches the Subject Alternative Name (SAN) in the SSL certificate that the server presents. If the SAN does not contain the relevant hostname, the verification matches the hostname against the common name (CN) in the certificate. If a mismatch is detected, the SSL connection is rejected.

This property can be configured at a global level and an SSL Configuration level.
com.ibm.ssl.skipHostnameVerificationForHosts Comma-separated list of hosts
You can specify a comma-separated list of hostnames, IP addresses, or both for this property. When you do, the client skips hostname and IP address verification for the specified items during SSL connections even if the com.ibm.ssl.verifyHostname property is set to true. By default, this property is set to an empty string, which means that the client verifies all hostnames and IP addresses in the SSL connections.

This property can be configured at a global level and an SSL Configuration level.

Avoid trouble: The property does not work for the following items:
    SSLSocketFactories other than the one provided by WebSphere (e.g. the default JDK SSLSocketFactory, Apache HTTPClient SSLSocketFactory)
    Sockets that are initially created without hostname or IP address information
Notes on related properties:
  • The com.sun.jndi.ldap.object.disableEndpointIdentification property, which was made available prior to the new properties listed here, enforces hostname verification for outbound calls from the JNDI APIs. Most notably, this property will affect whether hostname verification is used for LDAP connections. More info here: https://www.ibm.com/support/pages/node/1098783
  • The com.ibm.ssl.performURLHostNameVerification property, which was made available prior to the new properties listed here, enforces hostname verification only when the javax.net.ssl.HttpsURLConnection object is used whereas com.ibm.ssl.verifyHostname applies to all connections that use WebSphere socket factories.

[{"Type":"MASTER","Line of Business":{"code":"LOB67","label":"IT Automation \u0026 App Modernization"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSAW57","label":"WebSphere Application Server Network Deployment"},"ARM Category":[{"code":"a8m50000000Cd8DAAS","label":"WebSphere Application Server traditional-All Platforms-\u003ESecurity-\u003ESSL-\u003ESSL - General"}],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]

Document Information

Modified date:
19 September 2024

UID

ibm17163109

Page Feedback