VISUAL STUDIO   Windows Mac

HttpClient Stack and SSL/TLS Implementation Selector for Android

PDF for offline use
Related Articles:

Let us know how you feel about this

Translation Quality


0/250

last updated: 2017-07

The HttpClient Stack and SSL/TLS Implementation selectors determine the HttpClient and SSL/TLS implementation that will be used by your Xamarin.Android apps.

Xamarin.Android provides two combo boxes that will control the TLS settings for an Android app. One combo box will identify which HttpMessageHandler will use when instantiating an HttpClient object, while the other identifies which TLS implementation will be used by web requests.

ℹ Projects must reference the System.Net.Http assembly.

The settings for the HttpClient stack are found in the Project Options for a Xamarin.Android Project. Click on the Build > Android Build settings and click on the General tab:

Visual Studio for Mac Android Options

The settings for the HttpClient stack are found in the Project Options for a Xamarin.Android project. Click on the Android Options tab, and then click on the Advanced Options button. This will display the Advanced Android Options dialog which has two combo boxes, one for the HttpClient implementation and one for the SSL/TLS implementation:

Visual Studio Android Options

HttpClient Stack Selector

This project option controls which HttpMessageHandler implementation will be used each time an HttpClient object is instantiated. By default, this is the managed HttpClientHandler.

Android HttpClient implementation combo box in Visual Studio for Mac

Android HttpClient implementation combo box in Visual Studio

Managed (HttpClientHandler)

Managed handler is the fully managed HttpClient handler that has been shipped with previous Xamarin.Android versions.

Pros:

  • It is the most compatible (features) with MS .NET and older Xamarin versions.

Cons:

  • It is not fully integrated with the OS (eg. limited to TLS 1.0).
  • It is usually much slower (eg. encryption) than native API.
  • It requires more managed code, creating larger applications.

AndroidClientHandler

AndroidClientHandler is the new handler that delegates to native Java/OS code instead of implementing everything in managed code.

Pros:

  • Use native API for better performance and smaller executable size.
  • Support for the latest standards, eg. TLS 1.2.

Cons:

  • Requires Android 5.0 or later.
  • Some HttpClient features/options are not available.

Programatically Using AndroidClientHandler

The Xamarin.Android.Net.AndroidClientHandler is an HttpMessageHandler implementation specifically for Xamarin.Android. Instances of this class will use the native java.net.URLConnection implementation for all HTTP connections. This will theoretically provide an increase in HTTP performance and smaller APK sizes.

This code snippet is an example of how to explicitly for a single instance of the HttpClient class:

// Android 5.0 or higher, Xamarin.Android 6.1 or higher
HttpClient client = new HttpClient(new Xamarin.Android.Net.AndroidClientHandler ());
ℹ️

Note: The underlying Android device must support TLS 1.2 (ie. Android 5.0 and later)

SSL/TLS implementation build option

This project option controls what underlying TLS library will be used by all web request, both HttpClient and WebRequest. By default, TLS 1.2 is selected:

TLS/SSL implementation combo box in Xamarin Studio

TLS/SSL implementation combo box in Visual Studio

For example:

var client = new HttpClient();

If the HttpClient implementation was set to Managed and the TLS implementation was set to Native TLS 1.2+, then the client object would automatically use the managed HttpClientHandler and TLS 1.2 (provided by the BoringSSL library) for its HTTP requests.

However, if the HttpClient implementation is set to AndroidHttpClient, then all HttpClient objects will use the underlying Java class java.net.URLConnection and will be unaffected by the TLS/SSL implementation value. WebRequest objects would use the BoringSSL library.

Other ways to control SSL/TLS configuration

There are three ways that a Xamarin.Android application can control the TLS settings:

  1. Select the HttpClient implmentation and default TLS library in the Project Options.
  2. Programatically using Xamarin.Android.Net.AndroidClientHandler.
  3. Declare environment variables (optional).

Of the three choices, the recommended approach is to use the Xamarin.Android project options to declare the default HttpMessageHandler and TLS for the entire app. Then, if necessary, programmatically instantiate Xamarin.Android.Net.AndroidClientHandler objects. These options are described above.

The third option – using environment variables – is explained below.

Declare Environment Variables

There are two environment variables that are related to the use of TLS in Xamarin.Android:

  • XA_HTTP_CLIENT_HANDLER_TYPE – This environment variable declares the default HttpMessageHandler that the application will use. For example:
XA_HTTP_CLIENT_HANDLER_TYPE=Xamarin.Android.Net.AndroidClientHandler
  • XA_TLS_PROVIDER – This environment variable will declare which TLS library will be used, either btls, legacy, or default (which is the same as omitting this variable):
XA_TLS_PROVIDER=btls

This environment variable is set by adding an environment file to the project. An environment file is a Unix-formatted plain-text file with a build action of AndroidEnvironment:

Screenshot of the AndroidEnvironment build action in Xamarin Studio.

Screenshot of the AndroidEnvironment build action in Visual Studio.

Please see the Xamarin.Android Environment guide for more details about environment variables and Xamarin.Android.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.