- Android N includes a Network Security Configuration - feature that 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: + 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:
<?xml version="1.0" encoding="utf-8"?> <manifest ... > - <application android:networkSecurityConfig="@xml/network_security_config" - ... > - ... - </application> + <application android:networkSecurityConfig="@xml/network_security_config" + ... > + ... + </application> </manifest>@@ -87,12 +87,12 @@ page.image=images/cards/card-nyc_2x.jpg
- By default secure (e.g. TLS, HTTPS) connections from all apps trust - the pre-installed system CAs, and apps targeting API level 23 - (Android M) and below also trust the user-added CA store by default. An - app can customize its own connections using {@code base-config} (for - app-wide customization) or {@code domain-config} (for per-domain - customization). + 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 {@code base-config} (for app-wide + customization) or {@code domain-config} (for per-domain customization).
@@ -147,8 +146,8 @@ page.image=images/cards/card-nyc_2x.jpg- The config to limit the set of trusted CAs is similar to trusting a custom CA for a specific domain except + 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.
@@ -207,14 +206,14 @@ elements instead of one.- When debugging an app that connects over HTTPS you may want to + 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 that - are only trusted when only when android:debuggable - is {@code true} by using {@code debug-overrides}. Normally IDEs and build + is {@code true}, by using {@code debug-overrides}. Normally, IDEs and build tools set this flag automatically for non-release builds.
@@ -243,7 +242,7 @@ android:debuggableApplications intending to connect to destinations using only secure - connections can opt-out of supporting cleartext (using unencrypted HTTP + 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. @@ -273,29 +272,30 @@ android:debuggable
- Normally an app trusts all preinstalled CAs. If any of these CAs were - to issue a fradulent certificate the app would be at risk from a MiTM - 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. + Normally, an app trusts all pre-installed CAs. If any of these CAs were to + issue a fradulent 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.
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 only valid if the certificate chain contains at least one of
- the pinned public keys.
+ 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.
- 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 + 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 to push out + app's connectivity is unaffected. Otherwise, you must push out an update to the app to restore connectivity.
- Additionally it is possible to set an expiration time for pins after which + 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. @@ -322,24 +322,24 @@ android:debuggable
- Values not set in a specific config are inherited. This behavior allows more - complex configurations while keeping the configuration file readable. + 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 value from the next more - general entry is used. Values not set in a {@code domain-config} is - taken from the parent {@code domain-config}, if nested, or from the {@code - base-config} if not. Values not set in the {@code base-config} uses the + 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 {@code domain-config} + are taken from the parent {@code domain-config}, if nested, or from the {@code + base-config} if not. Values not set in the {@code base-config} use the platform default values.
- For example consider, where all connections to subdomains of {@code - example.com} must use a custom set of CAs. Additonally cleartext traffic to + For example, consider where all connections to subdomains of {@code + example.com} must use a custom set of CAs. Additonally, cleartext traffic to these domains is permitted except when connecting to {@code secure.example.com}. By nesting the configuration for {@code - secure.example.com} inside the configuration for {@code example.com} the + secure.example.com} inside the configuration for {@code example.com}, the {@code trust-anchors} does not need to be duplicated.
@@ -458,7 +458,8 @@ android:debuggableAny values that are not set use the platform default values. The default - configuration for apps targeting above API level 24 and above: + configuration for apps targeting Android 7.0 (API level 24) and higher is as + follows:
@@ -468,7 +469,8 @@ android:debuggable
</trust-anchors>
</base-config>
-The default configuration for apps targeting API level 23 and below is:
+The default configuration for apps targeting Android 6.0 (API level 23) and
+lower is as follows:
<base-config cleartextTrafficPermitted="true">
<trust-anchors>
@@ -499,13 +501,14 @@ The default configuration for apps targeting API level 23 and below is:
Any number of nested <domain-config>
Note that if multiple {@code domain-config} elements cover a destination the config with the most specific (longest) -matching domain rule is used.
Note that if multiple {@code domain-config} elements cover a destination, the +configuration with the most specific (longest) matching domain rule is +used.
Specifies if the CAs from this source bypass certificate pinning. If {@code - "true"} then certificate chains which chain through one of the CAs from this - source then pinning is not be performed. This can be useful for debug CAs - or to support letting the user MiTM your app's secure traffic. + "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.
@@ -705,13 +708,12 @@ The source of CA certificates, can be one of
- Expiration helps prevent connectivity issues in apps which do - not get updates to their pin set, for example because the user - disabled app updates. + Expiration helps prevent connectivity issues in apps which do not get + updates to their pin set, such as when the user disables app updates.