Asana is now deactivating TLS 1.0

TLS 1.0 is being deactivated across Asana’s services

TLS, or Transport Layer Security, is the successor to SSL (Secure Sockets Layer) in specifying a protocol for secure communications across the Internet. When connecting to a secure server (for example, sites with https addresses), TLS defines the set of methods by which a client and server can secure their connection. Defined in 1999, TLS 1.0 provided an update for SSL which revised the design and patched some vulnerabilities in the earlier protocol.

TLS 1.1, defined in 2006, contained revisions to the TLS protocol to further secure connections against some attack patterns which were found to compromise its security. This means that connections using the older TLS 1.0 protocol remain vulnerable to these attack vectors. As mentioned in an earlier post, it is for this reason that Asana has deprecated TLS 1.0 connections to our servers.

We are now rolling out this change. If you have an application that connects to Asana using TLS 1.0 or any version of the older SSL protocols, you can expect in the next few weeks to no longer be able to connect.

Most modern software, including both programming languages that use a library to connect securely and most popular web browsers, have been configured for quite some time to prefer newer versions of the protocol. If this is the case, you are already likely to be connecting over TLS 1.1 or 1.2. In this case, you will experience no change in your ability to connect to Asana.

If, however, you are using old and outdated software, or, as an OAuth integration developer, your users are using old and outdated web browsers, there is a possibility that your software may not support TLS 1.1 or 1.2. In this case, we strongly encourage you to be aware that this change is happening and to update your software as soon as possible to avoid service outages. As we turn off access to the Asana API, you will begin receiving 400 Bad Request responses, and, as always, we send a message back in the response body with more information about the error. This response will inform you that your TLS connection is out of date.

There are some situations that have been identified that warrant particular attention:

Mac OS X ships a very old version of OpenSSL which does not support TLS 1.1 and above. This means that, by default, software that links to libssl on OS X will likely be unable to connect to Asana’s API. Languages and libraries will have to be updated to link to a more modern version of OpenSSL, for instance, one installed using MacPorts or Homebrew. We are currently updating information about how to do this for each language in the documentation for our client libraries:

Salesforce has constructed a table of guidelines for software that is and is not compatible with TLS 1.1 and higher. In general:

  • Google Chrome version 38 (Oct 2014) and newer is compatible by default across all operating systems. Version 22 (Sept 2012) to 37 are compatible when running on modern operating systems, for example Windows Vista and Mac OS X 10.6 and newer. Version 21 and older are not compatible.

  • Firefox version 27 (Sept 2013) and newer is compatible by default. Version 23 to 26 are compatible, but must be configured to use TLS 1.1 and higher. Version 22 and older are not compatible.

  • Internet Explorer version 11 (Oct 2013) and above is compatible by default. Versions 8, 9, and 10 are compatible on Windows 7 and newer, but must be configured to use TLS 1.1 and higher. Internet Explorer 8, 9, and 10 on Vista and older, and Internet Explorer 7 and older, are not compatible.

  • Programming languages and libraries vary, but in general, languages and libraries that have been updated within the past few years will be compatible. In particular, note the information about OpenSSL on OS X above. Salesforce’s table covers the versions of several modern languages quite thoroughly.

Update: A temporary workaround: amnesty headers

It’s very difficult for any organization to introduce a breaking change to their API. As long as nothing is breaking, there’s not much of a reason to take a look at, for instance, deprecation headers (though that’s a good practice); and after things are breaking, integration developers are stuck working with a zero-day break in the API. Neither case is ideal here: either developers never migrate off of old APIs that we want to expire, or we put them in an emergency state.

Here at Asana, we really don’t like those choices. We’ve been thinking about how to deal with this for a while, but the TLS deprecation change had a broader impact than we anticipated, and so we think it’s a good time to release a glimpse of what we’re thinking of doing in these cases.

For fixing breaking changes, here’s what we’re going to try:

  1. Begin returning a deprecation header when we identify requests that will break in Asana’s API. This header will only be returned on requests that will break when we introduce the change. In other words, if you see this header, your existing API call is on its way to being broken in some way. We’re currently working on what this header will be called and what it will contain.
  2. At the same time, we’ll return an Asana-Amnesty-{topic}-Expires header with a HTTP RFC 1123 date format, which is the same format that the standard HTTP Expires date is in. More information about this below.
  3. Send out a developer newsletter (and contact developers through other channels) to let them know there’s a deprecation in the API.
  4. After some time, we’ll introduce the breaking change at a low-level of errors. For instance, return a 4xx error for 10% of all requests. This error will both include the above headers and a descriptive error message in the response. The goal here is to provide significant feedback about changes occurring in the API, without completely disabling it, for developers who didn’t notice or haven’t had time to implement changes that mitigate the deprecated feature. Since the requests can be retried, even though there will be a significant number of errors being returned by the Asana API, developers who have written robust integrations with retries should still see eventual success.
  5. When we introduce the low-frequency breaking change, we’ll also start handling a request header: Asana-Amnesty-{topic}. Setting this header to true will enable requests to be served on a temporary basis without the 4xx error codes. This header can be set before the breaking change happens in order to ensure a completely smooth transition; the net effect will be that no breakage will occur.
  6. Increase the frequency of the breaking change over some time until the change is in full effect - that is, 100% of the requests without Asana-Amnesty-{topic}: true will fail with a 4xx error code.
  7. When the date in Asana-Amnesty-{topic}-Expires passes, we will no longer accept Asana-Amnesty-{topic} headers. At this time, all integrations which use the old behavior will be broken.

We think this provides the best possible experience for integrations developers, while allowing us to remove, for example, less-secure connections via TLS 1.0 to our API. There is a workflow that allows preemptive immunity to our breaking changes, that is, catching deprecation headers and preemptively setting the amnesty header, while still allowing Asana to implement a migration path and remove old ways of interacting with our API.

So, at this time, if the header Asana-Amnesty-Tls: true is passed to Asana’s API, we will still honor your request without returning a 4xx error code; but please note that this is a temporary measure, and we will stop accepting TLS 1.0 requests entirely on Wednesday, September 14, 2016.

This change is an important step to ensure the security of our users’ data, and we appreciate your participation. Thanks for helping us keep our users safe!

Matt Bramlage, Asana Developer Advocate