Enabling TLS 1.2 on your .NET application

I recently came across an issue with several of our ASP.NET WebAPI services which were consuming a third-party set of APIs. These third-party APIs were configured to disable any requests from clients that were using TLS 1.0/1.1. Unfortunately, this included our own APIs. All requests to the third-party API were returning empty responses. After some discussion with one of the developers of the third-party APIs, he suggested the issue may be related to TLS 1.2 not being supported as he had seen the issue before.

Firstly, what is TLS? Here’s a definition from a Microsoft article that describes TLS best practices with regards to the .NET Framework.

Quote:

The Transport Layer Security (TLS) protocol is an industry standard designed to help protect the privacy of information communicated over the Internet. TLS 1.2 is a standard that provides security improvements over previous versions. TLS 1.2 will eventually be replaced by the newest released standard TLS 1.3 which is faster and has improved security

- Transport Layer Security (TLS) best practices with the .NET Framework | Microsoft Docs

I was able to run the third-party APIs from our local test environment, but not when I ran them from our staging / production environments which were hosted on Azure. I had to make several changes, including code changes to the ASP.NET WebAPI services and changes to our Azure hosting environments.

As many current servers are moving towards TLS 1.2/1.3 and removing support for TLS 1.0 /1.1, connectivity issues between newer servers and older (legacy) .NET applications are becoming more common. Installing a newer version of the .NET Framework onto your development environment is not the answer. The solution is down to the version of the .NET Framework used for compiling your project. This is what actually matters when it comes to selecting the supported TLS version during the TLS handshake.

In this article I will describe the changes I have made to our Azure hosting (where our ASP.NET WebAPIs are hosted) and the code changes which enabled TLS 1.2 support.

Upgrading our Azure hosting to support TLS 1.2

More accurately the changes I have made to our Azure hosting have removed support for earlier versions of TLS i.e. TLS 1.0/1.1. Although this change was not strictly necessary to fix the problem I was experiencing, it was appropriate in terms of tightening up the security of our ASP.NET WebAPIs and to ensure that our own APIs can only be accessed by clients that support TLS 1.2. This is quite simply achieved by opening the Azure portal and navigating to the App Service hosting. From there the TLS/SSL Settings blade can be selected.

I have set this to TLS 1.2 for both our staging and production environments. This sets the minimum TLS version. Therefore our hosting environments will no longer accept requests from earlier versions of TLS.

Code changes to support TLS 1.2

Depending on what version of .NET Framework your project uses will dictate the possible solutions available to you. If your project compiles against .NET Framework >= 4.7 then you are already good to go. Applications developed in .NET Framework 4.7 or greater automatically default to whatever the operating system they run on considers safe (which currently is TLS 1.2 and will later include TLS 1.3).

If your application has been developed in a version of the .NET Framework prior to 4.7 then you have two options.

- Recompile your application using .NET Framework 4.7 or greater

- If recompiling your application is not something you can do then you can update your .config file by adding the following.

Hide Copy Code

<configuration>
 <runtime>
  <AppContextSwitchOverrides value="Switch.System.Net.DontEnableSystemDefaultTlsVersions=false"/>
 </runtime>
</configuration>

Also make sure you have the following set in your .config file.

Hide Copy Code

<system.web>
 <compilation targetFramework="x.y.z" />
 <httpRuntime targetFramework="x.y.z" /> <-- this is the important one!
</system.web>

It is obviously preferable if x.y.x are the same i.e. that the application is compiled against and runs against the same .NET Framework version. So in the code sample x.y.z could be 4.6.1 or some other version of .NET Framework prior to 4.7.

In the cases where recompilation is not an option and you need to update your .config file instead (as described above), this should be viewed as a temporary workaround. The preferred (and best practice) solution is to recompile your application as soon as possible.

Microsoft have put together a useful document describing the best practices relating to TLS 1.2. The advice in this document should be carefully read and understood in order to fully secure your application.

So if your application doesn’t already support TLS 1.2 then it’s a good idea to put aside some time to make sure it does. Ensuring your application is up-to-date in terms of security can only be a good thing.