News
Abstract
Beginning with PH58796, WebSphere Liberty performs hostname verification on SSL certificates.
Content
Fix
When an interim fix or fix pack (24.0.0.9) containing PH58796 is applied, the Liberty runtime automatically performs additional verification of certificates. This means that when Liberty is acting as a client connecting to an outbound server, 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 PH58796 affect all outbound connections. This means that any outbound connection could potentially fail after PH58796 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 outbound calls from a Liberty instance to a middleware server such a Database, or outbound calls from a web application running on a Liberty server to any other host.
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 verifyHostname to false, or by setting 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/Updated Properties
A new collection of properties can be used to configure or disable the hostname verification behavior. These properties can be configured for each ssl configuration in the server.xml for a Liberty server, or the client.xml for a Liberty client. Whenever possible, IBM strongly recommends applying the resolution step described above instead of disabling the hostname verification behavior.
For example, here is how the verifyHostname property can be set to false for the defaultSSLConfig:
<ssl id="defaultSSLConfig" verifyHostname="false" />| Property Name | Values (defaults in bold) | Description |
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. Liberty ensures that for any connection established through the Liberty-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 as an <ssl> configuration attribute. If the property is defined on the <ssl> element with id="defaultSSLConfig", it will be applied globally. Consult the documentation for information on SSL defaults in Liberty. |
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 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 as an <ssl> configuration attribute. If the property is defined on the <ssl> element with id="defaultSSLConfig", it will be applied globally. Consult the documentation for information on SSL defaults in Liberty. Avoid trouble: The property does not work for the following items:
Example values:
|
Notes on related properties:
- The -Dcom.sun.jndi.ldap.object.disableEndpointIdentification property (set in jvm.options), 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
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.
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.
Collectives
The following documentation only applies to the collectiveController-1.0 and collectiveMember-1.0 features. To determine if a feature is enabled for IBM WebSphere Application Server Liberty, refer to How to determine if Liberty is using a specific feature.
Skip this section if you are not using the collectiveControler-1.0 and collectiveMember-1.0 features.
Skip this section if you are not using the collectiveControler-1.0 and collectiveMember-1.0 features.
Expand
For Collective operations, hostname verification is enabled by default when the target server presents a certificate with a SAN field. Hostname verification failures in the context of a Collective could cause issues with adminCenter views, adminCenter commands, and replica coordination.
For Collectives which were created prior to the fix being installed, the default generated certificates in the serverIdentity.p12 and key.p12 keystores do not have SAN information.
After applying the fix to these environments, the following warning message is expected during startup when using the default generated certificates:
CWPKI0050W: The certificate with the serveridentity alias from the serverIdentity keyStore has no subject alternative name. HostName verification is not enforced for serverIdentity collective controller, replica and member SSL communication.
The Collective certificates in the serverIdentity.p12 and key.p12 keystores need to be regenerated using the recommended steps below.
Recommended Steps
For Collectives using the default certificates, it is recommended to apply the fix and post-fix steps in the following order. These steps do not apply to Collectives using CA certificates, which already have SAN information.
- Install the fix to the Controller(s) in the environment.
- Using the keytool command line tool, find the Owner string of each Controller’s leaf certificate in serverIdentity.p12 and key.p12 that will be used for the genKeyController command.
- Example Input:
keytool -list -v -keystore serverIdentity.p12 -storepass myPassword
Example Output:Certificate[1]:Owner: CN=controller1, L=%2Fopt%2Fibm%2Fwlp%2Fusr, L=example.mycompany.com, OU=controller, O=e2844f25-ef3d-4164-bfb7-a0824fa10a23, DC=com.ibm.ws.collective
- Example Input:
keytool -list -v -keystore key.p12 -storepass myPassword
Example Output:Certificate[1]:Owner: CN=example.mycompany.com, OU=controller1, O=ibm, C=us
- Keep these values handy as they will be used as inputs to the genKeyController command.
- Ensure all Controllers are running. If a Replica Set is in use, ensure that all of the Controllers in the Replica Set are running.
- Run the genKeyController command for each Controller to generate new certificates with a SAN field for each Controller's serverIdentity.p12 and key.p12 keystores, using the Owner fields obtained in step (1).
- Example Input for Controller serverIdentity.p12:
/opt/ibm/wlp/bin/collective genKeyController --controller=admin:admin@example.mycompany.com:9443 --keystorepassword=myPassword --keystorefile=/opt/ibm/wlp/usr/servers/controller1/resources/collective/serverIdentity.p12 --certificateSubject="CN=controller1, L=%2Fopt%2Fibm%2Fwlp%2Fusr, L=example.mycompany.com, OU=controller, O=e2844f25-ef3d-4164-bfb7-a0824fa10a23, DC=com.ibm.ws.collective"
Example Input for Controller key.p12:
/opt/ibm/wlp/bin/collective genKeyController --controller=admin:admin@example.mycompany.com:9443 --keystorepassword=myPassword --keystorefile=/opt/ibm/wlp/usr/servers/controller1/resources/security/key.p12 --certificatesubject="CN=example.mycompany.com, OU=controller1, O=ibm, C=us"
- Example Input for Controller serverIdentity.p12:
- Restart all of the Controllers
- Install the fix to the Member(s) in the environment
- Using the keytool command line tool, find the Owner string of each Member’s leaf certificate in serverIdentity.p12 and key.p12 that will be used for the genKey command.
- Example Input:
keytool -list -v -keystore serverIdentity.p12 -storepass myPassword
Example Output:Certificate[1]:Owner: CN=member1, L=%2Fopt%2Fibm%2Fwlp%2Fusr, L=c4713v1.fyre.ibm.com, OU=member, O=13875bda-c3f9-4986-9a10-36674701aba3, DC=com.ibm.ws.collective
- Example Input:
keytool -list -v -keystore key.p12 -storepass myPassword
Example Output:Certificate[1]:Owner: CN=example.mycompany.com, OU=member1, O=ibm, C=us
- Keep these values handy as they will be used as inputs to the genKey command.
- Run the genKey command for each Member to generate new certificates with a SAN field for each Member's serverIdentity.p12 and key.p12 keystores, using the Owner fields obtained in step (7).
- Example Input for Member serverIdentity.p12:
bin/collective genKey --controller=adminUser:pwd@example.mycompany.com:9443 --keystorePassword=myPassword --certificateSubject="CN=member1, L=%2Fopt%2Fibm%2Fwlp%2Fusr, L=example.mycompany.com, OU=member, O=13875bda-c3f9-4986-9a10-36674701aba3, DC=com.ibm.ws.collective" --keystoreFile=/opt/IBM/wlp/usr/servers/member1/resources/collective/serverIdentity.p12 --autoAcceptCertificates
- Example Input for Member key.p12:
bin/collective genKey --controller=adminUser:pwd@example.mycompany.com:9443 --keystorePassword=myPassword --certificateSubject="CN=example.mycompany.com, OU=member1, O=ibm, C=us" --keystoreFile=/opt/ibm/wlp/usr/servers/member1/resources/security/key.p12 --autoAcceptCertificates
- Example Input for Member serverIdentity.p12:
- Restart all of the Members
Configure Hostname Verification in a Collective
Refer to the table in the beginning of this document for more details about the properties that can be used to disable hostname verification on each Member and Controller. If you choose to disable hostname verification, note that it must be done in each of the controllerConnectionConfig and memberConnectionConfig ssl configurations on each of the Controllers and Members. These configurations are used internally for communication between the controller(s) and member(s).
For example, to disable hostname verification for an existing Collective environment, ensure that the controllerConnectionConfig and memberConnectionConfig ssl configurations in each Controller's server.xml have verifyHostname="false". These ssl configurations may not be explicitly defined in the server.xml - if they are not, then define them as given here:
Controller's server.xml
<ssl id="controllerConnectionConfig"
keyStoreRef="serverIdentity"
trustStoreRef="collectiveTrust"
verifyHostname="false" />
<ssl id="memberConnectionConfig"
keyStoreRef="serverIdentity"
trustStoreRef="collectiveTrust"
verifyHostname="false" />The controllerConnectionConfig ssl configuration in each Member's server.xml must also be set with verifyHostname="false":
Member's server.xml
<ssl id="controllerConnectionConfig"
keyStoreRef="serverIdentity"
trustStoreRef="collectiveTrust"
verifyHostname="false" />Additionally, the --disableHostnameVerification flag can be used to disable hostname verification when running client commands such as getMaintenanceMode, or when joining new members or controllers.
Example:
wlp/bin/collective getMaintenanceMode --controller=adminUser:adminPassword@controllerHostName:controllerHttpsPortNumber --hostName=serverHostName --disableHostnameVerificationCopied!
Related Information
[{"Type":"MASTER","Line of Business":{"code":"LOB77","label":"Automation Platform"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSD28V","label":"WebSphere Application Server Liberty Core"},"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
ibm17163230