The Network Security Configuration feature lets apps customize their network security settings in a safe, declarative configuration file without modifying app code. These settings can be configured for specific domains and for a specific app. The key capabilities of this feature are as follows:
网络安全配置的特性允许应用以安全的陈述文件自定义网络安全设置，不需要修改应用代码。这些设置可以用来配置特定的领域和特定的应用。这个特性的主要功能如下：
-
Custom trust anchors: Customize which Certificate Authorities (CA) are trusted for an app's secure connections. For example, trusting particular self-signed certificates or restricting the set of public CAs that the app trusts.
自定义信任锚：自定义应用安全连接的授信证书颁发机构。例如，信任指定的自签名证书 或 限制应用信任的公共证书集。 -
Debug-only overrides: Safely debug secure connections in an app without added risk to the installed base.
仅调试替换：无需在已安装的部分增加风险，在应用内安全地调试安全连接。 -
Cleartext traffic opt-out: Protect apps from accidental usage of cleartext traffic.
停用明文传输：保护应用免于意外的明文传输。 -
Certificate pinning: Restrict an app's secure connection to particular certificates.
证书固定：限制应用仅安全连接到制定证书。
Add a Network Security Configuration file
添加一个网络安全配置文件
The Network Security Configuration feature uses an XML file where you specify the settings for your app. You must include an entry in the manifest of your app to point to this file. The following code excerpt from a manifest demonstrates how to create this entry:
网络安全配置功能使用一个xml文件来配置应用。你必须在应用的清单文件中包含一个指向该文件的条目。下面的代码摘录于一个清单文件示范了怎样新建这个条目：
<?xml version="1.0" encoding="utf-8"?>
<manifest ... >
<application android:networkSecurityConfig="@xml/network_security_config"
... >
...
</application>
</manifest>
Customize trusted CAs
An app may want to trust a custom set of CAs instead of the platform default. The most common reasons of this are:
应用可能希望信任自定义的证书集合，而不是平台默认。以下是最常见的原因：
-
Connecting to a host with a custom certificate authority, such as a CA that is self-signed or is issued internally within a company.
连接到一台自定义证书的主机，比如自签名的证书或者在公司内部签发的证书。 -
Limiting the set of CAs to only the CAs you trust instead of every pre-installed CA.
限制证书集合为只允许你新人的证书，而不是每一个预装的证书。 -
Trusting additional CAs not included in the system.
信任不在系统内的其他证书。
By default, secure connections (using protocols like TLS and HTTPS) from all apps trust the pre-installed system CAs, and apps targeting Android 6.0 (API level 23) and lower also trust the user-added CA store by default. An app can customize its own connections using base-config (for app-wide customization) or domain-config (for per-domain customization).
默认情况下，来自所有应用的安全连接(使用TLS和HTTPS协议)信任系统预装的证书。而且，适配Android6.0及以下系统的应用也会默认地信任用户添加的证书存储区。应用可以通过'base-config'(应用范围的自定义)或'domain-config'(区域范围的自定义)来自定义自己的连接。
Configure a custom CA
配置一个自定义的证书
Assume you want to connect to your host which uses a self-signed SSL certificate or to a host whose SSL certificate is issued by a non-public CA which you trust, such as your company's internal CA.
假设你想要连接到使用了自签名SSL证书的主机，或者连接到一个配置了非公开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>
<trust-anchors>
<certificates src="@raw/my_ca"/>
</trust-anchors>
</domain-config>
</network-security-config>
Add the self-signed or non-public CA certificate, in PEM or DER format, to res/raw/my_ca.
添加自签名或者非公共CA证书到res/ras/my_ca，使用PEM或DER格式。
Limit the set of trusted CAs
限制信任的CA集合
An app that does not want to trust all CAs trusted by system can instead specify its own reduced set of CAs to trust. This protects the app from fraudulent certificates issued by any of the other CAs.
如果应用不想信任所有被系统信任的证书，作为替代，应用可以指定自己的简化版的证书集合。这样可以保护应用远离任何其他CA颁发的欺骗性的证书。
The configuration to limit the set of trusted CAs is similar to trusting a custom CA for a specific domain except that multiple CAs are provided in the resource.
对于限制受信任CA的配置与针对特定网域信任自定义的CA类似，除了前者会在资源中提供多个CA。
res/xml/network_security_config.xml:
<?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>
Add the trusted CAs, in PEM or DER format, to res/raw/trusted_roots. Note that if using PEM format the file must contain only PEM data and no extra text. You can also provide multiple <certificates>elements instead of one.
以PEM或DER的格式添加受信任的CA到res/raw/trusted_roots。注意一点：如果使用了PEM格式，那么该文件必须只能包含PEM的数据，且没有额外的文本。您也可以提供多个证书元素而不是一个。
Trust additional CAs
信任其他CA
An app may want to trust additional CAs not trusted by the system, this could be due to the system not yet including the CA or a CA that does not meet the requirements for inclusion into the Android system. An app can do this by specifying multiple certificate sources for a configuration.
应用可能希望信任其他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>
Configure CAs for debugging
配置用于调试的CA
When debugging an app that connects over HTTPS, you may want to connect to a local development server, which does not have the SSL certificate for your production server. In order to support this without any modification to your app's code, you can specify debug-only CAs, which are trusted onlywhen android:debuggable is true, by using debug-overrides. Normally, IDEs and build tools set this flag automatically for non-release builds.
当调试通过HTTPS连接的应用时，您可能希望连接到一个本地的开发服务器，这台服务器没有配置生产环境的SSL证书。为了在不修改任何应用代码的前提下支持到这一点，您可以指定一个针对debug模式的CA，您可以使用debug-overrides指定android:debuggable为true时信任上述CA。通过，集成开发环境和编译工具会自动地为非发布版本设置此标记。
This is safer than the usual conditional code because, as a security precaution, app stores do not accept apps which are marked debuggable.
这么做比常用的条件判断代码更安全，因为出于安全考虑，应用商店不接受被标记为可调式的应用。
res/xml/network_security_config.xml:
<?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>
Opt out of cleartext traffic
停用明文传输
⭐️ Note: The guidance in this section applies only to apps that target Android 8.1 (API level 27) or lower. Starting with Android 9 (API level 28), cleartext support is disabled by default.
⭐️注意：这个部分的指南仅应用适配Android8.1及更低版本。从Android9开始，明文传输的支持默认被禁止。
Applications intending to connect to destinations using only secure connections can opt-out of supporting cleartext (using the unencrypted HTTP protocol instead of HTTPS) to those destinations. This option helps prevent accidental regressions in apps due to changes in URLs provided by external sources such as backend servers. See NetworkSecurityPolicy.isCleartextTrafficPermitted() for more details.
打算只使用安全连接的应用程序可以不支持这些目的地的明文传输(使用了未加密的HTTP协议而不是HTTPS)。这个选项可以协助防止应用由于修改来自外部资源的链接地址(例如后台服务器)而产生意外的错误。
For example, an app may want to ensure that all connections to secure.example.com are always done over HTTPS to protect sensitive traffic from hostile networks.
例如，应用可能想要确保所有与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>
Pin certificates
证书固定
Normally, an app trusts all pre-installed CAs. If any of these CAs were to issue a fraudulent certificate, the app would be at risk from a man-in-the-middle attack. Some apps choose to limit the set of certificates they accept by either limiting the set of CAs they trust or by certificate pinning.
通常，应用信任所有预装的CA。如果这些证书中的任何一个要发型一个有危害的证书，应用将会暴露在中间人攻击的风险下。一些应用选择显示证书的集合来规避该风险：限制CA的集合，或者固定证书。
Certificate pinning is done by providing a set of certificates by hash of the public key (SubjectPublicKeyInfo of the X.509 certificate). A certificate chain is then valid only if the certificate chain contains at least one of the pinned public keys.
证书固定可以这样执行：通过公钥的哈希码来提供一个证书的集合(X.509证书的主要信息)。然后，一个证书链只有在包含至少一个固定的公钥才合法。
Note that, when using certificate pinning, you should always include a backup key so that if you are forced to switch to new keys or change CAs (when pinning to a CA certificate or an intermediate of that CA), your app's connectivity is unaffected. Otherwise, you must push out an update to the app to restore connectivity.
请注意，当使用证书固定这个选项时，您应该一直保有一个备用的密钥，以便您强制切换到新的密钥或更改CA时(在固定到一个CA的证书或者一个中间件CA)，您的应用连接不受影响。否则，您必须推出一个更新版本来恢复连接。
Additionally, it is possible to set an expiration time for pins after which pinning is not performed. This helps prevent connectivity issues in apps which have not been updated. However, setting an expiration time on pins may enable pinning bypass.
另外，还可以设置一个固定不生效的过期时间。这样可以防止未更新应用(旧版本)的一些连接问题。然而，在固定证书中设置过期时间可能会造成绕过证书固定的问题。
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>
Configuration inheritance behavior
配置继承的行为
Values not set in a specific configuration are inherited. This behavior allows more complex configurations while keeping the configuration file readable.
没有被设置到特定配置中的数据会被继承。这个特性允许更加复杂的配置信息，同时保持配置文件的可读性。
If a value is not set in a specific entry, then the value from the more general entry is used. For example, values not set in a domain-config are taken from the parent domain-config, if nested, or from the base-config if not. Values not set in the base-config use the platform default values.
如果一个数据没有被设置到特定的条目，那么该数据将使用来自更加通用条目的值。例如，没有设置domain-config的的数据，将使用父节点的domain-config，在嵌套结构中，如果嵌套结构中没有，也可以从base-config(基本配置)中获取。如果base-config(基本配置)也没有，那么使用平台的默认值。
For example, consider where all connections to subdomains of example.com must use a custom set of CAs. Additonally, cleartext traffic to these domains is permitted except when connecting to secure.example.com. By nesting the configuration for secure.example.com inside the configuration for example.com, the trust-anchors does not need to be duplicated.
例如，考虑到所有与二级域名的连接，必须使用自定义的CA集合。另外，除了与secure.example.com的连接，与这些域名的明文传输也是被允许的。通过在example.com中对secure.example.com嵌套一个配置文件，那些信任信息的配置不需要重复。
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>
Configuration file format
配置文件格式
The Network Security Configuration feature uses an XML file format. The overall structure of the file is shown in the following code sample:
网络安全配置文件使用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>
The following sections describe the syntax and other details of the file format.
下面的部分描述了语法和一些文件格式的细节。
<network-security-config>
can contain:
0 or 1 of <base-config>
Any number of <domain-config>
0 or 1 of <debug-overrides>
<base-config>
syntax:
<base-config cleartextTrafficPermitted=["true" | "false"]>
...
</base-config>
can config:
<trust-anchors>
description:
The default configuration used by all connections whose destination is not covered by a domain-config.
默认配置信息可能被所有未使用domain-config标出目的地的连接使用。
Any values that are not set use the platform default values.
如果没有配置任何信息，则使用平台默认值。
The default configuration for apps targeting Android 9 (API level 28) and higher is as follows:
适配Android9或更好版本的应用默认配置信息如下：
<base-config cleartextTrafficPermitted="false">
<trust-anchors>
<certificates src="system" />
</trust-anchors>
</base-config>
The default configuration for apps targeting Android 7.0 (API level 24) to Android 8.1 (API level 27) is as follows:
适配Android7.0到Android8.0的应用默认配置信息如下：
<base-config cleartextTrafficPermitted="true">
<trust-anchors>
<certificates src="system" />
</trust-anchors>
</base-config>
The default configuration for apps targeting Android 6.0 (API level 23) and lower is as follows:
适配Android6.0及以下版本的应用默认配置信息如下：
<base-config cleartextTrafficPermitted="true">
<trust-anchors>
<certificates src="system" />
<certificates src="user" />
</trust-anchors>
</base-config>
<domain-config>
syntax:
<domain-config cleartextTrafficPermitted=["true" | "false"]>
...
</domain-config>
Can Contain:
1 or more <domain>
0 or 1 <trust-anchors>
0 or 1 <pin-set>
Any number of nested <domain-config>
Description:
Configuration used for connections to specific destinations, as defined by the domain elements.
Note that if multiple domain-config elements cover a destination, the configuration with the most specific (longest) matching domain rule is used.
用来配置特定的目的地地址，由域元素定义。
请注意，如果多个domain-config元素覆盖了同一个目的地址，则使用特定程度最高(最长)的匹配域规则。
<domain>
syntax:
<domain includeSubdomains=["true" | "false"]>example.com</domain>
Attributes:
includeSubdomains
If "true", then this domain rule matches the domain and all subdomains, including subdomains of subdomains. Otherwise, the rule only applies to exact matches.
如果为true, 则这个域规则匹配这个域和所有的子域，包括子域的子域。否则，域规则只匹配特定的域。
<debug-overrides>
syntax:
<debug-overrides>
...
</debug-overrides>
Can Contain:
0 or 1 <trust-anchors>
Description:
Overrides to be applied when android:debuggable is "true", which is normally the case for non-release builds generated by IDEs and build tools. Trust anchors specified in debug-overrides are added to all other configurations, and certificate pinning is not performed when the server's certificate chain uses one of these debug-only trust anchors. If android:debuggable is "false", then this section is completely ignored.
当android:debuggable 为true时，元素被覆盖。常用于集成开发环境或打包工具打包非发布版本的场景。声明在debug-overrides域中的信任锚会添加到所有其他的配置信息中，并且当服务器的证书链使用了仅调试模式的信任锚时，证书固定将不会生效。如果android:debuggable的值为false,那么这个部分将会被完全忽略。
<trust-anchors>
syntax:
<trust-anchors>
...
</trust-anchors>
Can Contain:
Any number of <certificates>
Description:
Set of trust anchors for secure connections.
<certificates>
syntax:
<certificates src=["system" | "user" | "raw resource"]
overridePins=["true" | "false"] />
Description:
Set of X.509 certificates for trust-anchors elements.
Attributes:
-
src
The source of CA certificates. Each certificate can be one of the following:- a raw resource ID pointing to a file containing X.509 certificates. Certificates must be encoded in DER or PEM format. In the case of PEM certificates, the file must not contain extra non-PEM data such as comments.
- "system" for the pre-installed system CA certificates
- "user" for user-added CA certificates
CA证书的源，每个证书可以以下几种之一：
-
一个raw的资源ID指向了一个包含了X.509证书的文件。证书必须使用DER或者PEM格式编码。对于PEM格式的证书，证书文件不能包含非PEM格式的额外数据，如注解等。
-
overridePins
Specifies if the CAs from this source bypass certificate pinning. If "true", then pinning is not performed on certificate chains which are signed by one of the CAs from this source. This can be useful for debugging CAs or for testing man-in-the-middle attacks on your app's secure traffic.
Default is "false" unless specified in a debug-overrides element, in which case the default is "true".
如果CA需要绕过证书固定，那么要指定该条目的值。如果为true，则被来自该资源的一个CA签名的证书链，证书固定不生效。这样可以使用调试的CA，也可以测试应用安全传输时的中间人攻击。如果声明一个debug-overrides元素，那么默认值是true, 否则默认值是false.
<pin-set>
syntax:
<pin-set expiration="date">
...
</pin-set>
Can Contain:
Any number of <pin>
Description:
A set of public key pins. For a secure connection to be trusted, one of the public keys in the chain of trust must be in the set of pins. See <pin> for the format of pins.
证书固定的公钥集合。对于一个受信任的安全连接，链路中的公钥中的一个必须在固定公钥集合中。查看<pin>确定固定的格式。
Attributes:
expiration
The date, in yyyy-MM-dd format, on which the pins expire, thus disabling pinning. If the attribute is not set, then the pins do not expire.
Expiration helps prevent connectivity issues in apps which do not get updates to their pin set, such as when the user disables app updates.
过期标签
可以按照yyyy-MM-dd格式配置过期时间，从而让固定证书不生效。如果这个属性没有被设置，那么固定证书会一直生效。过期的机制可以防止未升级版本应用在连接服务器时产生的问题。例如用户关闭了应用更新。
<pin>
syntax:
<pin digest=["SHA-256"]>base64 encoded digest of X.509
SubjectPublicKeyInfo (SPKI)</pin>
Attributes:
digest:
The digest algorithm used to generate the pin. Currently, only "SHA-256" is supported.
digest(摘要)算法被用来生成固定(pin该怎么翻译？)。现在，只支持"SHA-256"。
Additional resources
For more information about Network Security Configuration, consult the following resources.
网友评论