In my years of development, one thing I’ve learned for certain is that securing your network requests is an essential part of any mobile application. A few weeks ago one of my own applications stopped working due to a change to a Secure Sockets Layer (SSL) certificate on meetup.com’s authentication server, which made me realize the important role Transport Layer Security (TLS) plays in securing app and server requests.

I discuss TLS in more details on my podcast Merge Conflict, but in short, TLS provides symmetric cryptography that prevents man-in-the-middle attacks as well as privacy of any communication leaving a mobile device. Meetup had updated their authentication server to require a minimum of TLS 1.2 support when making requests, so I was able to easily update my application and enable TLS 1.2 support for my Xamarin.iOS and Xamarin.Android applications with just a few build settings.

The Basics

When it comes to network requests and TLS, there are two important settings that we’re able to modify:

• HttpClient: Handles the HttpMessageHandler implementation to provide a managed handler or offer the underlying native implementation.
• TLS/SSL: Handles the implementation of TLS the application uses.

Each of the implementations that we could select provides different functionality, speed, and compatibility, while all providing a standard network request call and acting transparently behind the scenes.

Android

The settings for selecting the HttpClient and TLS implementations are found by right-clicking the project, then Properties > Android Options > Advanced in Visual Studio on Windows, or Options > Build > Android Build > General in Xamarin Studio.

Implementations

On Android the HttpClient implementation that we select will control the defaults in our code for new HttpClient(), while the TLS/SSL Implementation controls defaults for WebRequest.

The managed HttpClientHandler is the fully managed implementation of the HttpClient handler, which has been the default for Xamarin.Android for years. While it’s the most compatible in terms of HttpClient features, the trade off is a slightly larger executable size and may execute slower than the native implementations. This implementation was only compatible with TLS 1.0/1.1 in the past, however, there is a new option in the TLS/SSL Implementation to use Native TLS 1.2+ that will use Google’s Boring SSL under the hood for all calls.

The Native AndroidClientHandler option uses the native java.net.URLConnection for all HTTP connections, with improved performance and smaller executable size. The caveat with the AndroidClientHandler is that while it will work on all versions of Android, it will only provide TLS 1.2 support on Android 5.0+ devices and a few HttpClient features may not be available.

Selecting Programmatically

Optionally, you can mix and match using the managed and native HttpClient Handler on a call by call basis. Simply pass in an instance of the AndroidClientHandler class when creating the HttpClient:

using System.Net.Http;
...
// This will use the default message handler for the application; as
// set in the Project Options for the project.
var client = new HttpClient();

// Use AndroidClientHandler for all calls from this HttpClient
var client = new HttpClient(new Xamarin.Android.Net.AndroidClientHandler ());

OS & TLS Compatibility

It’s important to ensure that Native TLS 1.2+ is selected in the SSL/TLS Implementation box, if your application requires TLS 1.2+. The version of Android the application is required to run on will determine if we should select the Managed or Native HttpClient Implementation. For Meetup Manager, I selected the Managed HttpClientHandler and Native TLS 1.2+ so I could support TLS 1.2+ in all of my calls regardless of the version of Android.

iOS & macOS

iOS and macOS are more simplified when it comes to Handlers and TLS support. All iOS applications from Xamarin.iOS 10.8 on use Apple’s native TLS implementation, which provides full TLS 1.2+ support for all applications. There are still several options that developers may choose when it comes to the HttpClient Implementation, which can be found by right-clicking the project and selecting Properties > iOS Build > Advanced in Visual Studio or Options > Build > iOS Build in Xamarin Studio.

There are three different HttpClient Handlers that can be selected for iOS applications. The default managed HttpClientHandler offers the largest compatibility with HttpClient features. However, like the managed Android HttpClient Handler, it also requires more managed code, which can increase the application’s size. The other two options, CFNetwork Handler (iOS 6+) and NSURLSession Handler (iOS 7+), are wrappers around their respective native APIs, offering the use of the underlying native code for network communications and transport. The use of these will result in a smaller executable, improved network performance, and they use the underlying iOS queues and threads. The drawback is that there may not be full feature parity with all .NET HttpClient features and options.

Selecting Programmatically

Just like Xamarin.Android we can pragmatically choose which HttpMessageHandler our app uses:

using System.Net.Http;
...
// This will use the default message handler for the application; as
// set in the Project Options for the project.
var client = new HttpClient();

// This will create an HttpClient that explicitly uses the CFNetworkHandler
var client = new HttpClient(new CFNetworkHandler());

// This will create an HttpClient that explicitly uses NSUrlSessionHandler
var client = new HttpClient(new NSUrlSessionHandler());

Updating our TLS and HttpClient implementations will enable our applications to be fully secure and compatible with any backend that our application must interact with.

Learn More

Be sure to read through our updated cross-platform Transport Layer Security documentation for a full, in-depth analysis of all TLS options available to Xamarin developers, which includes additional toggles and guidance. You can also check out the platform-specific documentation for Android and iOS / macOS respectively. Also, be sure to listen to my trials and tribulations on Merge Conflict 37: TLS – How do you EVEN. Finally, learn more with Xamarin University’s free self-guided course “Consuming REST-based Web Services”, which examines how to integrate with, and consume, RESTful web services in mobile apps.