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

3 files changed, 82 insertions, 73 deletions

diff --git a/docs/html/_redirects.yaml b/docs/html/_redirects.yaml
index 87ae71391c13..2b94718e3450 100644
--- a/docs/html/_redirects.yaml
+++ b/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
\ No newline at end of file
diff --git a/docs/html/training/_book.yaml b/docs/html/training/_book.yaml
index d6561bb79388..0e2083a9df35 100644
--- a/docs/html/training/_book.yaml
+++ b/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:
diff --git a/docs/html/preview/features/security-config.jd b/docs/html/training/articles/security-config.jd
index 2706ced8579b..90a93fa00078 100644
--- a/docs/html/preview/features/security-config.jd
+++ b/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="qv">
+<div id="tb-wrapper">
+<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
-  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:
 </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>
 
@@ -72,10 +72,10 @@ page.image=images/cards/card-nyc_2x.jpg
 <pre>
 &lt;?xml version="1.0" encoding="utf-8"?&gt;
 &lt;manifest ... &gt;
-  &lt;application android:networkSecurityConfig="@xml/network_security_config"
-               ... &gt;
-    ...
-  &lt;/application&gt;
+    &lt;application android:networkSecurityConfig="@xml/network_security_config"
+                    ... &gt;
+        ...
+    &lt;/application&gt;
 &lt;/manifest&gt;
 </pre>
 
@@ -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,
-  issued by an internal corporate CA, etc).
+  <li>Connecting to a host with a custom certificate authority, such as a
+  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
-  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).
 </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=
-  "#TrustingACustomCa">trusting a custom CA</a> for a specific domain except
+  The configuration to limit the set of trusted CAs is similar to <a href=
+  "#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
-  are <i>only</i> trusted when <a href=
+  modification to your app's code, you can specify debug-only CAs, which
+  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
-  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.
 </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
-  chain is then only valid if the certificate chain contains at least one of
-  the pinned public keys.
+  public key (<code>SubjectPublicKeyInfo</code> 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.
 </p>
 
 <p>
-  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.
 </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
-  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.
 </p>
 
 <p>
-  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.
 </p>
 
 <p>
-  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 <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)
-matching domain rule is used.</p></dd>
+<p>Note that if multiple {@code domain-config} elements cover a destination, the
+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
-        subdomains, including subdomains of subdomains, otherwise the rule only
+        If {@code "true"}, then this domain rule matches the domain and all
+        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
-    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.
   </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
-        expire, thus disabling pinning. If the attribute is not set then the
-        pins do not expire.
+        The date, in {@code yyyy-MM-dd} format, on which the pins expire, thus
+        disabling pinning. If the attribute is not set, then the pins do not
+        expire.
         <p>
-          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.
         </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>