IBM Support

SSL connection to XML Management Interface or WebGUI might fail

Downloadable files


Abstract

An SSL connection to the XML Management Interface or WebGUI of a WebSphere DataPower appliance will fail if the SSL client requires a trusted certificate chain and the root CA cert

Download Description

If you try to connect to the XML Management Interface (SOMA, AMP, WS-Management, and WSDM) with an SSL client that enforces a trusted certificate chain, the SSL connection will fail if the root CA (Certificate Authority) certificate is not trusted by the SSL client.

Here is an example of such a failure from a Java based SSL client:

Exception in thread "main" javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.g: PKIX path building failed: java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid CertPath.; internal cause is:
java.security.cert.CertPathValidatorException: The certificate issued by OU=Root CA, O="DataPower Technology, Inc.", C=US is not trusted; internal cause is: java.security.cert.CertPathValidatorException: Certificate chaining error 

The root CA certificate can become trusted by adding it to the trust store of the SSL client. The root CA certificate that you add to the trust store, depends on what SSL Proxy Profile is being used by the XML Management Interface.

  • It is a security best practice to not use the default SSL Proxy Profile for the Web Management Service (WebGUI) and XML Management Interface, because it involves a common RSA private key that is shipped on all DataPower appliances. For more information, see technote Access the WebGUI, and the browser presents a message concerning the IBM WebSphere DataPower certificate. If your appliance uses a custom SSL Proxy Profile for the XML Management Interface, you would add your root CA certificate.
  • If your appliance is using the default SSL Proxy Profile for the XML Management Interface, you would add the DataPower root CA certificate.
DataPower appliances started using a new Root CA certificate with the following appliances:
  • Firmware version 4.0.1 on Type 7199 appliances
  • Firmware version 4.0.2 on Type 7198 appliances

Starting with DataPower 5.0.0, the Type 9235 and Type 4195 appliances start using the new Root CA certificate that has always been used by the Type 7199 and Type 7198 appliances.

This means that customers with Type 9235 and Type 4195 appliances who have been using the old DataPower root CA certificate in their trust store will start having SSL connection failures when they upgrade to 5.0.0.

Customers with the following appliances should add the new DataPower Root CA certificate to their SSL client's trust store, if they are going to use the default SSL Proxy Profile for SOMA and AMP.
  • Type 7198 and Type 7199 appliances at any level of DataPower firmware.
  • Type 4195 and Type 9235 appliances at the 5.0.0 level of DataPower firmware.
    • In addition,Type 4195 and Type 9235 appliances also need the fix for APAR IC84993 so that all of the proper certificates for the default SSL Proxy Profile are used.

The new DataPower Root CA certificate can be obtained from the resource kit on Fix Central, as well as from the DataPower 5.0.0 resource CD that is shipped with new appliances. See the link at the end of this technote to download the 5.0.0 resource kit. Once you have the resource kit, you can extract the files. The new DataPower Root CA certificate is the /certificates/root-ca-cert.pem file. If you are using the DataPower 5.0.0 resource CD, the file can be found directly on the CD.

Type 9235 and Type 4195 appliance customers who want to continue to use SOMA and AMP with the default SSL Proxy Profile at levels prior to 5.0.0, should also continue to keep the old DataPower root CA certificate in their SSL client's trust store.

If you try to connect to the WebGUI when the root CA is not trusted by the web browser, the web browser will display a dialog asking you if you really want to continue the connection. If your appliance is using the default SSL Proxy Profile for the WebGUI, you may have to indicate to the browser that it is safe to continue the connection after you upgrade your Type 9235 or Type 4195 appliance to DataPower 5.0.0. This would be true even if you have told the browser in the past to trust the SSL connection to the appliance, because the default SSL Proxy Profile would be using the new DataPower Root CA certificate in DataPower 5.0.0.

Appliances that use the default SSL Proxy Profile for the WebGUI will also need the fix for APAR IC84993 so that all of the proper certificates for the default SSL Proxy Profile will be used in creating the SSL connection.

Download package



Document information

More support for: IBM DataPower Gateways

Software version: 5.0.0

Operating system(s): Firmware

Reference #: 4032998

Modified date: 05 July 2012


Translate this page: