Merge "docs: removing duplicate security config doc" into nyc-dev
diff --git a/docs/html/guide/topics/security/security-config.jd b/docs/html/guide/topics/security/security-config.jd
deleted file mode 100644
index 4cee253..0000000
--- a/docs/html/guide/topics/security/security-config.jd
+++ /dev/null
@@ -1,539 +0,0 @@
-page.title=Network Security Config
-@jd:body
-
-<div id="qv-wrapper">
-<div id="qv">
-
-<h2>In this document</h2>
-<ol>
-<li><a href="#SupportedFeatures">Features</a></li>
-<li><a href="#Examples">Examples</a>
- <ol>
- <li><a href="#TrustingCustomCas">Trusting Custom CAs</a>
- <ol>
- <li><a href="#TrustingACustomCa">Trusting a Custom CA</a></li>
- <li><a href="#LimitingCas">Limiting the Set of Trusted CAs</a></li>
- <li><a href="#TrustingAdditionalCas">Trusting Additional CAs</a></li>
- </ol>
- </li>
- <li><a href="#TrustingDebugCa">Debugging-only CAs</a></li>
- <li><a href="#UsesCleartextTraffic">Cleartext Traffic Opt-Out</a></li>
- <li><a href="#CertificatePinning">Certificate Pinning</a></li>
- <li><a href="#ConfigInheritance">Configuration Inheritance</a></li>
- </ol>
-</li>
-<li><a href="#FileFormat">Configuration File Format</a></li>
-</ol>
-</div>
-</div>
-
-<p>The Android Network Security Config lets apps customize their network security settings
-in a safe, declarative configuration file without modifying application code.
-These settings can be configured for specific domains and app-wide.</p>
-
-<h2 id="SupportedFeatures">Features</h2>
-<ul>
-<li><b>Custom trust anchors.</b> Lets an application customize which Certificate Authorities (CA) are trusted
-for its secure connections. For example, trusting particular self-signed certificates or restricting the set of public
-CAs that the app trusts.
-</li>
-<li><b>Debug-only overrides.</b> Lets an application developer safely debug secure connections of their
-application without added risk to the installed base.
-</li>
-<li><b>Cleartext traffic opt-out.</b> Lets an application protect itself from accidental usage of cleartext traffic.</li>
-<li><b>Certificate pinning.</b> An advanced feature that lets an application restrict pin its secure connection
-to particular certificates.</li>
-</ul>
-
-<h2 id="Examples">Examples</h2>
-<h3 id="TrustingCustomCas">Trusting Custom CAs</h3>
-<p>An application may want to trust a custom set of CAs instead of the platform
-default. The most common reasons of this are:
-<ul>
-<li>Connecting to a host with a custom certificate authority(self-signed, issued by an internal corporate CA, etc).</li>
-<li>Limiting the set of CAs to only the CAs you trust instead of every preinstalled CA.</li>
-<li>Trusting additional CAs not included in the system.</li>
-</ul>
-</p>
-<p>By default secure (e.g. TLS, HTTPS) connections from all applications trust the pre-installed system CAs, and
-applications targeting API level 23 (Android M) and below also trust the user-added CA store by default.
-An application can customize its own connections using {@code base-config} (for app-wide customization) or
-{@code domain-config} (for per-domain customization).</p>
-
-<h4 id="TrustingACustomCa">Trusting a Custom CA</h4>
-<p>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, e.g., your company's internal
-CA.</p>
-<p>
-<code>res/xml/network_security_config.xml</code>:
-<pre>
-<?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>
-</pre>
-</p>
-<p>Add the self-signed or non-public CA certificate, in PEM or DER format, to {@code res/raw/my_ca}.</p>
-<p>
-In <code>AndroidManifest.xml</code> reference the above config
-<pre>
-<?xml version="1.0" encoding="utf-8"?>
-...
-<application ...>
- <meta-data android:name="android.security.net.config"
- android:resource="@xml/network_security_config" />
- ...
-</pre>
-</p>
-<h4 id="LimitingCas">Limiting the Set of Trusted CAs</h4>
-<p>An application 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 application from fradulent certificates issued by any
-of the other CAs.</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 that multiple CAs are provided in the resource.</p>
-
-<p>
-<code>res/xml/network_security_config.xml</code>:
-<pre>
-<?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>
-</pre>
-</p>
-<p>Add the trusted CAs, in PEM or DER format, to {@code res/raw/trusted_roots}.
-Note that if using PEM format the file must contain <em>only</em> PEM data and no extra text.
-You can also provide multiple <a href="certificates"><code><certificates></code></a> elements instead
-of one.</p>
-<p>
-In <code>AndroidManifest.xml</code> reference the above config
-<pre>
-<?xml version="1.0" encoding="utf-8"?>
-...
-<application ...>
- <meta-data android:name="android.security.net.config"
- android:resource="@xml/network_security_config" />
- ...
-</pre>
-</p>
-
-<h4 id="TrustingAdditionalCas">Trusting Additional CAs</h4>
-<p>An application 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 application can do this by specifying multiple certificate sources for a configuration.
-</p>
-<p>
-<code>res/xml/network_security_config.xml</code>:
-<pre>
-<?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>
-</pre>
-</p>
-<p>
-In <code>AndroidManifest.xml</code> reference the above config
-<pre>
-<?xml version="1.0" encoding="utf-8"?>
-...
-<application ...>
- <meta-data android:name="android.security.net.config"
- android:resource="@xml/network_security_config" />
- ...
-</pre>
-</p>
-
-<h3 id="TrustingDebugCa">Debugging-only CAs</h3>
-<p>When debugging an application 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 application's code you can specify debug-only CAs that are
-<i>only</i> trusted 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 tools set this flag automatically for non-release builds.</p>
-<p>This is safer than the usual conditional code because, as a security precaution, application stores
-do not accept applications which are marked debuggable.</p>
-
-<p>
-<code>res/xml/network_security_config.xml</code>:
-<pre>
-<?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>
-</pre>
-</p>
-<p>
-In <code>AndroidManifest.xml</code> reference the above config
-<pre>
-<?xml version="1.0" encoding="utf-8"?>
-...
-<application ...>
- <meta-data android:name="android.security.net.config"
- android:resource="@xml/network_security_config" />
- ...
-</pre>
-</p>
-
-<h3 id="UsesCleartextTraffic">Cleartext Traffic Opt-Out</h3>
-<p>Applications which intend to connect to destinations using only secure connections can opt-out
-of supporting cleartext (i.e. plain HTTP instead of HTTPS) to those destinations. This helps prevent
-accidental regressions in applications due to changes in URLs provided by external sources such as
-backend servers.</p>
-<p>See {a href="{@docRoot}reference/android/security/NetworkSecurityPolicy.html#isCleartextTrafficPermitted()} for more details.</p>
-
-<p>For example, an application may want to ensure that all connections to {@code secure.example.com} are always
-done over HTTPS to protect sensitive traffic from hostile networks.</p>
-
-<p>
-<code>res/xml/network_security_config.xml</code>:
-<pre>
-<?xml version="1.0" encoding="utf-8"?>
-<network-security-config>
- <domain-config usesCleartextTraffic="false">
- <domain includeSubdomains="true">secure.example.com</domain>
- </domain-config>
-</network-security-config>
-</pre>
-</p>
-<p>
-In <code>AndroidManifest.xml</code> reference the above config
-<pre>
-<?xml version="1.0" encoding="utf-8"?>
-...
-<application ...>
- <meta-data android:name="android.security.net.config"
- android:resource="@xml/network_security_config" />
- ...
-</pre>
-</p>
-
-<h3 id="CertificatePinning">Certificate Pinning</h3>
-<p>Normally an application trusts all preinstalled CAs. If any of these CAs were to issue a fradulent certificate
-the application would be at risk from a MiTM attack. Some applications 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.</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 pinning to a CA certificate or an intermediate of that CA),
-your application's connectivity is unaffected. Otherwise you will have to push out an update to the
-application to restore connectivity.</p>
-
-<p>Additionally it is possible to set an expiration time for pins after which pinning will not be
-performed. This helps prevent connectivity issues in applications which have not been updated.
-However, setting an expiration time on pins may enable pinning bypass.
-</p>
-
-<p>
-<code>res/xml/network_security_config.xml</code>:
-<pre>
-<?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>
- </domain-config>
-</network-security-config>
-</pre>
-</p>
-<p>
-In <code>AndroidManifest.xml</code> reference the above config
-<pre>
-<?xml version="1.0" encoding="utf-8"?>
-...
-<application ...>
- <meta-data android:name="android.security.net.config"
- android:resource="@xml/network_security_config" />
- ...
-</pre>
-</p>
-
-<h3 id="ConfigInheritance">Configuration Inheritance</h3>
-<p>Values not set in a specific config will be inherited.
-This 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 will be used.
-Values not set in a {@code domain-config} will be 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} will use
-the platform default values.
-
-<p>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
-{@code trust-anchors} does not need to be duplicated.</p>
-
-<p>
-<code>res/xml/network_security_config.xml</code>:
-<pre>
-<?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>
-</pre>
-</p>
-<p>
-In <code>AndroidManifest.xml</code> reference the above config
-<pre>
-<?xml version="1.0" encoding="utf-8"?>
-...
-<application ...>
- <meta-data android:name="android.security.net.config"
- android:resource="@xml/network_security_config" />
- ...
-</pre>
-</p>
-
-<h2 id="FileFormat">Configuration File Format</h2>
-<p>The configuration file is XML. Here is what it can contain:</p>
-</p>
-<pre>
-<?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>
-</pre>
-
-<h3 id="network-security-config"><network-security-config></h3>
-<dl class="xml">
-<dt>can contain:</dt>
-<dd>0 or 1 <code><a href="#base-config"><base-config></a></code>
-<br/>Any number of <code><a href="#domain-config"><domain-config></a></code>
-<br/>0 or 1<code><a href="#debug-overrides"><debug-overrides></a></code>
-</dd>
-</dl>
-
-
-<h3 id="base-config"><base-config></h3>
-<dl class="xml">
-<dt>syntax:</dt>
-<dd><pre class="stx"><base-config <a href="#usesCleartextTraffic">usesCleartextTraffic</a>=["true" | "false"]>
- ...
-</base-config></pre></dd>
-<dt>can contain:</dt>
-<dd><code><a href="#trust-anchors"><trust-anchors></a></code></dd>
-<dt>descrption:</dt>
-<dd>
-The default configuration used by all connections whose destination is not covered by a
-<a href="#domain-config"><code>domain-config</code></a>.
-
-<p>Any values that are not set will use the platform default values.
-The default configuration for applications targeting above API level 24 and above:
-<pre>
-<base-config usesCleartextTraffic="true">
- <trust-anchors>
- <certificates src="system" />
- </trust-anchors>
-</base-config>
-</pre>
-The default configuration for applications targeting API level 23 and below is:
-<pre>
-<base-config usesCleartextTraffic="true">
- <trust-anchors>
- <certificates src="system" />
- <certificates src="user" />
- </trust-anchors>
-</base-config>
-</pre>
-</p>
-</dd>
-</dl>
-
-<h3 id="domain-config"><domain-config></h3>
-<dl class="xml">
-<dt>syntax:</dt>
-<dd><pre class="stx"><domain-config <a href="#usesCleartextTraffic">usesCleartextTraffic</a>=["true" | "false"]>
- ...
-</domain-config></pre></dd>
-<dt>Can Contain:</dt>
-
-<dd>
-1 or more <code><a href="#domain"><domain></a></code>
-<br/>0 or 1 <code><a href="#trust-anchors"><trust-anchors></a></code>
-<br/>0 or 1 <code><a href="#pin-set"><pin-set></code></a>
-<br/>Any number of nested <code><domain-config></code></dd>
-
-<dt>Descrption</dt>
-<dd>Configuration used for connections to specific destinations as the defined by {@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 will be used.</p></dd>
-</dl>
-
-<h3 id="domain"><domain></h3>
-<dl class="xml">
-<dt>syntax:</dt>
-<dd><pre class="stx"><domain includeSubdomains=["true" | "false"]>example.com</domain></pre></dd>
-<dt>Attributes:</dt>
-<dd><dl class="attr">
-<dt>{@code includeSubdomains}</dt>
-<dd>If {@code "true"} then this domain rule will match the domain and all subdomains, including
-subdomains of subdomains, otherwise the rule only applies to exact matches.</dd>
-</dl>
-</dd>
-
-<dt>Descrption:</dt>
-</dl>
-
-<h3 id="debug-overrides"><debug-overrides></h3>
-<dl class="xml">
-<dt>syntax:</dt>
-<dd><pre class="stx"><debug-overrides>
- ...
-</debug-overrides></pre></dd>
-<dt>Can Contain:</dt>
-<dd>0 or 1 <code><a href="#trust-anchors"><trust-anchors></a></code></dd>
-<dt>Description:</dt>
-<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 generated by IDEs and build tools.
-Trust anchors specified in {@code 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.
-</dd>
-</dl>
-
-<h3 id="trust-anchors"><trust-anchors></h3>
-<dl class="xml">
-<dt>syntax:</dt>
-<dd>
-<pre class="stx"><trust-anchors>
-...
-</trust-anchors>
-</pre></dd>
-<dt>Can Contain:</dt>
-<dd>Any number of <code><a href="#certificates"><certificates></a></code></dd>
-<dt>Description:</dt>
-<dd>Set of trust anchors for secure connections.</dd>
-</dl>
-
-
-<h3 id="certificates"><certificates></h3>
-<dl class="xml">
-<dt>syntax:</dt>
-<dd><pre class="stx"><certificates src=["system" | "user" | "<i>raw resource</i>"]
- overridePins=["true" | "false"] />
-</pre></dd>
-<dt>description:</dt>
-<dd>Set of X.509 certificates for {@code trust-anchors} elements.</dd>
-
-<dt>attributes:</dt>
-<dd><dl class="attr">
-<dt>{@code src}</dt>
-<dd>
-The source of CA certificates, can be one of
-<ul>
- <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 comments.</li>
- <li>{@code "system"} for the pre-installed system CA certificates</li>
- <li>{@code "user"} for user-added CA certificates</li>
-</ul>
-</dd>
-
-<dt>{@code overridePins}</dt>
-<dd>
-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 will not be performed. This can be useful
-for debug CAs or to support letting the user MiTM your app's secure traffic.
-<p>
-Default is {@code "false"} unless specified in a {@code debug-overrides} element, in which case the default is {@code "true"}.
-</p>
-</dd>
-</dl>
-</dd>
-
-<h3 id="pin-set"><pin-set></h3>
-<dl class="xml">
-<dt>syntax:</dt>
-<dd>
-<pre class="stx"><pin-set expiration="date">
-...
-</pin-set>
-</pre></dd>
-<dt>Can Contain:</dt>
-<dd>Any number of <code><a href="#pin"><pin></a></code></dd>
-<dt>Description:</dt>
-<dd>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 <code><a href="#pin"><pin></a></code> for the format of pins.</dd>
-<dt>Attributes:</dt>
-<dd><dl class="attr">
-<dt>{@code expiration}</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.
-<p>Expiration helps prevent connectivity issues in applications which do not get updates to their
-pin set, for example because the user disabled application updates.</p>
-</dd>
-</dl>
-</dd>
-
-<h3 id="pin"><pin></h3>
-<dl class="xml">
-<dt>syntax:</dt>
-<dd>
-<pre class="stx"><pin digest=["SHA-256"]>base64 encoded digest of X.509 SubjectPublicKeyInfo (SPKI)</pin></pre></dd>
-<dt>Attributes:</dt>
-<dd><dl class="attr">
-<dt>{@code digest}</dt>
-<dd>The digest algorithm used to generate the pin. Currently only {@code "SHA-256"} is supported.</dd>
-</dl>
-</dd>
-</dl>
