IBM Support

I'm using an Apache HttpClient to make an outbound call in my web application running on WebSphere Application Server Traditional, and I'm getting an SSL handshake error. How can I debug this?

Question & Answer


Question

I need to connect to an external service using TLSv1.2. I've changed my WebSphere SSL configurations to use the TLSv1.2 handshake protocol, but I can still see that the connection is going out using TLSv1.0.

I'm using an Apache HttpClient to make an outbound call in my web application running on WebSphere Application Server Traditional, and I'm getting an SSL handshake error. How can I debug this?

Answer

In WAS traditional, the SSL configurations that you define in the administrative console are applied at the runtime by a class called an SSLSocketFactory. WebSphere has its own custom SSLSocketFactory implementation (com.ibm.websphere.ssl.protocol.SSLSocketFactory) which it sets as the default for the IBM Java runtime that it sits on top of. When application code calls APIs that use this SSLSocketFactory for their connections, the WAS SSL settings are applied to the connection and any problems with the connection (for example protocol mismatches, cipher suite mismatches, or certificate trust issues) can be resolved by making changes to the SSL configurations in the WAS administrative console.

The Apache HttpClient, by default sets up a connection in such a way that it explicitly uses a custom Apache SSLSocketFactory implementation, rather than the default one set for the JVM (which in normal situations is the WAS implementation). Because of this, it will not be beholden to any WAS SSL configuration that is defined, including keyStores, trustStores, cipher suites, and handshake protocols. If you are using the Apache HttpClient in this way and are not able to change your usage pattern, then the properties of the SSL connection are entirely controlled at the application layer, and not by WAS.

If you are able to modify your application code, there are a number of available changes that can be implemented so that your code will use the WAS SSL settings and so that a WAS administrator, rather than an application developer, can make changes to affect the properties of the SSL connection. Here are some of the most common solutions:

1. Instantiate your Apache HttpClient by making a call to HttpClientBuilder.useSystemProperties().build(). The useSystemProperties() method tells the Apache runtime to use the default SSLSocketFactory on the JVM, which is the WAS SSLSocketFactory. There are other methods of creating an Apache HttpClient which will do this too, for example HttpClients.createDefault().
2. Use a standard Java API class such as an HttpsUrlConnection or an SSLSocket. All of the standard Java API classes use the defaults that are set for the JVM, so they will use the WAS settings. Note that if you use an API that operates at a lower level than the SSLSocketFactory, such as an SSLContext or an SSLEngine, your code will be prone to the same problems.

Note that starting in 8.5.5.9 and 8.0.0.12, a fix was added to WAS so that it no longer includes Apache HttpClient libraries in its default classloader. Prior to this fix, if your application code was picking up the libraries from the WAS runtime, it may have been working because those libraries were instrumented by IBM so that they always use the WAS SSLSocketFactory.

[{"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Component":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF033","label":"Windows"}],"Version":"All Versions","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
10 October 2019

UID

ibm11085505