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 or IP address from the server certificate's Subject Alternative Name (SAN) matches the hostname or IP address 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 or IP address. 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:
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].
⚠️ The CWPKI0062E error alone may not always indicate a hostname verification error. You need to check the extended error section of the output to confirm this wasn't thrown due to another exception.
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. An IP address can separately be added too if applicable. 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.
These properties can be configured as Global Security Custom Properties, which apply to the entire cell.
The properties may also be configured as a name/value pair for clients (for example wsadmin, syncNode, stopServer 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. Hostname inputs may be specified with a wildcard in the leftmost position of the hostname in accordance with RFC 1034. 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. Example values:
|
Notes on related properties:
- The
com.sun.jndi.ldap.object.disableEndpointIdentificationproperty, 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.performURLHostNameVerificationproperty, 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. - The
com.ibm.websphere.security.ior.hostNameproperty, which was also made available prior to the new properties, indicates if an IP address or a hostname will be used in the Interoperable Object Reference (IOR). This is a CORBA or RMI-IIOP related reference to help uniquely identify an object on the remote CORBA instance.- For more information see here: https://www.ibm.com/docs/en/was-nd/8.5.5?topic=realm-security-custom-properties#iorhostName
- If configuring on a WebSphere Client, this specific setting can go in the sas.client.props
- When an interim fix or fix pack (8.5.5.27, 9.0.5.21) containing PH58798 is applied, the default for this is property was changed to true.
When this custom property is set to true, a hostname will be used in the IOR, if you explicitly set this to false, it will use the IP address in the IOR. - However if you see a specific error about an invalid IPv6 address, you may need to set the setting to false to work around the issue.
java.net.UnknownHostException: [localhost:9810]: invalid IPv6 address literal
- For more information see here: https://www.ibm.com/docs/en/was-nd/8.5.5?topic=realm-security-custom-properties#iorhostName
Copied!
Hostname considerations:
In some cases the process of establishing a connection to a target host requires the target hostname to be resolved from its IP address. If the IP address resolved from the hostname is then resolved back to a different hostname, it may result in a hostname verification error. To avoid problems, consider either mapping the IP address to a single hostname, or listing all mapped hostnames as SANs in the server certificate.
This feature does not change how hostnames are resolved by the underlying Java runtime. For details on this, refer to the Java documentation and to the documentation or administrators of the operating system and network on which Java is running.
Related Information
[{"Type":"MASTER","Line of Business":{"code":"LOB77","label":"Automation Platform"},"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"}]
Was this topic helpful?
Document Information
Modified date:
29 October 2025
UID
ibm17163109