Android网络安全性配置

• 自定义信任锚：针对应用的安全连接自定义哪些证书颁发机构 (CA) 值得信任。例如，信任特定的自签署证书或限制应用信任的公共 CA 集。
• 仅调试重写：在应用中以安全方式调试安全连接，而不会增加已安装用户的风险。
• 明文通信选择退出：防止应用意外使用明文通信。
• 证书固定：将应用的安全连接限制为特定的证书。

添加安全配置文件

网络安全性配置特性使用一个 XML 文件，您可以在该文件中指定应用的设置。您必须在应用的清单中包含一个条目以指向该文件。以下代码摘自一份清单，演示了如何创建此条目：

1. <?xml version="1.0" encoding="utf-8"?> 
2. <manifest ... > 
3.     <application android:networkSecurityConfig="@xml/network_security_config" 
4.                     ... > 
5.         ... 
6.     </application> 
7. </manifest>  

自定义可信 CA

应用可能需要信任自定义的 CA 集，而不是平台默认值。出现此情况的最常见原因包括：

• 连接到具有自定义证书颁发机构的主机，如自签署或在公司内部签发的 CA。
• 将 CA 集仅限于您信任的 CA，而不是每个预装 CA。
• 信任系统中未包含的附加 CA。

默认情况下，来自所有应用的安全连接(使用 TLS 和 HTTPS 之类的协议)均信任预装的系统 CA，而面向 Android 6.0(API 级别 23)及更低版本的应用默认情况下还会信任用户添加的 CA 存储。应用可以使用 base-config(应用范围的自定义)或 domain-config(按域自定义)自定义自己的连接。

配置自定义 CA

假设您要连接到使用自签署 SSL 证书的主机，或者连接到其 SSL 证书是由您信任的非公共 CA(如公司的内部 CA)签发的主机。

res/xml/network_security_config.xml：

1. <?xml version="1.0" encoding="utf-8"?> 
2. <network-security-config> 
3.     <domain-config> 
4.         <domain includeSubdomains="true">example.com</domain> 
5.         <trust-anchors> 
6.             <certificates src="@raw/my_ca"/> 
7.         </trust-anchors> 
8.     </domain-config> 
9. </network-security-config>  

以 PEM 或 DER 格式将自签署或非公共 CA 证书添加到 res/raw/my_ca。

限制可信 CA 集

如果应用不想信任系统信任的所有 CA，则可以自行指定，缩减要信任的 CA 集。这样可以防止应用信任任何其他 CA 签发的欺诈性证书。

限制可信 CA 集的配置与针对特定域信任自定义 CA 相似，不同的是，前者要在资源中提供多个 CA。

res/xml/network_security_config.xml：

1. <?xml version="1.0" encoding="utf-8"?> 
2. <network-security-config> 
3.     <domain-config> 
4.         <domain includeSubdomains="true">secure.example.com</domain> 
5.         <domain includeSubdomains="true">cdn.example.com</domain> 
6.         <trust-anchors> 
7.             <certificates src="@raw/trusted_roots"/> 
8.         </trust-anchors> 
9.     </domain-config> 
10. </network-security-config>  

以 PEM 或 DER 格式将可信 CA 添加到 res/raw/trusted_roots。请注意，如果使用 PEM 格式，文件必须仅包含 PEM 数据，且没有额外的文本。您还可以提供多个 <certificates> 元素，而不是只提供一个元素。

信任附加 CA

应用可能需要信任系统不信任的附加 CA，出现此情况的原因可能是系统还未包含此 CA，或 CA 不符合添加到 Android 系统中的要求。应用可以通过为一个配置指定多个证书源来实现此目的。

res/xml/network_security_config.xml：

1. <?xml version="1.0" encoding="utf-8"?> 
2. <network-security-config> 
3.     <base-config> 
4.         <trust-anchors> 
5.             <certificates src="@raw/extracas"/> 
6.             <certificates src="system"/> 
7.         </trust-anchors> 
8.     </base-config> 
9. </network-security-config>  

配置用于调试的 CA

调试通过 HTTPS 连接的应用时，您可能需要连接到没有为生产服务器提供 SSL 证书的本地开发服务器。为了支持此操作，而又不对应用的代码进行任何修改，您可以通过使用 debug-overrides 指定仅在 android:debuggable 为 true 时才可信的仅调试 CA。通常，IDE 和构建工具会自动为非发布版本设置此标记。

这比一般的条件代码更安全，因为出于安全考虑，应用存储不接受被标记为可调试的应用。

res/xml/network_security_config.xml：

1. <?xml version="1.0" encoding="utf-8"?> 
2. <network-security-config> 
3.     <debug-overrides> 
4.         <trust-anchors> 
5.             <certificates src="@raw/debug_cas"/> 
6.         </trust-anchors> 
7.     </debug-overrides> 
8. </network-security-config>  

选择退出明文通信

旨在连接到仅使用安全连接的目的地的应用可以选择不再对这些目的地提供明文(使用解密的 HTTP 协议而非 HTTPS)支持。此选项有助于防止应用因外部源(如后端服务器)提供的网址发生变化而意外回归。请参阅 NetworkSecurityPolicy.isCleartextTrafficPermitted()，了解更多详情。

例如，应用可能需要确保与 secure.example.com 的所有连接始终通过 HTTPS 完成，以防止来自恶意网络的敏感流量。

res/xml/network_security_config.xml：

1. <?xml version="1.0" encoding="utf-8"?> 
2. <network-security-config> 
3.     <domain-config cleartextTrafficPermitted="false"> 
4.         <domain includeSubdomains="true">secure.example.com</domain> 
5.     </domain-config> 
6. </network-security-config>  

固定证书

一般情况下，应用信任所有预装 CA。如果有预装 CA 签发欺诈性证书，则应用将面临被中间人攻击的风险。有些应用通过限制信任的 CA 集或通过证书固定来选择限制其接受的证书集。

通过按公钥的哈希值(X.509 证书的 SubjectPublicKeyInfo)提供证书集完成证书固定。然后，只有至少包含一个已固定的公钥时，证书链才有效。

请注意，使用证书固定时，您应始终包含一个备份密钥，这样，当您被强制切换到新密钥或更改 CA 时(固定到某个 CA 证书或该 CA 的中间证书时)，您应用的连接性不会受到影响。否则，您必须推送应用的更新以恢复连接性。

此外，可以设置固定的到期时间，在该时间之后不执行证书固定。这有助于防止尚未更新的应用出现连接性问题。不过，设置固定的到期时间可能会绕过证书固定。

res/xml/network_security_config.xml：

1. <?xml version="1.0" encoding="utf-8"?> 
2. <network-security-config> 
3.     <domain-config> 
4.         <domain includeSubdomains="true">example.com</domain> 
5.         <pin-set expiration="2018-01-01"> 
6.             <pin digest="SHA-256">7HIpactkIAq2Y49orFOOQKurWxmmSFZhBCoQYcRhJ3Y=</pin> 
7.             <!-- backup pin --> 
8.             <pin digest="SHA-256">fwza0LRMXouZHRC8Ei+4PyuldPDcf3UKgO/04cDM1oE=</pin> 
9.         </pin-set> 
10.     </domain-config> 
11. </network-security-config>  

配置继承行为

将继承未在特定配置中设置的值。此行为允许进行更复杂的配置，同时又能保证配置文件可读。

如果未在特定条目中设置值，将使用来自更通用条目中的值。例如，未在 domain-config 中设置的值将从父级 domain-config(如果已嵌套)或者 base-config(如果未嵌套)中获取。未在 base-config 中设置的值将使用平台默认值。

例如，到 example.com 的子域的所有连接都必须使用自定义 CA 集。此外，允许使用这些域的明文通信，连接到 secure.example.com 时除外。通过在 example.com 的配置中嵌套 secure.example.com 的配置，不需要重复 trust-anchors。

res/xml/network_security_config.xml：

1. <?xml version="1.0" encoding="utf-8"?> 
2. <network-security-config> 
3.     <domain-config> 
4.         <domain includeSubdomains="true">example.com</domain> 
5.         <trust-anchors> 
6.             <certificates src="@raw/my_ca"/> 
7.         </trust-anchors> 
8.         <domain-config cleartextTrafficPermitted="false"> 
9.             <domain includeSubdomains="true">secure.example.com</domain> 
10.         </domain-config> 
11.     </domain-config> 
12. </network-security-config>  

配置文件格式

网络安全性配置特性使用 XML 文件格式。文件的整体结构如以下代码示例所示：

1. <?xml version="1.0" encoding="utf-8"?> 
2. <network-security-config> 
3.     <base-config> 
4.         <trust-anchors> 
5.             <certificates src="..."/> 
6.             ... 
7.         </trust-anchors> 
8.     </base-config> 
9.  
10.     <domain-config> 
11.         <domain>android.com</domain> 
12.         ... 
13.         <trust-anchors> 
14.             <certificates src="..."/> 
15.             ... 
16.         </trust-anchors> 
17.         <pin-set> 
18.             <pin digest="...">...</pin> 
19.             ... 
20.         </pin-set> 
21.     </domain-config> 
22.     ... 
23.     <debug-overrides> 
24.         <trust-anchors> 
25.             <certificates src="..."/> 
26.             ... 
27.         </trust-anchors> 
28.     </debug-overrides> 
29. </network-security-config>  

以下部分将介绍语法与文件格式的其他详细信息。

<network-security-config>

• 可以包含：
• 0 或 1 个 <base-config>
  • 任意数量的 <domain-config>
  • 0 或 1 个 <debug-overrides>

<base-config>

• 语法：

1. <base-config cleartextTrafficPermitted=["true" | "false"]> 
2.     ... 
3. </base-config>  

• 可以包含：

<trust-anchors>

• 说明：

目的地不在 domain-config 涵盖范围内的所有连接所使用的默认配置。未设置的任何值均使用平台默认值。面向 Android 7.0(API 级别 24)及更高版本应用的默认配置如下所示：

1. <base-config cleartextTrafficPermitted="true"> 
2.     <trust-anchors> 
3.         <certificates src="system" /> 
4.     </trust-anchors> 
5. </base-config>  

面向 Android 6.0(API 级别 23)及更低版本应用的默认配置如下所示：

1. <base-config cleartextTrafficPermitted="true"> 
2.     <trust-anchors> 
3.         <certificates src="system" /> 
4.         <certificates src="user" /> 
5.     </trust-anchors> 
6. </base-config>  

<domain-config>

• 语法：

1. <domain-config cleartextTrafficPermitted=["true" | "false"]> 
2.  
3. ... 
4.  
5. </domain-config>  

• 可以包含：
  • 1 个或多个 <domain>
  • 0 或 1 个 <trust-anchors>
  • 0 或 1 个 <pin-set>
• 任意数量的已嵌套 <domain-config>
• 说明

用于按照 domain 元素的定义连接到特定目的地的配置。请注意，如果有多个 domain-config 元素涵盖某个目的地，将使用匹配域规则最具体(最长)的配置。

<domain>

• 语法：

1. <domain includeSubdomains=["true" | "false"]>example.com</domain> 

• 属性：
  • includeSubdomains
  • 如果为 "true"，此域规则将与域及所有子域(包括子域的子域)匹配。否则，该规则仅适用于精确匹配项。
• 说明：

<debug-overrides>

• 语法：

1. <debug-overrides> 
2.  
3. ... 
4.  
5. </debug-overrides>  

• 可以包含：
  • 0 或 1 个 <trust-anchors>
• 说明：

在 android:debuggable 为 "true" 时将应用的重写，IDE 和构建工具生成的非发布版本通常属于此情况。在 debug-overrides 中指定的信任锚将添加到所有其他配置，并且当服务器的证书链使用其中一个仅调试信任锚时，将不执行证书固定。如果 android:debuggable 为 "false"，将完全忽略此部分。

<trust-anchors>

• 语法：

1. <trust-anchors> 
2.  
3. ... 
4.  
5. </trust-anchors>  

• 可以包含：

任意数量的 <certificates>

• 说明：

用于安全连接的信任锚集。

<certificates>

• 语法：

1. <certificates src=["system" | "user" | "raw resource"] 
2.  
3. overridePins=["true" | "false"] />  

• 说明：

用于 trust-anchors 元素的 X.509 证书集。

• 属性：
  • src
  • CA 证书的来源。每个证书可为下列状态之一：
    • 指向包含 X.509 证书的文件的原始资源 ID。证书必须以 DER 或 PEM 格式编码。如果为 PEM 证书，则文件不得包含额外的非 PEM 数据，例如注释。
    • 用于预装系统 CA 证书的 "system"
    • 用于用户添加的 CA 证书的 "user"
  • overridePins
  • 指定此来源的 CA 是否绕过证书固定。如果为 "true"，则不对此来源的 CA 签署的证书链执行证书固定。这对于调试 CA 或测试对应用的安全流量进行中间人攻击 (MiTM) 非常有用。默认值为 "false"，除非在 debug-overrides 元素中另外指定(在这种情况下，默认值为 "true")。

<pin-set>

• 语法：

1. <pin-set expiration="date"> 
2.  
3. ... 
4.  
5. </pin-set>  

• 可以包含：

任意数量的 <pin>

• 说明：

一组公钥固定。对于要信任的安全连接，信任链中必须有一个公钥位于固定集中。有关固定格式，请参阅 <pin>。

• 属性：
  • expiration
  • 采用 yyyy-MM-dd 格式的日期，固定在该日期过期，因而将停用固定。如果未设置该属性，则固定不会过期。设置到期时间有助于防止未更新到其固定集(例如，在用户停用应用更新时)的应用出现连接问题。

<pin>

• 语法：

1. <pin digest=["SHA-256"]>base64 encoded digest of X.509 
2.  
3. SubjectPublicKeyInfo (SPKI)</pin>  

• 属性：
  • digest
  • 用于生成固定的摘要算法。目前仅支持 "SHA-256"。