IBM Support

OpenSocial Component on Domino using TLS or SSL

Technote (troubleshooting)


Problem

Some OpenSocial gadgets, such as IBM Connections gadgets, need special setup for TLS or SSL for successful operation. Default configurations will experience failure at service startup. The Apache Shindig libraries by default expect to use TLSv1, while the Domino server by default supports SSLv3 and cannot perform the expected TLS handshake.

Symptom

OpenSocial Component functionality won't work for some gadgets. Logging (e.g. when "com.ibm.mm.proxy.level=FINEST" logging is enabled) will show a handshake failure, similar to:
javax.net.ssl.SSLHandshakeException: Server chose SSLv3, but that protocol version is not enabled or not supported by the client.

Administrators may also see "HTTP 502" SEVERE errors in the trace logs from the org.apache.shindig.gadgets.render.DefaultServiceFetcher class, similar to
"An HTTP 502 error occurred when fetching service methods from the https://<your server, unlocked domain, or locked domain>/fiesta/rpc endpoint"


Resolving the problem

Choose a remedy:

Option 1: Configure the Domino server to use the IBM HTTP Server (IHS), which provides TLSv1 support. This is the recommended remedy for Windows server platforms, and requires Domino version 9.x server on Windows. The Open Social components can continue to expect TLSv1.

- or -

Option 2: Configure the Open Social platform Java to use SSLv3. The Domino server should use its default SSL configuration, which is SSLv3.

2a: Create a file (for example,c:\IBM\Domino9\jvmOptions ) that contains the following:

-Dhttps.protocols=SSLv3,TLSv1

2b: Apply the setting in the Domino server's notes.ini.
JavaUserOptionsFile=c:\IBM\Domino9\jvmOptions

Option 3: (Available in release 9.01) In use cases where Option 2 is insufficient, an additional ini setting "OSGI_SSL_Protocol" can be configured for the SSL handshake protocol to be used for Open Social.

Currently OSGI_SSL_Protocol may be set to one of the following:
SSLv3 (to indicate SSL version 3),
SSL (to default to the highest supported version of SSL, although any supported version may be used),
TLSv1 (to indicate TLS version 1),
TLS (to default to the highest supported version of TLS, although any supported version may be used),
SSL_TLS (to indicate TLS if available, although any supported version of TLS or SSL may be used).

For example, to specify use of only SSL version 3, add this into the notes ini:
OSGI_SSL_Protocol=SSLv3

In release 9.01, the assumed default for OSGI_SSL_Protocol is SSL_TLS, which is equivalent to no value being specified.


Note that other solutions may also be feasible using a reverse proxy in front of the Domino server to handle TLSv1 requirements.

Document information

More support for: IBM Domino
OpenSocial

Software version: 9.0, 9.0.1

Operating system(s): AIX, IBM i, Linux, Solaris, Windows, z/OS

Reference #: 1640202

Modified date: 26 November 2014