HttpClient Stack and SSL/TLS Implementation Selector

PDF for offline use:
Related Articles:

Let us know how you feel about this.


0/250
Thanks for the feedback!

last updated: 2016-04

The new HttpClient Stack and SSL/TLS Implementation Selector determines the HttpClient and SSL/TLS Implementation that will be used by your Xamarin.iOS, Xamarin.tvOS or Xamarin.Mac app.

New HttpClient Stack Selector

Available for Xamarin.iOS, Xamarin.tvOS and Xamarin.Mac: this controls which HttpClient implementation to use. The default continues to be an HttpClient that is powered by HttpWebRequest, while you can now optionally switch to an implementation that uses iOS’s, tvOS's or OS X's native transports (NSUrlSession or CFNetwork depending on the OS). The upside is smaller binaries, and faster downloads, the downside is that it requires the event loop to be running for async operations to be executed.

Selecting a HttpClient Stack

To adjust the HttpClient being used by your app, double-click the Project Name in the Solution Explorer to open the Project Options. Next, switch to the Build settings for your project. For example, iOS Build for a Xamarin.iOS app:

From the HttpClient Implementation dropdown, select the HttpClient type as one of the following: Managed, CFNetwork or NSUrlSession.

Managed (Default)

The Managed handler is the fully managed HttpClient handler that has been shipped with previous version of Xamarin.

Pros:

  • It has the most compatible feature set with Microsoft .NET and older Xamarin versions.

Cons:

  • It is not fully integrated with the Apple OSes and is limited to TLS 1.0.
  • It typically much slower at things like encryption than the native APIs.
  • It requires more managed code, thus creating a larger app distributable.

CFNetwork

The CFNetwork-based handler is based on the native CFNetwork framework available in iOS 6 an greater.

Pros:

  • It uses native APIs for better performance and smaller executable size.
  • Supports for newer standards such as TLS 1.2.

Cons:

  • Requires iOS 6 or later.
  • Not available on watchOS.
  • Some HttpClient features/options are not available.

NSUrlSession

The NSURLSession-based handler is based on the native NSURLSession framework available in iOS 7 an greater.

Pros:

  • It uses native APIs for better performance and smaller executable size.
  • Supports for the latest standards such as TLS 1.2.

Cons:

  • Requires iOS 7 or later.
  • Some HttpClient features/options are not available.

New SSL/TLS implementation build option

SSL (Secure Socket Layer) and its successor, TLS (Transport Layer Security), provide support for HTTP and other network connections via System.Net.Security.SslStream.

The new SSL/TLS implementation build option controls the SSL/TLS backend used by Xamarin.iOS, Xamarin.tvOS and Xamarin.Mac. It switches between Mono’s own TLS stack, and one powered by Apple’s TLS stack present in Mac and iOS.

Selecting a SSL/TLS implementation

To adjust the SSL/TLS implementation being used by your app, double-click the Project Name in the Solution Explorer to open the Project Options. Next, switch to the Build settings for your project. For example, iOS Build for a Xamarin.iOS app:

From the SSL/TLS Implementation dropdown, select the SSL/TLS type as one of the following: Mono or Apple TLS.

Mono (default)

Currently, the SslStream implementation provided by Mono only supports TLS version 1.0 and does not yet support the newer version 1.1 and 1.2 protocols.

Apple TLS

If you choose to use the Apple SSL/TLS, Xamarin.iOS, Xamarin.tvOS or Xamarin.Mac's System.Net.Security.SslStream will call Apple's native SSL/TLS implementation instead of using the managed implementation provided by Mono.

App Transport Security

Apple's App Transport Security (ATS) enforces secure connections between internet resources (such as the app's back-end server) and your app. ATS ensures that all internet communications conform to secure connection best practices, thereby preventing accidental disclosure of sensitive information either directly through your app or a library that it is consuming.

Since ATS is enabled by default in apps built for iOS 9, tvOS 9 and OS X 10.11 (El Capitan) and greater, all connections using NSUrlConnection, CFUrl or NSUrlSession will be subject to ATS security requirements. If your connections do not meet these requirement, they will fail with an exception.

Based on your select of HttpClient Stack and SSL/TLS Implementation, you may need to make modifications to your app to work correctly with ATS as well.

To find out more about ATS, please see our App Transport Security guide.

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.