IBM Support

How do I change the default SSL/TLS protocol my Java™ application will use?

Question & Answer


Question

How do I change the default SSL/TLS protocol my Java™ application uses?

Answer

TLSv1.3 & TLSv1.2 are the default TLS protocols in IBM JDK 8.0.  TLSV1.2 is the default TLS protocol in IBM JDK 7.1 and 7.0.  NOTE: The TLSv1.1 and TLSv1.0 protocols are disabled after installing the Java 8.0 SR6 FP30, 7.1 SR4 FP85, and 7.0 SR10 FP85 or newer service release fix pack level on the IBM i OS.  Detailed information IBM JDK security updates can be found here: https://www.ibm.com/support/pages/node/1117863.
There are two properties that a Java™ client application can use to specify the TLS version of the SSL/TLS handshake.

jdk.tls.client.protocols=TLSv1.2
&
https.protocols=TLSv1.2
The jdk.tls.server.protocols=TLSv1.2 property can be used to set the default TLS protocol for Java Server applications.

Specifying jdk.tls.client.protocols=TLSv1.2 changes the ClientHello to use TLSv1.2 (https included). The https.protocols is only valid if the Client Application us using HttpsURLConnection class or URL.openStream() operations.

The value "TLSv1.2" is case-sensitive. It is important the 'v' is lowercase.
Please refer to the URL, https://www.ibm.com/docs/en/sdk-java-technology/8?topic=provider-customization, for complete list of IBM JDK security customization properties.
Property Description
jdk.tls.client.protocols Controls the underlying platform TLS implementation.  Additional information is available in the JSSE Reference Guide.

Example: -Djdk.tls.client.protocols=TLSv1.2

Available in all Java™ 11 & 8 releases, or after Java™ 7 update 95 (January 2016) and Java™ 6 update 121 (July 2016).
https.protocols Controls the protocol version used by Java™ clients, which obtain https connections through use of the HttpsURLConnection class or URL.openStream() operations.

Example: -Dhttps.protocols=TLSv1.2


The properties can be included in the SystemDefault.properties for the user.dir (typically /home/userid/SystemDefault.properties) for the JVM, or globally with /QIBM/UserData/Java400/SystemDefault.properties. The properties must be entirely left-aligned in order to be implemented.

Example:

************Beginning of data**************
#AllowOptions
jdk.tls.client.protocols=TLSv1.2
https.protocols=TLSv1.2
************End of Data********************

If these properties are included in a generic JVM argument, they need to include the '-D'

Example:
java -Djdk.tls.client.protocols=TLSv1.2 ClassName
java -Dhttps.protocols=TLSv1.2 ClassName

To aid in determining what TLS version is being used in the handshake, the debug details can be found with the property:

-Djavax.net.debug=all

The ClientHello event shows which version is in use.

Here is an example:

java -Djdk.tls.client.protocols=TLSv1.2 -Djavax.net.debug=all HttpsClient https://www.google.com | grep "ClientHello"
IBMJSSE2 to send SCSV cipher suite on initial ClientHello
*** ClientHello, TLSv1.2
Here are a few additional options on how to specifically define your Java application to use the TLSv1.2 protocol:
Use SSLContext to set your TLS protocol version:
SSLContext of "TLSv1.2" protocol supports TLS 1.2. For example:
// Get SSLContext instance for "TLSv1.2".
SSLContext context = SSLContext.getInstance("TLSv1.2");
// Create SSLEngine object that enables TLS version 1.2.
SSLEngine sslEngine = context.createSSLEngine("www.example.com", 443);
Or
// Create SSLSocket object that enables TLS version 1.2.
SSLSocketFactory socketFac = context.getSocketFactory();
SSLSocekt sslSocket = (SSLSocekt)socketFac.createSocket("www.example.com", 443);
Use the SSLSocket/SSLEngine.setEnabledProtocols() API:
 

Applications can set the enabled protocols explicitly in an SSLSocket/SSLEngine object. For example:

// Enable TLS 1.2 in an SSLSocket object.
sslSocket.setEnabledProtocols(new String[] {"TLSv1.2"});

// Enable TLS 1.2 in an SSLEngine object.
sslEngine.setEnabledProtocols(new String[] {"TLSv1.2"});
Use the SSLParameters.setProtocols() API:
Applications can set the protocols in an SSLParameters object, and then apply it to a connection via the SSLSocket.setSSLParameters() and SSLEngine.setSSLParameters() methods. For example:
// Set TLS 1.2 only in an SSLParameters object.
sslParameters.setProtocols(new String[] {"TLSv1.2"});

// Apply the parameters to an SSLSocket object.
sslSocket.setSSLParameters(sslParameters);

// Apply the parameters to an SSLEngine object.
sslEngine.setSSLParameters(sslParameters);

[{"Type":"MASTER","Line of Business":{"code":"LOB57","label":"Power"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000001gHbAAI","label":"Java Development Kit->Java Secure Socket Extension"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions"}]

Document Information

Modified date:
06 August 2021

UID

nas8N1022279

Page Feedback