OkHttp 3.13 Requires Android 5+

Today we’re releasing OkHttp 3.13. With this update we’re bumping the project’s requirements from this:

• Android 2.3+ / API 9+ (released December 2010)

• Java 7+ (released July 2011)

to this:

• Android 5.0+ / API 21+ (released November 2014)

• Java 8+ (released March 2014)

Cutting off old devices is a serious change and we don’t do it lightly! I’d like to explain why we’re doing this, what we’re doing to minimize disruption, and how to upgrade.

Why Android 5+ and Why Now?

TLS is the mechanism that makes HTTPS calls secure, private, and authenticated. OkHttp is aware of five versions: SSLv3 (1996), TLSv1 (1999), TLSv1.1 (2006), TLSv1.2 (2008), and TLSv1.3 (2018). We dropped support for SSLv3 in 2014 in response to the POODLE attack.

Now it’s time to drop both TLSv1 and TLSv1.1 and to make TLSv1.2 the Internet’s new minimum standard. On October 15 our colleagues at Google, Mozilla, Microsoft, and Apple announced that their browsers will require TLSv1.2 or better starting in early 2020.

Google added support for TLSv1.2 in Android 5.0. Oracle added it in Java 8. In OkHttp 3.13 we require that the host platform has built-in support for TLSv1.2.

What about Android 4.x?

Google’s distribution dashboard shows that ~11% of the devices that visited the Play Store in October 2018 were running Android 4.x. We’ve created a branch, OkHttp 3.12.x, to support these devices. Should we encounter any severe bugs or security problems we’ll backport the fixes and release. We plan to maintain this branch through December 31, 2020.

If you really need TLSv1.2 on Android 4.x, that’s possible! Ankush Gupta has written a thorough guide that explains how to get Google Play Services to do it. Even if you follow this process you should still use OkHttp 3.12.x with Android 4.x devices.

How do I upgrade?

Confirm that your project’s minSdkVersion is at least 21 and that your Android Gradle Plugin version is at least 3.2. Then use our new Maven coordinates in your build.gradle:

dependencies {
  implementation "com.squareup.okhttp3:okhttp:3.13.1"
  ...
}

You also need to set the Java version to 1.8 or better. We’re using Java 8 features in our source code now (yay lambdas!) and this gets Android’s compilers to handle it:

android {
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
  ...
}

The update also requires TLSv1.2-capable web servers by default. If your web servers are out of date HTTPS calls to them will fail with an SSLException. If necessary you can configure OkHttp 3.13 to allow TLSv1 and TLSv1.1 connections:

OkHttpClient client = new OkHttpClient.Builder()
    .connectionSpecs(Arrays.asList(ConnectionSpec.COMPATIBLE_TLS))
    .build();

If you find yourself doing this, be warned: in early 2020 web browsers will stop connecting to your web server! We recommend raising the server’s abilities over lowering the client’s demands wherever possible.

We document TLS configuration changes on our project wiki.

Thanks

We developers spend a lot of time and energy keeping dependencies up-to-date. We should celebrate this work! Our users trust their apps with what’s most important to them including private conversations, money, and family photos. We honor that trust by securing their data in the best way we can.

I appreciate the time you’ll spend on this update. It might not be easy but it is important.