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

- 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

    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:

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>

<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>

  </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>

</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.

</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>

</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>

<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>

<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.

<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.

<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>

<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>

    </trust-anchors>

</base-config>

</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>

<base-config cleartextTrafficPermitted="true">

    <trust-anchors>

<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">

      </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>

  <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>

<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>

<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>

      </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>

      </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>