training/articles/security-config.jd

page.title=
page.keywords=androidn,security,network
page.image=images/cards/card-nyc_2x.jpg

@jd:body

<div id="tb-wrapper">
<div id="tb">

<h2></h2>
<ol>
  <li><a href="#manifest"></a></li>
  <li><a href="#CustomTrust"> CA </a>
      <ol>
      <li><a href="#ConfigCustom"> CA </a></li>
      <li><a href="#LimitingCas"> CA </a></li>
      <li><a href="#TrustingAdditionalCas"> CA </a></li>
      </ol>
  </li>
  <li><a href="#TrustingDebugCa"> CA</a></li>
  <li><a href="#UsesCleartextTraffic"> </a></li>
  <li><a href="#CertificatePinning"></a></li>
  <li><a href="#ConfigInheritance"></a></li>
  <li><a href="#FileFormat"></a></li>
</ol>
</div>
</div>


<p>
  Android N


</p>

<ul>
  <li>
    <b>  :</b>CA
 CA


  </li>

  <li>
    <b>:</b>

  </li>

  <li>
    <b> :</b>

  </li>

  <li>
    <b>:</b>

  </li>
</ul>


<h2 id="manifest"></h2>

<p>
   XML


</p>

<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;manifest ... &gt;
  &lt;application ... &gt;
    &lt;meta-data android:name="android.security.net.config"
               android:resource="@xml/network_security_config" /&gt;
    ...
  &lt;/application&gt;
&lt;/manifest&gt;
</pre>

<h2 id="CustomTrust"> CA </h2>

<p>
   CA

</p>

<ul>
  <li> CA

  </li>

  <li> CA  CA

  </li>

  <li> CA
  </li>
</ul>

<p>
  TLSHTTPS  CA API  23Android M CA

 {@code base-config} {@code domain-config}


</p>


<h3 id="ConfigCustom"> CA </h3>

<p>
   SSL  CA CA  SSL


</p>

<p>
  <code>res/xml/network_security_config.xml</code>:
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;network-security-config&gt;
    &lt;domain-config&gt;
        &lt;domain includeSubdomains="true"&gt;example.com&lt;/domain&gt;
        &lt;trust-anchors&gt;
            &lt;certificates src="@raw/my_ca"/&gt;
        &lt;/trust-anchors&gt;
    &lt;/domain-config&gt;
&lt;/network-security-config&gt;
</pre>
</p>

<p>
  PEM  DER  CA
{@code res/raw/my_ca}
</p>


<h3 id="LimitingCas"> CA </h3>

<p>
   CA  CA
 CA

</p>

<p>
   CA <a href="#TrustingACustomCa"> CA </a> CA

</p>

<p>
<code>res/xml/network_security_config.xml</code>:
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;network-security-config&gt;
    &lt;domain-config&gt;
        &lt;domain includeSubdomains="true"&gt;secure.example.com&lt;/domain&gt;
        &lt;domain includeSubdomains="true"&gt;cdn.example.com&lt;/domain&gt;
        &lt;trust-anchors&gt;
            &lt;certificates src="@raw/trusted_roots"/&gt;
        &lt;/trust-anchors&gt;
    &lt;/domain-config&gt;
&lt;/network-security-config&gt;
</pre>
</p>

<p>
  PEM  DER  CA  {@code res/raw/trusted_roots}
  PEM  PEM <em></em>
1
<a href="#certificates"><code>&lt;certificates&gt;</code></a>

</p>


<h3 id="TrustingAdditionalCas">
   CA
</h3>

<p>
   CA  CA CA  Android

CA


</p>
<p>
<code>res/xml/network_security_config.xml</code>:
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;network-security-config&gt;
    &lt;base-config&gt;
        &lt;trust-anchors&gt;
            &lt;certificates src="@raw/extracas"/&gt;
            &lt;certificates src="system"/&gt;
        &lt;/trust-anchors&gt;
    &lt;/base-config&gt;
&lt;/network-security-config&gt;
</pre>
</p>


<h2 id="TrustingDebugCa"> CA </h2>

<p>
  HTTPS  SSL


 <i></i> {@code debug-overrides} <a href="{@docRoot}guide/topics/manifest/application-element.html#debug">android:debuggable</a>  {@code true}  CA

IDE

</p>

<p>
    debuggable


</p>

<p>
<code>res/xml/network_security_config.xml</code>:
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;network-security-config&gt;
    &lt;debug-overrides&gt;
        &lt;trust-anchors&gt;
            &lt;certificates src="@raw/debug_cas"/&gt;
        &lt;/trust-anchors&gt;
    &lt;/debug-overrides&gt;
&lt;/network-security-config&gt;
</pre>
</p>


<h2 id="UsesCleartextTraffic"> </h2>

<p>
  HTTPS  HTTP

  URL


  {@link android.security.NetworkSecurityPolicy#isCleartextTrafficPermitted
  NetworkSecurityPolicy.isCleartextTrafficPermitted()}
</p>

<p>
   {@code
  secure.example.com}  HTTPS

</p>

<p>
<code>res/xml/network_security_config.xml</code>:
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;network-security-config&gt;
    &lt;domain-config usesCleartextTraffic="false"&gt;
        &lt;domain includeSubdomains="true"&gt;secure.example.com&lt;/domain&gt;
    &lt;/domain-config&gt;
&lt;/network-security-config&gt;
</pre>
</p>


<h2 id="CertificatePinning"></h2>

<p>
   CA  CA  MiTM

 CA

</p>

<p>
  X.509  SubjectPublicKeyInfo
 1


</p>

<p>
  CA CA  CA


</p>

<p>


</p>

<p>
<code>res/xml/network_security_config.xml</code>:
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;network-security-config&gt;
    &lt;domain-config&gt;
        &lt;domain includeSubdomains="true"&gt;example.com&lt;/domain&gt;
        &lt;pin-set expiration="2018-01-01"&gt;
            &lt;pin digest="SHA-256"&gt;7HIpactkIAq2Y49orFOOQKurWxmmSFZhBCoQYcRhJ3Y=&lt;/pin&gt;
            &lt;!-- backup pin --&gt
            &lt;pin digest="SHA-256"&gt;fwza0LRMXouZHRC8Ei+4PyuldPDcf3UKgO/04cDM1oE=&lt;/pin&gt;
        &lt;/pin-set&gt;
    &lt;/domain-config&gt;
&lt;/network-security-config&gt;
</pre>
</p>


<h2 id="ConfigInheritance"></h2>

<p>


</p>

<p>

{@code domain-config}  {@code domain-config}  {@code
  base-config}
{@code base-config}

</p>

<p>
  {@code
  example.com} CA  {@code
  secure.example.com} <em></em>
{@code example.com}  {@code
  secure.example.com}
{@code trust-anchors}
</p>

<p>
<code>res/xml/network_security_config.xml</code>:
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;network-security-config&gt;
    &lt;domain-config&gt;
        &lt;domain includeSubdomains="true"&gt;example.com&lt;/domain&gt;
        &lt;trust-anchors&gt;
            &lt;certificates src="@raw/my_ca"/&gt;
        &lt;/trust-anchors&gt;
        &lt;domain-config cleartextTrafficPermitted="false"&gt;
            &lt;domain includeSubdomains="true"&gt;secure.example.com&lt;/domain&gt;
        &lt;/domain-config&gt;
    &lt;/domain-config&gt;
&lt;/network-security-config&gt;
</pre>
</p>


<h2 id="FileFormat"></h2>

<p>
   XML

</p>

<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;network-security-config&gt;
    &lt;base-config&gt;
        &lt;trust-anchors&gt;
            &lt;certificates src="..."/&gt;
            ...
        &lt;/trust-anchors&gt;
    &lt;/base-config&gt;

    &lt;domain-config&gt;
        &lt;domain&gt;android.com&lt;/domain&gt;
        ...
        &lt;trust-anchors&gt;
            &lt;certificates src="..."/&gt;
            ...
        &lt;/trust-anchors&gt;
        &lt;pin-set&gt;
            &lt;pin digest="..."&gt;...&lt;/pin&gt;
            ...
        &lt;/pin-set&gt;
    &lt;/domain-config&gt;
    ...
    &lt;debug-overrides&gt;
        &lt;trust-anchors&gt;
            &lt;certificates src="..."/&gt;
            ...
        &lt;/trust-anchors&gt;
    &lt;/debug-overrides&gt;
&lt;/network-security-config&gt;
</pre>

<p>


</p>

<h3 id="network-security-config">
  &lt;network-security-config&gt;
</h3>

<dl class="xml">
  <dt>
    :
  </dt>

  <dd>
    0  1  <code><a href="#base-config">&lt;base-config&gt;</a></code><br>
     <code><a href=
    "#domain-config">&lt;domain-config&gt;</a></code><br>
    0  1  <code><a href="#debug-overrides">&lt;debug-overrides&gt;</a></code>
  </dd>
</dl>

<h3 id="base-config">
  &lt;base-config&gt;
</h3>

<dl class="xml">
  <dt>
    :
  </dt>
</dl>

<pre class="stx">
&lt;base-config <a href=
"#usesCleartextTraffic">usesCleartextTraffic</a>=["true" | "false"]&gt;
    ...
&lt;/base-config&gt;
</pre>
<dl class="xml">
  <dt>
    :
  </dt>

  <dd>
    <code><a href="#trust-anchors">&lt;trust-anchors&gt;</a></code>
  </dd>

  <dt>
    :
  </dt>

  <dd>
    <a href="#domain-config"><code>domain-config</code></a>


<p>
  API  24

</p>

<pre>
&lt;base-config usesCleartextTraffic="true"&gt;
    &lt;trust-anchors&gt;
        &lt;certificates src="system" /&gt;
    &lt;/trust-anchors&gt;
&lt;/base-config&gt;
</pre>
API  23
<pre>
&lt;base-config usesCleartextTraffic="true"&gt;
    &lt;trust-anchors&gt;
        &lt;certificates src="system" /&gt;
        &lt;certificates src="user" /&gt;
    &lt;/trust-anchors&gt;
&lt;/base-config&gt;
</pre>

  </dd>
</dl>

<h3 id="domain-config">&lt;domain-config&gt;</h3>
<dl class="xml">
<dt>:</dt>
<dd>
<pre class="stx">&lt;domain-config <a href="#usesCleartextTraffic">usesCleartextTraffic</a>=["true" | "false"]&gt;
    ...
&lt;/domain-config&gt;</pre>
</dd>

<dt>:</dt>

<dd>
1  <code><a href="#domain">&lt;domain&gt;</a></code>
<br/>0  1  <code><a href="#trust-anchors">&lt;trust-anchors&gt;</a></code>
<br/>0  1  <code><a href="#pin-set">&lt;pin-set&gt;</code></a>
<br/> <code>&lt;domain-config&gt;</code></dd>

<dt></dt>
<dd>{@code domain}

<p> {@code domain-config}
</p></dd>
</dl>


<h3 id="domain">&lt;domain&gt;</h3>

<dl class="xml">
  <dt>
    :
  </dt>

  <dd>
    <pre class="stx">
&lt;domain includeSubdomains=["true" | "false"]&gt;example.com&lt;/domain&gt;
</pre>
  </dd>

  <dt>
    :
  </dt>

  <dd>
    <dl class="attr">
      <dt>
        {@code includeSubdomains}
      </dt>

      <dd>
        {@code "true"}


      </dd>
    </dl>
  </dd>

  <dt>
    :
  </dt>
</dl>

<h3 id="debug-overrides">&lt;debug-overrides&gt;</h3>

<dl class="xml">
  <dt>
    :
  </dt>

  <dd>
    <pre class="stx">
&lt;debug-overrides&gt;
    ...
&lt;/debug-overrides&gt;
</pre>
  </dd>

  <dt>
    :
  </dt>

  <dd>
    0  1  <code><a href="#trust-anchors">&lt;trust-anchors&gt;</a></code>
  </dd>

  <dt>
    :
  </dt>

  <dd>
    <a href="{@docRoot}guide/topics/manifest/application-element.html#debug">android:debuggable</a>  {@code "true"} IDE

{@code
    debug-overrides}

<a href="{@docRoot}guide/topics/manifest/application-element.html#debug">android:debuggable</a>  {@code "false"}

  </dd>
</dl>

<h3 id="trust-anchors">&lt;trust-anchors&gt;</h3>
<dl class="xml">
  <dt>
    :
  </dt>

  <dd>
    <pre class="stx">
&lt;trust-anchors&gt;
...
&lt;/trust-anchors&gt;
</pre>
  </dd>

  <dt>
    :
  </dt>

  <dd>
     <code><a href="#certificates">&lt;certificates&gt;</a></code>
  </dd>

  <dt>
    :
  </dt>

  <dd>

  </dd>
</dl>


<h3 id="certificates">&lt;certificates&gt;</h3>
<dl class="xml">
<dt>:</dt>
<dd><pre class="stx">&lt;certificates src=["system" | "user" | "<i>raw resource</i>"]
              overridePins=["true" | "false"] /&gt;
</pre></dd>
<dt>:</dt>
<dd>{@code trust-anchors}  X.509 </dd>

<dt>:</dt>
<dd><dl class="attr">
<dt>{@code src}</dt>
<dd>
CA
<ul>
  <li>X.509  ID
  DER  PEM PEM  PEM
<em></em>

  </li>

  <li>{@code "system"}:  CA
  </li>

  <li>{@code "user"}:  CA
  </li>
</ul>
</dd>

<dt>{@code overridePins}</dt>
<dd>
  <p>
     CA {@code
    "true"}  CA
CA  MiTM

  </p>

  <p>
     {@code "false"} {@code debug-overrides}  {@code "true"}

  </p>
</dd>
</dl>
</dd>


<h3 id="pin-set">&lt;pin-set&gt;</h3>

<dl class="xml">
  <dt>
    :
  </dt>

  <dd>
<pre class="stx">
&lt;pin-set expiration="date"&gt;
...
&lt;/pin-set&gt;
</pre>
  </dd>

  <dt>
    :
  </dt>

  <dd>
     <code><a href="#pin">&lt;pin&gt;</a></code>
  </dd>

  <dt>
    :
  </dt>

  <dd>


<code><a href="#pin">&lt;pin&gt;</a></code>
  </dd>

  <dt>
    :
  </dt>

  <dd>
    <dl class="attr">
      <dt>
        {@code expiration}
      </dt>

      <dd>
        {@code yyyy-MM-dd}


        <p>


        </p>
      </dd>
    </dl>
  </dd>
</dl>

<h3 id="pin">&lt;pin&gt;</h3>
<dl class="xml">
  <dt>
    :
  </dt>

  <dd>
<pre class="stx">
&lt;pin digest=["SHA-256"]&gt;base64 encoded digest of X.509
    SubjectPublicKeyInfo (SPKI)&lt;/pin&gt;
</pre>
  </dd>

  <dt>
    :
  </dt>

  <dd>
    <dl class="attr">
      <dt>
        {@code digest}
      </dt>

      <dd>
        PIN
{@code "SHA-256"}
      </dd>
    </dl>
  </dd>
</dl>