Managing SSL/TLS protocol versions in TIBCO ActiveMatrix BusinessWorks™ 5

This article explains how to manage SSL/TLS protocol versions in TIBCO ActiveMatrix BusinessWorks™ 5 (BW).

TLS protocol versions enabled by default in BW environments

The TLS protocol versions enabled by default in a BW environment vary based on the JRE version.

Let’s take the case of BW 5.15.0, which uses Java 11. The property jdk.tls.disabledAlgorithms in the security properties file (TIBCO_HOME/tibcojre64/11/conf/security/java.security) shows which protocol versions are disabled. 

jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, RC4, DES, MD5withRSA, \
    DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, \
    include jdk.disabled.namedCurves

By default, SSLv3, TLS 1.0 and TLS 1.1 are disabled on JRE level and only TLS 1.2 and TLS 1.3 are enabled. So, by default, BW 5.15.0 can use TLS 1.2 or TLS 1.3.

TLS protocol version used in a TLS session

The TLS protocol version that is used in a TLS session depends on what protocol versions are supported by the two sides of the connection. Let’s say, BW (Send HTTP Request activity) is connecting to a web server over TLS in a BW 5.15 environment where TLS 1.2 and TLS 1.3 are enabled. If the web server supports TLS 1.3, it will be used for the connection. On the other hand, if TLS 1.2 is the highest version supported by the web server, TLS 1.2 will be used.

How to check the enabled TLS protocol versions and the version used in a TLS session

If BW is the client, to identify enabled TLS protocol versions, check TLS debug logs. The ClientHello handshake message shows the enabled TLS protocol versions. The sample log given below shows that TLS 1.3 and TLS 1.2 are enabled.

"ClientHello": {
.....
.....
    "supported_versions (43)": {
      "versions": [TLSv1.3, TLSv1.2]
    },
.....
.....
}

If BW is the server, the utility sslscan (https://github.com/rbsec/sslscan/releases) can be used to check the enabled TLS protocol versions. The sample output given below shows that TLS 1.2 and TLS 1.3 are enabled.

$sslscan localhost:9191
Version: 2.1.3 Windows 64-bit (Mingw)
OpenSSL 3.0.9 30 May 2023

Connected to ::1

Testing SSL server localhost on port 9191 using SNI name localhost

  SSL/TLS Protocols:
SSLv2     disabled
SSLv3     disabled
TLSv1.0   disabled
TLSv1.1   disabled
TLSv1.2   enabled
TLSv1.3   enabled

.....
.....

To identify the TLS protocol version that is used in a TLS session where BW is the client or server, check TLS debug logs. The ServerHello handshake message shows the selected TLS protocol version. The sample log given below shows that the selected version is TLS 1.3.

"ServerHello": {
.....
.....
    "supported_versions (43)": {
      "selected version": [TLSv1.3]
    },
.....
.....
}

Disabling a TLS protocol version that is enabled by default

A TLS protocol version may be disabled on JRE level or application level.

JRE level

To disable a specific TLS protocol, add it to the property jdk.tls.disabledAlgorithms in the security properties file. For example, to disable TLS 1.2, update the property as follows.

jdk.tls.disabledAlgorithms=SSLv3, TLSv1, TLSv1.1, TLSv1.2, RC4, DES, MD5withRSA, \
    DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, \
    include jdk.disabled.namedCurves

Application level

In cases where TLS is handled by BW, it is possible to disable TLS protocols separately on client side and server side using the following properties.

com.tibco.security.ssl.server.EnableTLSv1
com.tibco.security.ssl.server.EnableTLSv11
com.tibco.security.ssl.server.EnableTLSv12
com.tibco.security.ssl.server.EnableTLSv13
com.tibco.security.ssl.client.EnableTLSv1
com.tibco.security.ssl.client.EnableTLSv11
com.tibco.security.ssl.client.EnableTLSv12
com.tibco.security.ssl.client.EnableTLSv13

For example, the following property can be used to disable TLSv1.2 on client side in a BW version where TLSv1.2 is enabled by default.

java.property.com.tibco.security.ssl.client.EnableTLSv12=false

Sample log that shows the TLS protocol versions that are enabled by default in BW 5.15 environment.

"ClientHello": {
.....
.....
    "supported_versions (43)": {
      "versions": [TLSv1.3, TLSv1.2]
    },
.....
.....
}

Sample log with the property com.tibco.security.ssl.client.EnableTLSv12 set to false. Only TLSv1.3 is enabled.

"ClientHello": {
.....
.....
    "supported_versions (43)": {
      "versions": [TLSv1.3]
    },
.....
.....
}

In cases where TLS is handled by a third-party library, use the setting provided by the third-party library. For example, when using MySQL Connector/J JDBC driver version 8.x to connect to MySQL server over TLS, the TLS protocol versions TLS 1.2 and TLS 1.3 are enabled by default. The driver configuration property tlsVersions can be used to restrict TLS protocol versions. To disable TLS 1.2 and use only TLS 1.3, set the property to TLSv1.3 in the JDBC URL as shown below.

jdbc:mysql://host:port/database?sslMode=VERIFY_CA&tlsVersions=TLSv1.3

Enabling a TLS protocol version that is disabled by default

Sometimes, it may be necessary to enable a specific TLS protocol version that is disabled by default. To enable a specific TLS protocol, remove it from the property jdk.tls.disabledAlgorithms in the security properties file. For example, to enable TLS 1.1, update the property as follows.

jdk.tls.disabledAlgorithms=SSLv3, TLSv1, RC4, DES, MD5withRSA, \
    DH keySize < 1024, EC keySize < 224, 3DES_EDE_CBC, anon, NULL, \
    include jdk.disabled.namedCurves

Sample log with the property updated to enable TLSv1.1. TLS 1.3, TLS 1.2 and TLS 1.1 are enabled.

"ClientHello": {
.....
.....
    "supported_versions (43)": {
      "versions": [TLSv1.3, TLSv1.2, TLSv1.1]
    },
.....
.....
}

Note that any changes made to the default security properties file affect all the BW applications running under the TIBCO_HOME. If the requirement to enable a TLS protocol version is specific to an application, a better option would be to make a copy of the security properties file, make the change in the new file and configure the application to use the new file. More information on specifying an alternate security properties file can be found in the comments section of the security properties file.