适用于 Android 的 HttpClient Stack 和 SSL/TLS 实现选择器

项目
07/13/2023

HttpClient Stack 和 SSL/TLS 实现选择器确定 Xamarin.Android 应用将使用的 HttpClient 和 SSL/TLS 实现。

项目必须引用 System.Net.Http 程序集。

警告

2018 年 4 月 - 由于安全要求（包括 PCI 合规性）增加，主要云提供商和 Web 服务器预计将停止支持早于 1.2 的 TLS 版本。在 Visual Studio 的早期版本中创建的 Xamarin 项目默认使用旧版 TLS。

为了确保应用继续使用这些服务器和服务， 应使用如下所示的 Android HttpClient 和 Native TLS 1.2 设置更新 Xamarin 项目，然后重新生成应用并将其重新部署到 用户。

Visual Studio
Visual Studio for Mac

Xamarin.Android HttpClient 配置位于 “项目选项” > “Android 选项”中，然后单击“ 高级选项” 按钮。

以下是 TLS 1.2 支持的建议设置：

备用配置选项

AndroidClientHandler

AndroidClientHandler 是委托给本机 Java/OS 代码的新处理程序，而不是在托管代码中实现所有内容。 这是建议选项。

优点

使用本机 API 可提高性能和更小的可执行文件大小。
支持最新标准，例如 TLS 1.2。

缺点

需要 Android 4.1 或更高版本。
某些 HttpClient 功能/选项不可用。

托管 (HttpClientHandler)

托管处理程序是以前 Xamarin.Android 版本附带的完全托管的 HttpClient 处理程序。

优点

它是与 MS .NET 和较旧 Xamarin 版本) 最兼容的 (功能。

缺点

它未与 OS (完全集成，例如。限制为 TLS 1.0) 。
例如，它通常慢得多 (。加密) 比本机 API。
它需要更多托管代码，从而创建更大的应用程序。

选择处理程序

和 HttpClientHandler 之间的AndroidClientHandler选择取决于应用程序的需求。 AndroidClientHandler 建议用于最新的安全支持，例如。

需要 TLS 1.2+ 支持。
你的应用面向 Android 4.1 (API 16) 或更高版本。
需要对 HttpClient的 TLS 1.2+ 支持。
不需要对 WebClient的 TLS 1.2+ 支持。

HttpClientHandler 如果需要 TLS 1.2+ 支持，但必须支持早于 Android 4.1 的 Android 版本，则这是一个不错的选择。如果需要对 WebClient的 TLS 1.2+ 支持，这也是一个不错的选择。

从 Xamarin.Android 8.3 开始， HttpClientHandler 默认使用 Boring SSL (btls) 作为基础 TLS 提供程序。 Boring SSL TLS 提供程序具有以下优势：

它支持 TLS 1.2+。
它支持所有 Android 版本。
它为 HttpClient 和 WebClient提供 TLS 1.2+ 支持。

使用 Boring SSL 作为下层 TLS 提供程序的缺点是，它可以增加生成的 APK 的大小， (它为每个受支持的 ABI) 增加大约 1MB 的额外 APK 大小。

从 Xamarin.Android 8.3 开始，默认 TLS 提供程序为 Boring SSL (btls) 。如果不想使用 Boring SSL，可以通过将属性设置为 $(AndroidTlsProvider)legacy (来还原历史托管 SSL 实现，了解有关设置生成属性的详细信息，请参阅生成过程) 。

以编程方式使用 `AndroidClientHandler`

Xamarin.Android.Net.AndroidClientHandler是HttpMessageHandler专用于 Xamarin.Android 的实现。此类的实例将对所有 HTTP 连接使用本机 java.net.URLConnection 实现。理论上，这将提高 HTTP 性能和更小的 APK 大小。

此代码片段是一个示例，说明如何显式为类的 HttpClient 单个实例：

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

注意

基础 Android 设备必须支持 TLS 1.2 (即。Android 4.1 及更高版本) 。请注意，Android 5.0+ 中正式支持 TLS 1.2。但是，某些设备在 Android 4.1+ 中支持 TLS 1.2。

SSL/TLS 实现生成选项

此项目选项控制所有 Web 请求（和 HttpClientWebRequest）将使用的基础 TLS 库。默认情况下，选择 TLS 1.2：

Visual Studio
Visual Studio for Mac

例如：

var client = new HttpClient();

如果 HttpClient 实现设置为 Managed ，TLS 实现设置为 Native TLS 1.2+，则 client 对象将自动使用 BoringSSL 库) 提供的托管 HttpClientHandler 和 TLS 1.2 (对其 HTTP 请求。

但是，如果 HttpClient 实现 设置为 AndroidHttpClient，则所有 HttpClient 对象都将使用基础 Java 类 java.net.URLConnection ，并且不受 TLS/SSL 实现 值影响。 WebRequest 对象将使用 BoringSSL 库。

控制 SSL/TLS 配置的其他方法

Xamarin.Android 应用程序可以通过三种方式控制 TLS 设置：

在“项目选项”中选择 HttpClient 实现和默认 TLS 库。
以编程方式使用 Xamarin.Android.Net.AndroidClientHandler。
(可选) 声明环境变量。

在三个选项中，建议的方法是使用 Xamarin.Android 项目选项声明整个应用的默认 HttpMessageHandler 和 TLS。然后，如有必要，以编程方式实例化 Xamarin.Android.Net.AndroidClientHandler 对象。上面介绍了这些选项。

下面介绍了第三个选项（使用环境变量）。

声明环境变量

有两个环境变量与在 Xamarin.Android 中使用 TLS 相关：

XA_HTTP_CLIENT_HANDLER_TYPE – 此环境变量声明应用程序将使用的默认值 HttpMessageHandler 。例如：
```
XA_HTTP_CLIENT_HANDLER_TYPE=Xamarin.Android.Net.AndroidClientHandler
```
XA_TLS_PROVIDER– 此环境变量将声明要使用的 TLS 库、btlslegacy、或 default (这与省略此变量) 相同：
```
XA_TLS_PROVIDER=btls
```