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">  </a>
      <ol>
      <li><a href="#ConfigCustom">   </a></li>
      <li><a href="#LimitingCas">   </a></li>
      <li><a href="#TrustingAdditionalCas">    </a></li>
      </ol>
  </li>
  <li><a href="#TrustingDebugCa">  </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>     ()
    .

   ,   .
  </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;app ...&gt;
    &lt;meta-data android:name="android.security.net.config"
               android:resource="@xml/network_security_config" /&gt;
    ...
&lt;/app&gt;
</pre>

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

<p>
           ()    ,   .
   :
</p>

<ul>
  <li>      (,
     ..)
  </li>

  <li>
 .
  </li>

  <li>  ,    ,   .
  </li>
</ul>

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


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

<p>
  ,      ,    SSL,
   ,   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
 {@code res/raw/my_ca}.
</p>


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

<p>
        ,   ,
      .
    ,    .
</p>

<p>
         <a href="#TrustingACustomCa">   </a>   ,   ,
      .
</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  {@code res/raw/trusted_roots}.
   ,     PEM   <em></em>  PEM
  -  .
 <a href="#certificates"><code>&lt;certificates&gt;</code></a>
 .
</p>


<h3 id="TrustingAdditionalCas">

</h3>

<p>
       ,        .
      ,
        Android.
      ,
 .
</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">    </h2>

<p>
    ,      HTTPS,
     ,     SSL
   .
 ,      ,
     , <i></i>    <a href="{@docRoot}guide/topics/manifest/application-element.html#debug">
android:debuggable</a>
   {@code true}   {@code debug-overrides}.
        ,   .
</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>
  ,         ,
         (    HTTP
  HTTPS)   .
    ,    URL-,
 , ,  .
         {@link android.security.NetworkSecurityPolicy#isCleartextTrafficPermitted
  NetworkSecurityPolicy.isCleartextTrafficPermitted()}.
</p>

<p>
  ,       HTTPS     {@code
  secure.example.com},
   .
</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>
       .
  ,       .

     ,   .
</p>

<p>

   (SubjectPublicKeyInfo  X.509).
   ,
   .
</p>

<p>

 ,               (
       ).

  .
</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;/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}     .  ,
    , <em></em>    {@code
  secure.example.com}.    {@code
  secure.example.com}   {@code 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"},      ,
      .  ,   {@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>  X.509   {@code trust-anchors}.</dd>

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

<ul>
  <li>  ,      X.509.
        DER  PEM.    PEM
  <em> </em>  ,   PEM, ,
 .
  </li>

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

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

<dt>{@code overridePins}</dt>
<dd>
  <p>
    ,         .    {@code
    "true"},        ,
 .
         .
  </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>
         ,    .
 {@code "SHA-256"}.
      </dd>
    </dl>
  </dd>
</dl>