AWS Developer Tools Blog

TLS 1.3 Incompatibility with AWS SDK for Java versions 1.9.5 to 1.10.31

AWS works to ensure that your Java applications connect using the most modern encryption protocols that provide performance and security advances. This includes Transport Layer Security (TLS) version 1.3, which we are actively adding support for in all of our services. This blog is to notify you that older versions of the AWS SDK for Java, 1.9.5 to 1.10.31, are incompatible with TLS 1.3. If you use these versions, to maintain your ability to connect to AWS endpoints, you will need to take one of the three possible actions we outline below. If no action is taken, customers using the affected versions will fail with “SecurityException: Invalid SSL master secret”, when attempting to connect to AWS endpoints that offer TLS 1.3.   AWS SDK for Java versions 1.10.32 onward, including the AWS SDK for Java 2.x, are unaffected.

What AWS Java for SDK versions are unable to connect using TLS 1.3?

Your application may be impacted if it meets the two following conditions:

  1. Your application is utilizing a version of the AWS SDK for Java between 1.9.5 and 1.10.31, AND
  2. The JDK version you are using enables TLS 1.3 by default or you have explicitly enabled TLS 1.3 using the jdk.tls.client.protocols system property.

If your application meets both of these conditions, all API calls through the SDK for Java will fail when the AWS service supports TLS 1.3.

If your application only meets the first condition, be aware that upgrading your JDK in the future to one that enables 1.3 will also mean your application may be impacted. On July 19th, 2022 Java 8 will enable TLS 1.3 by default, although it does not do so currently. As of May 11, 2022, versions of the JDK from 11 onwards enable TLS 1.3 by default.

How do I know if I am impacted?

You can determine if you are currently using an affected AWS SDK Java version by checking the aws-java-sdk-core version in the output of the following Maven command, using the Maven Dependency Plugin:

mvn dependency:tree

The example below shows that MyApp application has a dependency on SDK for Java version 1.9.5:

[INFO] Scanning for projects...
[INFO]
[INFO] --------------------< software.amazon.awssdk:MyApp >--------------------
[INFO] Building MyApp 1.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-dependency-plugin:2.8:tree (default-cli) @ MyApp ---
[INFO] software.amazon.awssdk:MyApp:jar:1.0-SNAPSHOT
[INFO] +- com.amazonaws:aws-java-sdk-cloudfront:jar:1.9.5:compile

To check your Java version, you can use

java -version

Please note that it’s not uncommon for applications to use a specific java executable when running. Be sure to that you’re invoking the Java executable that will eventually be used to run your application.

The SDK version and JDK version are also included the User-Agent header of the HTTP requests made by the SDK so you can also query your CloudTrail logs to see if you are making API calls with the affected SDK version.

What should I do if my application is affected?

If you have determined that your application is affected, you can choose one of the following options:

Option 1 (Least effort): Upgrade your application to AWS SDK for Java 1.12.x or later.

Upgrading your application to the latest supported version of the SDK for Java 1.x is the easiest option. Please note that some breaking SDK behavior changes exist between 1.9.x, 1.10.x and 1.12.x. For example, 1.10.x and onwards enables throttled retries by default, and removes some previously public APIs from the service client interfaces. They are not drop-in compatible and you will need to test your application carefully to ensure it’s working as expected under the newer version.

Option 2 (Recommended): Upgrade your application to the AWS SDK for Java version 2.x.

The AWS SDK for Java 2.x is a major rewrite of the 1.x code base built on top of Java 8+. In addition to addressing TLS 1.3 issue, it includes many updates, such as improved consistency, ease of use, and strongly enforced immutability.  Please visit our Migration Guide to see all the major features that are new in version 2.x as well as guidance on how to migrate your code to version 2.x from 1.x.

Option 3 (Short term workaround): Temporarily omit TLS 1.3 from SDK enabled protocols.

We understand that you may not have the ability to upgrade your application to SDK for Java 1.12.x or 2.x right away. For example, you may be using a third-party library that uses one of the affected versions under the hood. In these situations, you can temporarily explicitly omit TLS 1.3 from your enabled protocols, using the jdk.tls.client.protocols system property. For example, the following enables only TLS 1.2 when running from the command line:

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

Please note that this option is recommended as a short-term workaround while you are upgrading your application to the SDK for Java 1.12.x or 2.x, because it prevents the use of newer, more secure TLS versions. 

If you have any questions or concerns, you can contact us in Github.