IBM Support

Hostname verification for Liberty

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 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 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. 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. 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 at a global level and an <ssl> configuration level.
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. 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 Liberty (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
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.
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.
 
  1. Install the fix to the Controller(s) in the environment.
  2. 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.
  3. Ensure all Controllers are running. If a Replica Set is in use, ensure that all of the Controllers in the Replica Set are running.
  4. 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" 

  5. Restart all of the Controllers
  6. Install the fix to the Member(s) in the environment
  7. 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.
  8. 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
       
  9. 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 --disableHostnameVerification

[{"Type":"MASTER","Line of Business":{"code":"LOB67","label":"IT Automation \u0026 App Modernization"},"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"}]

Document Information

Modified date:
19 September 2024

UID

ibm17163230

Page Feedback