IBM Support

PH48747: WebSphere web server plug-in changes to certificate hostname validation

News


Abstract

Beginning with PH48747, WebSphere Web Server plug-in performs hostname validation on SSL certificates

Content

Fix
When an interim fix or fix pack (8.5.5.24, 9.0.5.16) containing PH48747 is applied, the plug-in automatically performs additional validation  of the certificates provided by the application servers.  The plug-in compares values from the certificate (Common Name, SAN DNS names, SAN IP addresses) to values contained within the plugin-cfg.xml file.  New configuration properties are available to accommodate certificates that do not pass validation.
There are differences of operations and configuration based on whether Intelligent Management is enabled and how plugin-cfg.xml is generated.  What follows are links to various parts of this document.  As you look at the tables, pay attention to the "Applies to" column to understand its plug-in usage.

 
Possible side effects
  1. In environments with many servers in plugin-cfg.xml, webserver startup may be delayed. 
    HostVerificationStartupCheck=false defers the checking to runtime
  2. In environments with servers in plugin-cfg.xml that point to shutdown host operating systems, webserver startup may be delayed
    APAR PH55238 corrects the connection timeout handling for HostVerificationStartupCheck. 
  3. Special note about environments with liberty configuration with <tcpOptions waitToAccept="true"/>.
    waitToAccept was introduced in 2015, but has been considered detrimental after improvements made to the default Liberty behavior since 20.0.0.2.  The waitToAccept option should be removed from the configuration

    The fix for APAR PH55213 will make this aspect of HostVerificationStartupCheck more reliable with waitToAccept="true"  
New Properties
Property Name Values
(defaults in bold)		 Description  Applies to
SecureHostVerification true-markdown
true-nomarkdown
false		 Setting to false, along with setting HostVerificationStartupCheck to false, turns off all hostname validation introduced by this APAR.

If set to one of the true values and the validation fails, then the server markdown behavior is handled based on the setting (Intelligent Management handles markdown behavior outside this property's setting). 		 WebSphere, Intelligent Management, and Liberty
HostVerificationStartupCheck
true
false
 Controls whether the plug-in validates all defined transports within the XML at startup. See "Start Up Chart" for details on property settings and behavior. WebSphere, non-Intelligent Management Liberty
IMSecureConnectorVerification
fail
warn
off
 * SecureHostVerification must be set to a ‘true-?’ value. Controls whether the plug-in validates all Connectors within the Intelligent Management group.  As the plug-in loads, it creates a list of all Connectors from all Intelligent Management groups.  When a new https Connector connection is needed, the Plugin software performs the necessary certificate validation routines.  A validation failure with the property set to fail cancels the stream and post messages to the log.  When set to ‘warn’, only messages are posted to the log, but the stream is allowed to continue. Intelligent Management
IMSecureEndpointVerification fail 
warn
off		 * SecureHostVerification must be set to a ‘true-?’ value. Controls whether the plug-in validates the Endpoint hostname returned by the Connector.  When a new stream is needed, the plug-in performs the necessary certificate validation routines.  A validation failure with the property set to fail cancels the stream and post messages to the log.  When set to ‘warn’, only messages are posted to the log, but the stream is allowed to continue. Intelligent Management
GlobalHostAlias Comma-delimited list GlobalHostAlias is a comma-separated list (NO SPACES) of either hostnames or IP values that will be accepted if present in the servers certificate. WebSphere, Intelligent Management, and Liberty
HostnameAlias Single value HostnameAlias is a Transport property, which gives the user the ability to add an alternate hostname or IP that will be accepted if present in the the servers certificate. WebSphere
Where to set these Properties
Property Name Where to Set Applies to
HostVerificationStartupCheck Web servers > [webserver?] > plug-in properties > Custom properties WebSphere
SecureHostVerification Web servers > [webserver?] > plug-in properties > Custom properties WebSphere, Intelligent Management
IMSecureConnectorVerification Web servers > [webserver?] > plug-in properties > Custom properties Intelligent Management
IMSecureEndpointVerification Web servers > [webserver?] > plug-in properties > Custom properties  Intelligent Management
GlobalHostAlias Web servers > [webserver?] > plug-in properties > Custom properties WebSphere, Intelligent Management
HostNameAlias Application servers > server1 > Web container transport chains > WCInboundDefaultSecure > TCP inbound channel (TCP_4) > Custom Properties WebSphere
Liberty properties are set differently.  The properties are configured inside a server.xml, under the subelement <extraConfigProperties> of the <pluginConfiguration> tag.
Example: 
<pluginConfiguration httpEndpointRef="${usr.extension.dir}"
   webserverSecurePort="433" webserverName="webHTTPServ“   . . .   ESIEnable="false”>
   <extraConfigProperties
    GlobalHostAlias="www.this.com,www.that.com"  SecureHostVerification="true-nomarkdown“ IMSecureConnectorVerification="warn"
    IMSecureEndpointVerification="fail“ HostVerificationStartupCheck="false">
  </extraConfigProperties>
</pluginConfiguration>
Processing
General Validation (non-Intelligent Management)
New https connections attempt to validate the certificate's Common Name, SAN DNS names, and SAN IP addresses values against the plugin-cfg.xml content in this order.
  1.   Transport's HostnameAlias (set or derived)
  2.   GlobalHostAlias values
  3.   Transport's hostname (if different than HostnameAlias)
  4.   Remote Server address values (if possible)
Once there is a match, the plug-in ceases further validations.  Existing Streams that are being reused do not require an extra validation.
By default, validation takes place during startup for each https transport.  Depending on the plug-in version and the KillWebServerStartUpOnParseErr setting, the IBM HTTP Server might not start.  The following chart explains the expected behavior.
Start Up Chart (non-Intelligent Management)
Version KillWebServer-StartUpOnParseErr HostVerification-StartupCheck SecureHost-Verification Validation failures detected at Start Up
9.0.5 true (default value) true true-nomarkdown or true-markdown Web Server does NOT start.  Validation errors reported.
9.0.5 false true true-nomarkdown or true-markdown Web Server starts.  Validation errors reported.
9.0.5 false false true-nomarkdown or true-markdown Web Server starts.  No validation errors reported.
8.5.5 false (default value) true true-nomarkdown or true-markdown Web Server does NOT start.  Validation errors reported.
8.5.5 true true true-nomarkdown or true-markdown Web Server does NOT start.  Validation errors reported.
8.5.5 false false true-nomarkdown or true-markdown Web Server starts.  No validation errors reported.
General Validation (Intelligent Management Connectors)
The plug-in handles Intelligent Connectors differently than it does for standard WebSphere transport traffic.  The plug-in aggregates all Intelligent Management connectors during the XML load. Because Intelligent Management is outside the scope of general startup, there isn't an option to stop the web server from starting. When an https Connector is used, the plug-in validates the certificate's Common Name, SAN DNSNames, and SAN IP addresses values in this order.
  1. Connector list created at startup
  2. GlobalHostAlias values
  3. Server Address values (if possible)
General Validation (Intelligent Management Endpoints)
Endpoints are treated the same as a defined transport within the plugin-cfg.xml.  Endpoints don't have HostnameAlias values available.  In those cases, the plug-in assumes to use the hostname as the HostnameAlias value, which eliminates the need to validate the hostname again.  See "General Validation (non-Intelligent Management)" details.
Notes
  • iSeries Limitation - Unlike other OSes, the gskit package used by iSeries is unable to iterate over multiple SAN DNSNames or SAN IP addresses.  It is only able to get the first value in the list and pass it back to the plug-in for validation.  Currently, being addressed by APAR SE79603.  There isn't any ETA on its delivery.
  • Wildcards - Any "*" within the plugin-cfg.xml GlobalHostAlias or HostnameAlias fields are treated as a literal.  Only wildcards contained within one of the certificate fields are processed for potential pattern matches.
  • Remote ServerAddress Values – The plug-in attempts to gather additional information from the application server that can aid in passing the certificate values.  If Transport hostname is an IP and the HostnameAlias value was provided, then it might be able to find an extra hostname value to try use against the IP address value.
  • If the Transport hostname contains an IP address and there isn't anything defined for HostnameAlias, the plug-in uses the reverse DNS lookup value for a HostnameAlias.  
  • The extra certificate validation occurs for NEW https Streams.  If you require Intelligent Management Connectors to use https, then you must enable the WebSphere Global Security and regenerate the XML.
  • Intelligent Management Connectors and Endpoints are not validated during the process plug-in's start.  Therefore, there isn't any way to stop the web server from loading due to failures with Connectors or Endpoints.
FAQ's
•Why won’t my web server start, or Why does my web server take longer to start?
ØHostVerificationStartupCheck & KillWebServerStartUpOnParseErr are set to true and start-up validation errors were detected.  See “Start Up chart” for behaviors based on  settings and version.  Setting HostVerificationStartupCheck to false will eliminate the start-up checks, but those same issues will be detected and reported for each new https stream there after.
•Why do my customer’s requests fail?
ØSecureHostVerification is set to one of the ‘true-?’ values and the plug-in validation are failing the transport because it can’t find a match between the XML values and certificate values.  Either the certificate needs to be adjusted, add GlobalHostAlias values, add a HostnameAlias value for the Transport (if WebSphere traditional), or set SecureHostVerification to false.
ØIf Intelligent Management is enabled, then switching IMConnectorVerification or IMEndpointVerification to warn or off helps in this situation.  “Warn” still does the validation but does not stop the request.
•How do I keep validation on, but allow failing request to process?
ØWebSphere traditional doesn’t offer a warning option.  The SecureHostVerification acceptable values are true-markdown, true-nomarkdown, or a false option.  
ØIntelligent Management does offer a “warn” option that posts the error messages to the log but allows the connection to go through.  It is up to your Administrator to monitor the logs for validation failures.
•Will this impact performance on our servers?
ØIBM’s performance review didn’t see any impact from our testing.  Since we can’t mimic every customer’s environment, we can’t guarantee the same results for each customer.
•How do I add values to my XML to allow validation to pass?
ØProperties can be manually added to the XML or refer to the “Where to set these Properties” table for details on how each property is set.
•Is there a way to turn off all validation?
ØYes, setting SecureHostVerification and HostVerificationStartupCheck to false stops all validation for traditional WebSphere, Liberty, and Intelligent Management.
•I set my IMSecureConnectorVerification or IMSecureEndpointVerification properties to fail or warn, but I don’t see any validations.
ØThe SecureHostVerification property controls all hostname validations.  Setting to one of the true values turns it ON, and false turns it OFF. SecureHostVerification value has no impact on markdown behavior for processing with Intelligent Management.  Intelligent Management handles it on its own.
ØConnectors and Endpoints must be using https protocol.  For Connectors to use https, WebSphere Global Security must be turned on.  
ØEndpoints follow the same procedure as WebSphere Traditional transports.  If the incoming request is HTTPS, then Intelligent Management chooses to use an HTTPS Endpoint.
•Sometimes I have a failure while others don’t.  Why is that happening?
ØThere isn’t a simple answer.  The request could be going to a different node that isn’t using the same certificate as a passing node.  You need to review a Trace loglevel plug-in log.  Find the request that fails and decide whether the certificate needs to be adjusted or if an extra value is needed within the GlobalHostAlias property.
ØReview the plugin-cfg.xml file for asterisks within the GlobalHostAlias or HostnameAlias values.  Asterisks within ANY of Plugin-cfg.xml fields are seen as a literal.  The plug-in ignores the ‘Wildcard’ for pattern match.  Only wildcards within certificate values do the pattern matches to plugin-cfg.xml values.
•I merged 2 plugin-cfg.xml files, but the merged version isn’t showing all GlobalHostAlias values from all XMLs.
 ØThis is normal for the pluginCfgMerge tool.  The PluginCfgMerge tool always recognized the first XML in the list provided as being the baseline to pull all <Config and <Property tag values.  It is expected that these properties are not merged.  The correction is to consolidate all GlobalHostAlias values from the other XMLs to the first XML.  This list cannot contain any spaces and is comma-separated. 
Example:  Plugin-cfg1.xml has <Property Name="GlobalHostAlias" Value=“host1.com"/>
                  Plugin-cfg2.xml has <Property Name="GlobalHostAlias" Value=“host2.com"/>
                  Plugin-cfg-1.xml needs to have <Property Name="GlobalHostAlias" Value="host1.com,host2.com"/>
ØAre the 2 XMLs manually merged? Do you see the GlobalHostAlias within the <Config and also appear as a <Property?
If the tags appear in the <Config tag and a <Property tag, the plug-in binary uses the value in the Property tag.  Therefore, you need to add the values from the <Config version to the <Property version before the merge.

[{"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":"a8m50000000CdVLAA0","label":"WebSphere Application Server traditional-All Platforms-\u003ETransactions"}],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]

Document Information

Modified date:
06 June 2024

UID

ibm16982543

Page Feedback