网络安全配置

网络安全配置功能允许您在安全的、声明性的配置文件中自定义应用的网络安全设置，而无需修改应用代码。这些设置可以为特定域和特定应用配置。此功能的主要功能包括

  • 自定义信任锚：自定义哪些证书颁发机构 (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。

默认情况下，所有应用的安全连接（使用 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 证书的本地开发服务器。为了在不修改应用代码的情况下支持这一点，您可以指定仅调试 CA，这些 CA 仅在android:debuggable为true时受信任，方法是使用debug-overrides。通常，IDE 和构建工具会自动为非发布版本设置此标志。

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

以下摘录显示了如何在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()。

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

以下摘录显示了如何在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