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 validation 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 value from the server certificate's Subject Alternative Name (SAN) or Common Name (CN) matches the hostname value used when establishing the connection.
Possible Side Effects
The changes introduced by PH58796 affect all outbound calls from a Liberty server to another middleware server such as a Database, or outbound calls from a web application running on a Liberty server to any other host.
Hostname verification failures in the context of a Collective could cause issues with adminCenter views, adminCenter commands, and replica coordination.
Hostname verification failures in the context of a Collective could cause issues with adminCenter views, adminCenter commands, and replica coordination.
Standalone Liberty Server
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.
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.
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 |
Specifies whether host name verification for outbound connections using a specific SSL configuration is enabled. If set to true, then all outbound SSL connections that use the specified SSL configuration undergo verification of the target server host name against that server's certificate. The attribute is set to true by default. |
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.
For Collectives which were created prior to the fix being installed, keystores pointing to keyrings containing the system hostname as part of the Common Name (CN) in the certificate should not experience any issues for outbound SSL calls from the controller to member, or from the member to controller since these servers use the correct hostname when making outbound calls that match the controller/member certificate's hostname.
For reference:
See HOST.NAME in the sample RACF commands at:
Set up a Liberty collective on z/OS with SAF keyring
See controller.host.name and member.host.name at:
Configuring SAF certificates and keyrings for TLS on the z/OS operating system
If the certificate contains the wrong hostname, or the certificates are being used for multiple hosts, the sample RACF commands are provided to assist with regenerating the certificate containing a common name(CN) or subject alternative name (SAN) in which additional hostnames or IP address can be added to the certificate.
Generating the personal certificate with the hostname as the common name.
RACDCERT ID(CONTRLID) GENCERT SUBJECTSDN(CN('HOST.NAME') O('IBM') OU('Collective')) WITHLABEL('Controller') SIGNWITH(CERTAUTH LABEL('CONTROLLER ROOT')) SIZE(2048) NOTAFTER(DATE(2030/12/30))
Generating the personal certificate with an additional hostname NEW.HOST.NAME to the subject alternative name
RACDCERT ID(CONTRLID) GENCERT SUBJECTSDN(CN('HOST.NAME') O('IBM') OU('Collective')) WITHLABEL('Controller') ALTNAME(DOMAIN('NEW.HOST.NAME'))
SIGNWITH(CERTAUTH LABEL('CONTROLLER ROOT')) SIZE(2048) NOTAFTER(DATE(2030/12/30))
SIGNWITH(CERTAUTH LABEL('CONTROLLER ROOT')) SIZE(2048) NOTAFTER(DATE(2030/12/30))
Generating the personal certificate with an IP address 1.2.3.4 to the subject alternative name
RACDCERT ID(CONTRLID) GENCERT SUBJECTSDN(CN('HOST.NAME') O('IBM') OU('Collective')) WITHLABEL('Controller') ALTNAME(IP(1.2.3.4))
SIGNWITH(CERTAUTH LABEL('CONTROLLER ROOT')) SIZE(2048) NOTAFTER(DATE(2030/12/30))
SIGNWITH(CERTAUTH LABEL('CONTROLLER ROOT')) SIZE(2048) NOTAFTER(DATE(2030/12/30))
Generating the personal certificate with an subject alternative using an "*" for the subdomain.
RACDCERT ID(CONTRLID) GENCERT SUBJECTSDN(CN('HOST.NAME') O('IBM') OU('Collective')) WITHLABEL('Controller') ALTNAME(DOMAIN('*.HOST.NAME'))
SIGNWITH(CERTAUTH LABEL('CONTROLLER ROOT')) SIZE(2048) NOTAFTER(DATE(2030/12/30))
SIGNWITH(CERTAUTH LABEL('CONTROLLER ROOT')) SIZE(2048) NOTAFTER(DATE(2030/12/30))
Once the new certificate is created, the old certificate should be removed from the keyring, and the new one added to the keyring. These steps should be done for both the controller and member personal certificates.
If certificate updates are needed and the certificates were obtained from an external certificate authority, contact your certificate authority to request a new certificate with any updates or additions needed in the subject alternative name or common name.
If certificate updates are needed and the certificates were obtained from an external certificate authority, contact your certificate authority to request a new certificate with any updates or additions needed in the subject alternative name or common name.
New/Updated Properties
Refer to the Standalone Liberty Server section 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 SSL configuration including 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:
<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":
<ssl id="controllerConnectionConfig"
keyStoreRef="serverIdentity"
trustStoreRef="collectiveTrust"
verifyHostname="false" />
<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 --disableHostnameVerification
Additional Resources
Additional Resources
[{"Type":"MASTER","Line of Business":{"code":"LOB67","label":"IT Automation \u0026 App Modernization"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SS7K4U","label":"WebSphere Application Server for z\/OS"},"ARM Category":[{"code":"a8m0z0000001h7hAAA","label":"IBM WebSphere Liberty-All Platforms-\u003ELiberty z\/OS"}],"Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"All Versions"}]
Was this topic helpful?
Document Information
Modified date:
14 August 2024
UID
ibm17165287