How to enable TLS 1.2 as the default protocol for SSL connections on Java SE 7 clients

Applies To

Java SE JDK and JRE - Version 7 and later
Oracle WebLogic Server - Version 10.3.6 to 12.1.3.0.0
Any platform

Introduction

For SSL connections from Java SE 7 clients, the default handshake protocol version is TLS 1.0. This document describes ways to to enable TLS 1.2 as the default protocol for Java SE 7 clients.

Note: Java 7 SSLServerSocket has TLS 1.2 enabled by default. This document discusses client sockets only.

Solutions

The Java client will always first attempt to negotiate over the highest level protocol enabled. In other words, the highest level protocol enabled becomes, in effect, the default protocol, since it is always attempted first. Therefore, simply enabling TLS 1.2, since there are no higher level protocols available in Java SE 7, makes it the default protocol. Java SE 7 clients, prior to 7 update 75 (7u75), had two protocols enabled by default: SSL 3 and TLS 1.0. Beginning with Java 7u75, SSL 3 was disabled by default. See also the Java SE 7u75 Release Notes.

There are different ways to control the default protocol version Java SE 7 clients will use, depending on which mechanism you are using to create the SSL connection.

Rich Internet Applications (RIAs)

For RIAs, those using the Java Plugin or WebStart applications, TLS 1.2 can be enabled by performing the following steps:

Open the Java Control Panel
Click on the “Advanced” tab
Scroll down to the “Advanced Security Settings” section
Check the “Use TLS 1.2” checkbox.

See also this Control Panel Example where SSLv2ClientHello and SSL 3 are disabled, and TLS 1, TLS 1.1, and TLS 1.2 are enabled.

HttpsClient / HttpsURLConnection

Applications using the HttpsClient or HttpsURLConnection classes can use the https.protocols system property. The https.protocols system property is a JSSE tuning parameter that controls the protocol version used by Java clients which obtain https connections through the use of the HttpsURLConnection class or via URL.openStream() operations. This property can update the default version in case your Java SE 7 client wants to use TLS 1.2 as its default.

For implementation, see the JSSE Reference Guide: >https.protocols system property. This contains a comma-separated list of protocol suite names specifying which protocol suites to enable on this HttpsURLConnection. See the SSLSocket setEnabledProtocols(String[]) method.

System properties are set on the Java command line as a -D flag. You can set it singly:

-Dhttps.protocols="TLS 1.2"

or as a list of choices (handshake is first attempted at the highest level protocol):

-Dhttps.protocols="TLS 1,TLS 1.1,TLS 1.2"

Simple code example:

$more SSLConnect.java
import java.io.*;
import java.net.*;

public class SSLConnect {
    public static void main(String[] args) throws Exception {
        URL u = new URL("https://[URL]");
        BufferedReader in = new BufferedReader(new InputStreamReader(u.openStream()));
    }
}

Here we run the above code with the -Dhttps.protocols="TLS 1.2" flag. We added the SSL debug flag, -Djavax.net.debug=all, to verify the client uses TLS 1.2 for the initial handshake:

$ java -Djavax.net.debug=all -Dhttps.protocols="TLS 1.2"  SSLConnect

...

Is initial handshake: true
Is secure renegotiation: false
main, setSoTimeout(0) called
%% No cached client session
*** ClientHello, TLS 1.2

...

SSLSocket / SSLSocketFactory

Applications managing their own SSLSockets need to set up their EnabledProtocols preferences via the SSLSocket API. If your application is required to run at a specific, user-specified TLS protocol level, then it should implement code that allows the user to pass in a system property which it can then use to configure the SSLSockets it creates. For a code example, please see Document 1910270.1 “How to Enable TLS 1.2 for a Client Side SSLSocket for Java SE 7” on My Oracle Support (Oracle Customers Only). Note: The example is prior to SSL 3 being disabled by default in 7u75.

Note: Beginning with Java SE 8, TLS 1.2 is the default handshake protocol for Client SSL connections.
With Java SE 7 update 95 and Java SE 8, the jdk.tls.client.protocols system property is introduced. This is a new JSSE tuning parameter for enabling/disabling SunJSSE protocol versions on the client. This property is set to a quotation-enclosed, comma-separated list of protocol versions you wish to be enabled for the client. All others are disabled for the client. For example: $ java ... -Djdk.tls.client.protocols="TLS 1.1,TLS 1.2" In this example, only TLS 1.1 and TLS 1.2 are enabled for this client. SSL 2Hello, SSL 3, and TLS 1.0 are all disabled. See the Customizing JSSE section of the JSSE Reference Guide for details.

References

Last reviewed on Thu Jan 02 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

No time to become a TLS expert? Borrow one of ours.

Security Resources