网络安全配置

网络安全配置功能使您可以安全地、声明式地在配置文件中自定义应用的网络安全设置，而无需修改应用代码。这些设置可以为特定域和特定应用进行配置。此功能的关键能力包括：

  • 自定义信任锚：自定义哪些证书颁发机构 (CA) 受信任用于应用的安全连接。例如，信任特定的自签名证书或限制应用信任的公共 CA 集。
  • 仅限调试的覆盖：安全地调试应用中的安全连接，而不会增加已安装基础的风险。
  • 明文流量选择退出：保护应用免受意外使用明文（未加密）流量的影响。
  • 证书固定：将应用的安全连接限制为特定证书。

添加网络安全配置文件

网络安全配置功能使用 XML 文件来指定应用的设置。您必须在应用的清单中包含一个条目来指向此文件。清单中的以下代码片段演示了如何创建此条目：

<?xml version="1.0" encoding="utf-8"?>
<manifest ... >
    <application android:networkSecurityConfig="@xml/network_security_config"
                    ... >
        ...
    </application>
</manifest>

自定义受信任的 CA

您可能希望您的应用信任一组自定义的 CA，而不是平台默认的 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中为自定义 CA 配置您的应用：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

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

限制受信任的 CA 集

如果您不希望您的应用信任系统信任的所有 CA，则可以指定要信任的减少的 CA 集。这可以保护应用免受任何其他 CA 颁发的欺诈性证书的影响。

限制受信任的 CA 集的配置类似于信任特定域的自定义 CA，只是在资源中提供了多个 CA。以下代码片段演示了如何在res/xml/network_security_config.xml中限制应用的受信任的 CA 集：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">secure.example.com</domain>
        <domain includeSubdomains="true">cdn.example.com</domain>
        <trust-anchors>
            <certificates src="@raw/trusted_roots"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

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

信任其他 CA

您可能希望您的应用信任系统不信任的其他 CA，例如，如果系统尚未包含 CA 或 CA 不符合包含在 Android 系统中的要求。您可以使用类似以下代码片段的代码在res/xml/network_security_config.xml中为配置指定多个证书来源。

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <trust-anchors>
            <certificates src="@raw/extracas"/>
            <certificates src="system"/>
        </trust-anchors>
    </base-config>
</network-security-config>

配置用于调试的 CA

在调试连接到HTTPS的应用程序时，您可能需要连接到本地开发服务器，该服务器没有生产服务器的SSL证书。为了在不修改应用程序代码的情况下支持这一点，您可以使用debug-overrides指定仅限调试的CA，这些CA仅在android:debuggable为true时才受信任。

这比通常的条件代码更安全，因为作为一项安全预防措施，应用商店不接受标记为可调试的应用程序。

以下摘录显示了如何在res/xml/network_security_config.xml中指定仅限调试的CA。

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <debug-overrides>
        <trust-anchors>
            <certificates src="@raw/debug_cas"/>
        </trust-anchors>
    </debug-overrides>
</network-security-config>

禁用明文流量

注意：本节中的指导仅适用于面向Android 8.1（API级别27）或更低版本的应用程序。从Android 9（API级别28）开始，默认情况下禁用明文支持。

如果您希望您的应用程序仅使用安全连接连接到目标，您可以选择不使用明文（使用未加密的HTTP协议而不是HTTPS）连接到这些目标。此选项有助于防止由于外部来源（例如后端服务器）提供的URL更改而导致的应用程序意外回归。有关更多详细信息，请参阅NetworkSecurityPolicy.isCleartextTrafficPermitted()。

例如，您可能希望您的应用程序确保始终通过HTTPS连接到secure.example.com，以保护敏感流量免受恶意网络的攻击。

以下摘录显示了如何在res/xml/network_security_config.xml中禁用明文流量。

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

证书固定

通常，应用程序信任所有预安装的CA。如果这些CA中的任何一个签发欺诈证书，则应用程序将面临路径攻击的风险。某些应用程序选择通过限制其信任的CA集或通过证书固定来限制其接受的证书集。

证书固定是通过提供一组公钥哈希的证书来完成的（X.509证书的SubjectPublicKeyInfo）。只有当证书链包含至少一个固定的公钥时，证书链才有效。

请注意，当使用证书固定时，您应始终包含一个备用密钥，以便如果被迫切换到新密钥或更改CA（当固定到CA证书或该CA的中间证书时），您的应用程序的连接不会受到影响。否则，您必须推送应用程序更新以恢复连接。

此外，可以为固定设置一个过期时间，在此时间之后不执行固定。这有助于防止未更新的应用程序出现连接问题。但是，为固定设置过期时间可能会使攻击者绕过您固定的证书。

以下摘录显示了如何在res/xml/network_security_config.xml中固定证书。

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

配置继承行为

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

例如，如果嵌套，则未在domain-config中设置的值将从父domain-config获取，否则将从base-config获取。未在base-config中设置的值使用平台默认值。

例如，考虑所有连接到example.com的子域都必须使用自定义CA集的情况。此外，允许对这些域进行明文流量，*除非*连接到secure.example.com。通过将secure.example.com的配置嵌套到example.com的配置中，无需重复trust-anchors。

以下摘录显示了此嵌套在res/xml/network_security_config.xml中的外观。

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
        <domain-config cleartextTrafficPermitted="false">
            <domain includeSubdomains="true">secure.example.com</domain>
        </domain-config>
    </domain-config>
</network-security-config>

配置文件格式

网络安全配置功能使用XML文件格式。文件的整体结构如下面的代码示例所示。

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <trust-anchors>
            <certificates src="..."/>
            ...
        </trust-anchors>
    </base-config>

    <domain-config>
        <domain>android.com</domain>
        ...
        <trust-anchors>
            <certificates src="..."/>
            ...
        </trust-anchors>
        <pin-set>
            <pin digest="...">...</pin>
            ...
        </pin-set>
    </domain-config>
    ...
    <debug-overrides>
        <trust-anchors>
            <certificates src="..."/>
            ...
        </trust-anchors>
    </debug-overrides>
</network-security-config>

以下部分描述了文件的语法和其他细节。

<network-security-config>

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

<base-config>

语法
<base-config cleartextTrafficPermitted=["true" | "false"]>
    ...
</base-config>
可以包含
<trust-anchors>
描述
所有连接使用的默认配置，其目标未被domain-config涵盖。

所有未设置的值都使用平台默认值。

面向 Android 9（API 级别 28）及更高版本的应用的默认配置如下所示

<base-config cleartextTrafficPermitted="false">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

面向 Android 7.0（API 级别 24）到 Android 8.1（API 级别 27）的应用的默认配置如下所示

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

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

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
        <certificates src="user" />
    </trust-anchors>
</base-config>

<domain-config>

语法
<domain-config cleartextTrafficPermitted=["true" | "false"]>
    ...
</domain-config>
可以包含
1 个或多个<domain>
0 个或 1 个<trust-anchors>
0 个或 1 个<pin-set>
任意数量的嵌套<domain-config>
描述
用于连接到特定目标的配置，由domain元素定义。

请注意，如果多个domain-config元素涵盖一个目标，则将使用具有最具体（最长）匹配域规则的配置。

<domain>

语法
<domain includeSubdomains=["true" | "false"]>example.com</domain>
属性
includeSubdomains
如果为"true"，则此域规则匹配该域及其所有子域，包括子域的子域。否则，该规则仅适用于完全匹配。

<debug-overrides>

语法
<debug-overrides>
    ...
</debug-overrides>
可以包含
0 个或 1 个<trust-anchors>
描述
当android:debuggable为"true"时应用的覆盖，这通常是IDE和构建工具生成的非发布版本的情况。在debug-overrides中指定的信任锚点将添加到所有其他配置中，并且当服务器的证书链使用这些仅限调试的信任锚点之一时，不会执行证书固定。如果android:debuggable为"false"，则完全忽略此部分。

<trust-anchors>

语法
<trust-anchors>
...
</trust-anchors>
可以包含
任意数量的<certificates>
描述
安全连接的信任锚点集。

<certificates>

语法
<certificates src=["system" | "user" | "raw resource"]
              overridePins=["true" | "false"] />
描述
trust-anchors元素的X.509证书集。
属性
src
CA证书的来源。每个证书可以是以下之一：
  • 指向包含X.509证书的文件的原始资源ID。证书必须以DER或PEM格式编码。对于PEM证书，文件*不能*包含额外的非PEM数据，例如注释。
  • "system" 表示预安装的系统CA证书
  • "user" 表示用户添加的CA证书
overridePins

指定此来源的CA是否绕过证书固定。如果为"true"，则不会对由此来源的CA之一签名的证书链执行固定。这对于调试CA或测试对应用程序安全流量的中间人攻击很有用。

默认为"false"，除非在debug-overrides元素中指定，在这种情况下，默认为"true"。

<pin-set>

语法
<pin-set expiration="date">
...
</pin-set>
可以包含
任意数量的<pin>
描述
一组公钥固定。为了使安全连接受信任，信任链中的一个公钥必须位于固定集内。有关固定的格式，请参阅<pin>。
属性
expiration
以yyyy-MM-dd格式表示固定的过期日期，从而禁用固定。如果未设置该属性，则固定不会过期。

过期有助于防止未更新其固定集的应用程序出现连接问题，例如当用户禁用应用程序更新时。

<pin>

语法
<pin digest=["SHA-256"]>base64 encoded digest of X.509
    SubjectPublicKeyInfo (SPKI)</pin>
属性
digest
用于生成固定的摘要算法。目前，仅支持"SHA-256"。

其他资源

有关网络安全配置的更多信息，请咨询以下资源。

Codelabs