Working with TLS in the SDK for Java

The AWS SDK for Java uses the TLS capabilities of its underlying Java platform. In this topic, we show examples using the OpenJDK implementation used by Amazon Corretto 17.

To work with AWS services, the underlying JDK must support a minimum version of TLS 1.2, but TLS 1.3 is recommended.

Users should consult the documentation of the the Java platform they are using with the SDK to find out which TLS versions are enabled by default as well as how to enable and disable specific TLS versions.

How to check TLS version information

Using OpenJDK, the following code shows the use of SSLContext to print which TLS/SSL versions are supported.

System.out.println(Arrays.toString(SSLContext.getDefault().getSupportedSSLParameters().getProtocols()));

For example, Amazon Corretto 17 (OpenJDK) produces the following output.

[TLSv1.3, TLSv1.2, TLSv1.1, TLSv1, SSLv3, SSLv2Hello]

To see the SSL handshake in action and what version of TLS is used, you can use the system property javax.net.debug.

For example, run a Java applications that uses TLS.

java app.jar -Djavax.net.debug=ssl:handshake

The application logs the SSL handshake similar to the following.

...
javax.net.ssl|DEBUG|10|main|2022-12-23 13:53:12.221 EST|ClientHello.java:641|Produced ClientHello handshake message (
"ClientHello": {
  "client version"      : "TLSv1.2",

...
javax.net.ssl|DEBUG|10|main|2022-12-23 13:53:12.295 EST|ServerHello.java:888|Consuming ServerHello handshake message (
"ServerHello": {
  "server version"      : "TLSv1.2",
...

Enforce a minimum TLS version

The SDK for Java always prefers the latest TLS version supported by the platform and service. If you wish to enforce a specific minimum TLS version, consult your Java platform’s documentation.

For OpenJDK-based JVMs, you can use the system property jdk.tls.client.protocols.

For example, if you want SDK service clients in your application to use TLS 1.2, even though TLS 1.3 is available, provide the following system property.

java app.jar -Djdk.tls.client.protocols=TLSv1.2

AWS API endpoints upgrade to TLS 1.2

See this blog post for information about AWS API endpoints moving to TLS 1.2 for the minimum version.