IBM Support

SSLHandshakeException when trying to establish SSL connection with the SMTP server

Troubleshooting


Problem

The application is unable to establish secure communications with the SMTP server after enabling STARTTLS in the mail configuration in IBM Jazz Team Server (JTS). The error in jts.log indicates it cannot convert socket to TLS.

Symptom

Unable to connect to SMTP server through SSL. The following error can be seen in jts.log:
Could not convert socket to TLS; nested exception is: javax.net.ssl.SSLHandshakeException: Remote host closed connection during handshake

Cause

SSLHandshakeException - The SMTP server and the mail connection do not share a common SSL protocol.

Environment

All Environments

Diagnosing The Problem

  1. Configure JTS to connect to SMTP server through SSL by setting STARTTLS to true on the mail configuration page
    https://www.ibm.com/support/knowledgecenter/en/SSYMRC_7.0.2/com.ibm.jazz.repository.web.admin.doc/topics/tconfigemail.html
  2. Send a test email and see if the email is delivered successfully
  3. If it fails to send the test email, review jts.log for an error similar to the one below:
    Could not convert socket to TLS; nested exception is: javax.net.ssl.SSLHandshakeException: Remote host closed connection during handshake
  4. If there is a handshake or SSL protocol error, find out which protocol is being used by the SMTP server (eg. TLSv1.0, TLSv1.1, or TLSv1.2)
NOTE:
If you see an intermittent handshake issue, it is likely that the SMTP server cluster is being migrated to use a new protocol and not all servers are under the new protocol yet. To ensure a consistent test result, obtain the server's URL for the server with the new protocol. Then, test using the host URL instead of the proxy/load balancer URL used by the SMTP cluster.

Resolving The Problem

If TLSv1.2 is the protocol used by the SMTP server, it is required that you upgrade to one of the following releases or iFix versions:
  • 6.0.5 iFix021
  • 6.0.6 iFix020
  • 6.0.6.1 iFix014
  • 7.0.0 iFix007
  • 7.0.1 iFix005
  • 7.0.2 and future iFixes/releases
The mail libraries shipped with the above versions support TLSv1.2.
The following JVM option is also required to enable TLSv1.2 for secure connection with the mail server:
            mail.smtp.ssl.protocols=TLSv1.2
For example, in Liberty profile, add the following to the server.startup.bat/sh script. Then restart the server.
Linux:
JAVA_OPTS="$JAVA_OPTS -Dmail.smtp.ssl.protocols=TLSv1.2"
Windows:
set JAVA_OPTS=%JAVA_OPTS% -Dmail.smtp.ssl.protocols=TLSv1.2

Document Location

Worldwide

[{"Line of Business":{"code":"LOB59","label":"Sustainability Software"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSPRJQ","label":"IBM Engineering Lifecycle Management Base"},"ARM Category":[{"code":"a8m0z000000CbRUAA0","label":"Jazz Team Server->Administration->SMTP\/Email Configuration"}],"ARM Case Number":"TS005084096","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Version(s)"}]

Product Synonym

JTS; ELM;

Document Information

Modified date:
22 March 2021

UID

ibm16429079

Page Feedback