training/articles/security-config.jd

page.title=
page.keywords=androidn, ,
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
CA  .
  </li>

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

<p>
     (: TLS, HTTPS)     CA ,
API  23(Android M)
      CA   .
{@code base-config}(
  )  {@code domain-config}(
 )      .
</p>


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

<p>

       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>
       CA  PEM  DER
{@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>
     CA PEM  DER  {@code res/raw/trusted_roots} .
  PEM     PEM <em></em>
     .
<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
   .       ,
{@code debug-overrides}
 <i></i> <a href="{@docRoot}guide/topics/manifest/application-element.html#debug">
android:debuggable</a>
 {@code true}       CA   .  IDE
    .
</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;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)     .

  .
</p>

<p>

    CA  (
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>
    <code><a href="#base-config">&lt;base-config&gt;</a></code> 0  1<br>
    <code><a href=
    "#domain-config">&lt;domain-config&gt;</a></code>  <br>
    <code><a href="#debug-overrides">&lt;debug-overrides&gt;</a></code> 0  1
  </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>
<code><a href="#domain">&lt;domain&gt;</a></code> 1
<br/><code><a href="#trust-anchors">&lt;trust-anchors&gt;</a></code> 0  1
<br/><code><a href="#pin-set">&lt;pin-set&gt;</code></a> 0  1
<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>
    <code><a href="#trust-anchors">&lt;trust-anchors&gt;</a></code> 0  1
  </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>   CA  {@code "system"}
  </li>

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

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

  <p>
    {@code debug-overrides}
     {@code "false"}.    {@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>
            (   )
 PIN
     .
        </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>