docs: Migrated "Network Security Configuration" page on DAC (N OTA).

This page now resides with other pages discussing Android security
topics.

Bug: 27502850
Change-Id: I8ce3412198527a947e47e421b94c3d15cce6ec48

docs/html/_redirects.yaml

@@ -1206,3 +1206,5 @@ redirects:
 
 - from: /preview/features/key-attestation.html
   to: /training/articles/security-key-attestation.html
+- from: /preview/features/security-config.html
+  to: /training/articles/security-config.html

docs/html/training/_book.yaml

@@ -1363,6 +1363,11 @@ toc:
     path_attributes:
     - name: description
       value: How to ensure that your app is secure when performing network transactions.
+  - title: Network Security Configuration
+    path: /training/articles/security-config.html
+    path_attributes:
+    - name: description
+      value: Customize the behavior of your app's secure network connections safely.
   - title: Updating Your Security Provider to Protect Against SSL Exploits
     path: /training/articles/security-gms-provider.html
     path_attributes:

docs/html/training/articles/security-config.jd

@@ -1,11 +1,12 @@
 page.title=Network Security Configuration
-page.keywords=androidn,security,network
+page.keywords=security,network,config
+page.metaDescription=Feature that allows app developers to customize network security settings in a safe configuration file.
 page.image=images/cards/card-nyc_2x.jpg
 
 @jd:body
 
-<div id="qv-wrapper">
+<div id="tb-wrapper">
-<div id="qv">
+<div id="tb">
 
 <h2>In this document</h2>
 <ol>
@@ -28,11 +29,10 @@ page.image=images/cards/card-nyc_2x.jpg
 
 
 <p>
-  Android N includes a Network Security Configuration
+  The Network Security Configuration feature lets apps customize their network
-  feature that lets apps customize their network security settings in a safe,
+  security settings in a safe, declarative configuration file without modifying
-  declarative configuration file without modifying app code. These settings can
+  app code. These settings can be configured for specific domains and for a
-  be configured for specific domains and for a specific app. The key
+  specific app. The key capabilities of this feature are as follows:
-  capabilities of this feature are as follows:
 </p>
 
 <ul>
@@ -49,7 +49,7 @@ page.image=images/cards/card-nyc_2x.jpg
   </li>
 
   <li>
-    <b>Cleartext traffic opt-out:</b> Protect apps from from
+    <b>Cleartext traffic opt-out:</b> Protect apps from
     accidental usage of cleartext traffic.
   </li>
 
@@ -87,12 +87,12 @@ page.image=images/cards/card-nyc_2x.jpg
 </p>
 
 <ul>
-  <li>Connecting to a host with a custom certificate authority(self-signed,
+  <li>Connecting to a host with a custom certificate authority, such as a
-  issued by an internal corporate CA, etc).
+  CA that is self-signed or is issued internally within a company.
   </li>
 
   <li>Limiting the set of CAs to only the CAs you trust instead of every
-  preinstalled CA.
+  pre-installed CA.
   </li>
 
   <li>Trusting additional CAs not included in the system.
@@ -100,12 +100,11 @@ page.image=images/cards/card-nyc_2x.jpg
 </ul>
 
 <p>
-  By default secure (e.g. TLS, HTTPS) connections from all apps trust
+  By default, secure connections (using protocols like TLS and HTTPS) from all
-  the pre-installed system CAs, and apps targeting API level 23
+  apps trust the pre-installed system CAs, and apps targeting Android 6.0 (API
-  (Android M) and below also trust the user-added CA store by default. An
+  level 23) and lower also trust the user-added CA store by default. An app can
-  app can customize its own connections using {@code base-config} (for
+  customize its own connections using {@code base-config} (for app-wide
-  app-wide customization) or {@code domain-config} (for per-domain
+  customization) or {@code domain-config} (for per-domain customization).
-  customization).
 </p>
 
 
@@ -147,8 +146,8 @@ page.image=images/cards/card-nyc_2x.jpg
 </p>
 
 <p>
-  The config to limit the set of trusted CAs is similar to <a href=
+  The configuration to limit the set of trusted CAs is similar to <a href=
-  "#TrustingACustomCa">trusting a custom CA</a> for a specific domain except
+  "#ConfigCustom">trusting a custom CA</a> for a specific domain except
   that multiple CAs are provided in the resource.
 </p>
 
@@ -207,14 +206,14 @@ elements instead of one.
 <h2 id="TrustingDebugCa">Configuring CAs for Debugging</h2>
 
 <p>
-  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
+  modification to your app's code, you can specify debug-only CAs, which
-  are <i>only</i> trusted when <a href=
+  are trusted <i>only</i> when <a href=
   "{@docRoot}guide/topics/manifest/application-element.html#debug">
 android:debuggable</a>
-  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.
 </p>
 
@@ -243,7 +242,7 @@ android:debuggable</a>
 
 <p>
   Applications 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</a>
 <h2 id="CertificatePinning">Pinning Certificates</h2>
 
 <p>
-  Normally an app trusts all preinstalled CAs. If any of these CAs were
+  Normally, an app trusts all pre-installed CAs. If any of these CAs were to
-  to issue a fradulent certificate the app would be at risk from a MiTM
+  issue a fradulent certificate, the app would be at risk from a
-  attack. Some apps choose to limit the set of certificates they accept
+  man-in-the-middle attack. Some apps choose to limit the set of certificates
-  by either limiting the set of CAs they trust or by certificate pinning.
+  they accept by either limiting the set of CAs they trust or by certificate
+  pinning.
 </p>
 
 <p>
   Certificate pinning is done by providing a set of certificates by hash of the
-  public key (SubjectPublicKeyInfo of the X.509 certificate). A certificate
+  public key (<code>SubjectPublicKeyInfo</code> of the X.509 certificate). A
-  chain is then only valid if the certificate chain contains at least one of
+  certificate chain is then valid only if the certificate chain contains at
-  the pinned public keys.
+  least one of the pinned public keys.
 </p>
 
 <p>
-  Note that when using certificate pinning you should always include a backup
+  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
+  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.
 </p>
 
 <p>
-  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</a>
 <h2 id="ConfigInheritance">Configuration Inheritance Behavior</h2>
 
 <p>
-  Values not set in a specific config are inherited. This behavior allows more
+  Values not set in a specific configuration are inherited. This behavior allows
-  complex configurations while keeping the configuration file readable.
+  more complex configurations while keeping the configuration file readable.
 </p>
 
 <p>
-  If a value is not set in a specific entry then value from the next more
+  If a value is not set in a specific entry, then the value from the more
-  general entry is used. Values not set in a {@code domain-config} is
+  general entry is used. For example, values not set in a {@code domain-config}
-  taken from the parent {@code domain-config}, if nested, or from the {@code
+  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} uses the
+  base-config} if not. Values not set in the {@code base-config} use the
   platform default values.
 </p>
 
 <p>
-  For example consider, where all connections to subdomains of {@code
+  For example, consider where all connections to subdomains of {@code
-  example.com} must use a custom set of CAs. Additonally cleartext traffic to
+  example.com} must use a custom set of CAs. Additonally, cleartext traffic to
   these domains is permitted <em>except</em> 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.
 </p>
 
@@ -458,7 +458,8 @@ android:debuggable</a>
 
 <p>
   Any 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:
 </p>
 
 <pre>
@@ -468,7 +469,8 @@ android:debuggable</a>
     &lt;/trust-anchors&gt;
 &lt;/base-config&gt;
 </pre>
-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:
 <pre>
 &lt;base-config cleartextTrafficPermitted="true"&gt;
     &lt;trust-anchors&gt;
@@ -499,13 +501,14 @@ The default configuration for apps targeting API level 23 and below is:
 <br/>Any number of nested <code>&lt;domain-config&gt;</code></dd>
 
 <dt>Description</dt>
-<dd>Configuration used for connections to specific destinations as the defined by {@code domain} elements.
+<dd>Configuration used for connections to specific destinations, as defined by
+the {@code domain} elements.
 
-<p>Note that if multiple {@code domain-config} elements cover a destination the config with the most specific (longest)
+<p>Note that if multiple {@code domain-config} elements cover a destination, the
-matching domain rule is used.</p></dd>
+configuration with the most specific (longest) matching domain rule is
+used.</p></dd>
 </dl>
 
-
 <h3 id="domain">&lt;domain&gt;</h3>
 
 <dl class="xml">
@@ -530,8 +533,8 @@ matching domain rule is used.</p></dd>
       </dt>
 
       <dd>
-        If {@code "true"} then this domain rule matches the domain and all
+        If {@code "true"}, then this domain rule matches the domain and all
-        subdomains, including subdomains of subdomains, otherwise the rule only
+        subdomains, including subdomains of subdomains. Otherwise, the rule only
         applies to exact matches.
       </dd>
     </dl>
@@ -572,13 +575,13 @@ matching domain rule is used.</p></dd>
   <dd>
     Overrides to be applied when <a href=
     "{@docRoot}guide/topics/manifest/application-element.html#debug">android:debuggable</a>
-    is {@code "true"} which is normally the case for non-release builds
+    is {@code "true"}, which is normally the case for non-release builds
     generated by IDEs and build tools. Trust anchors specified in {@code
-    debug-overrides} are added to all other configurations and certificate
+    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 <a href=
     "{@docRoot}guide/topics/manifest/application-element.html#debug">android:debuggable</a>
-    is {@code "false"} then this section is completely ignored.
+    is {@code "false"}, then this section is completely ignored.
   </dd>
 </dl>
 
@@ -627,11 +630,11 @@ matching domain rule is used.</p></dd>
 <dd><dl class="attr">
 <dt>{@code src}</dt>
 <dd>
-The source of CA certificates, can be one of
+The source of CA certificates. Each certificate can be one of the following:
 <ul>
-  <li>a raw resource id pointing to a file containing X.509 certificates.
+  <li>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 <em>must not</em> contain extra non-PEM data such as
+  certificates, the file <em>must not</em> contain extra non-PEM data such as
   comments.
   </li>
 
@@ -647,9 +650,9 @@ The source of CA certificates, can be one of
 <dd>
   <p>
     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
+    "true"}, then pinning is not performed on certificate chains which are
-    source then pinning is not be performed. This can be useful for debug CAs
+    signed by one of the CAs from this source. This can be useful for debugging
-    or to support letting the user MiTM your app's secure traffic.
+    CAs or for testing man-in-the-middle attacks on your app's secure traffic.
   </p>
 
   <p>
@@ -705,13 +708,12 @@ The source of CA certificates, can be one of
       </dt>
 
       <dd>
-        The date, in {@code yyyy-MM-dd} format, at and after which the pins
+        The date, in {@code yyyy-MM-dd} format, on which the pins expire, thus
-        expire, thus disabling pinning. If the attribute is not set then the
+        disabling pinning. If the attribute is not set, then the pins do not
-        pins do not expire.
+        expire.
         <p>
-          Expiration helps prevent connectivity issues in apps which do
+          Expiration helps prevent connectivity issues in apps which do not get
-          not get updates to their pin set, for example because the user
+          updates to their pin set, such as when the user disables app updates.
-          disabled app updates.
         </p>
       </dd>
     </dl>
@@ -742,7 +744,7 @@ The source of CA certificates, can be one of
       </dt>
 
       <dd>
-        The digest algorithm used to generate the pin. Currently only
+        The digest algorithm used to generate the pin. Currently, only
         {@code "SHA-256"} is supported.
       </dd>
     </dl>