1page.title=Конфигурация сетевой безопасности 2page.keywords=androidn,security,network 3page.image=images/cards/card-nyc_2x.jpg 4 5@jd:body 6 7<div id="qv-wrapper"> 8<div id="qv"> 9 10<h2>Содержание документа</h2> 11<ol> 12 <li><a href="#manifest">Добавление файла конфигурации безопасности</a></li> 13 <li><a href="#CustomTrust">Настройка доверенных ЦС</a> 14 <ol> 15 <li><a href="#ConfigCustom">Настройка доверенного пользовательского ЦС</a></li> 16 <li><a href="#LimitingCas">Ограничение набора доверенных ЦС</a></li> 17 <li><a href="#TrustingAdditionalCas">Добавление дополнительных ЦС в доверенные</a></li> 18 </ol> 19 </li> 20 <li><a href="#TrustingDebugCa">ЦС для отладки</a></li> 21 <li><a href="#UsesCleartextTraffic">Отказ от передачи данных открытым текстом</a></li> 22 <li><a href="#CertificatePinning">Прикрепление сертификатов</a></li> 23 <li><a href="#ConfigInheritance">Поведение при наследовании конфигурации</a></li> 24 <li><a href="#FileFormat">Формат файла конфигурации</a></li> 25</ol> 26</div> 27</div> 28 29 30<p> 31 В Android N имеется функция "Конфигурация сетевой безопасности", 32 позволяющая приложениям настраивать свои параметры сетевой безопасности в защищенном 33 декларативном файле конфигурации без изменения программного кода приложения. Эти параметры можно 34 настроить для определенных областей и приложений. Основные 35 возможности этой функции: 36</p> 37 38<ul> 39 <li> 40 <b>Пользовательские якоря доверия.</b> Настройка доверенных центров сертификации (ЦС) 41 для защищенных соединений приложения. Примером может служить 42 настройка доверия определенным самозаверенным сертификатам или ограничение 43 набора общих ЦС, которым доверяет приложение. 44 </li> 45 46 <li> 47 <b>Замена при отладке.</b> Безопасная отладка защищенных соединений приложения 48 без дополнительного риска для установленной базы. 49 </li> 50 51 <li> 52 <b>Отказ от передачи данных открытым текстом.</b> Защита приложений от 53 случайной передачи данных открытым текстом. 54 </li> 55 56 <li> 57 <b>Прикрепление сертификатов.</b> Ограничение защищенных соединений приложения 58 определенными сертификатами. 59 </li> 60</ul> 61 62 63<h2 id="manifest">Добавление файла конфигурации безопасности</h2> 64 65<p> 66 Функция конфигурации сетевой безопасности использует файл XML, где вы можете указать 67 настройки своего приложения. Вы должны включить в манифест своего приложения 68 запись, указывающую на этот файл. В следующем отрывке кода из манифеста 69 показано, как создать такую запись: 70</p> 71 72<pre> 73<?xml version="1.0" encoding="utf-8"?> 74... 75<app ...> 76 <meta-data android:name="android.security.net.config" 77 android:resource="@xml/network_security_config" /> 78 ... 79</app> 80</pre> 81 82<h2 id="CustomTrust">Настройка доверенных ЦС</h2> 83 84<p> 85 Приложению может потребоваться возможность доверять пользовательскому набору центров сертификации (ЦС) вместо набора ЦС платформы, установленного по умолчанию. 86 Наиболее распространенные причины: 87</p> 88 89<ul> 90 <li>Подключение к узлу с пользовательским ЦС (самозаверенным, 91 внутренним корпоративным ЦС и т. д.) 92 </li> 93 94 <li>Ограничение списка только доверенными ЦС вместо 95 предустановленных. 96 </li> 97 98 <li>Добавление дополнительных ЦС, не установленных в системе, в список доверенных. 99 </li> 100</ul> 101 102<p> 103 По умолчанию защищенные соединения всех приложений (например, TLS, HTTPS) доверяют 104 предустановленным системным ЦС, а приложения для API уровня 23 105 (Android M) и ниже также по умолчанию доверяют ЦС, добавленным пользователем. Приложение 106 может настраивать свои соединения, используя {@code base-config} (для 107 настройки на уровне приложения) или {@code domain-config} (для настройки на уровне 108 доменов). 109</p> 110 111 112<h3 id="ConfigCustom">Настройка пользовательского ЦС</h3> 113 114<p> 115 Предположим, вы хотите подключиться к своему узлу, использующему самозаверенный сертификат SSL, 116 или к узлу, чей сертификат SSL был выпущен закрытым ЦС, 117 которому вы доверяете, например внутренним ЦС вашей компании. 118</p> 119 120<p> 121 <code>res/xml/network_security_config.xml</code>: 122<pre> 123<?xml version="1.0" encoding="utf-8"?> 124<network-security-config> 125 <domain-config> 126 <domain includeSubdomains="true">example.com</domain> 127 <trust-anchors> 128 <certificates src="@raw/my_ca"/> 129 </trust-anchors> 130 </domain-config> 131</network-security-config> 132</pre> 133</p> 134 135<p> 136 Добавьте самозаверенный сертификат или сертификат закрытого ЦС в формате PEM или DER в 137 {@code res/raw/my_ca}. 138</p> 139 140 141<h3 id="LimitingCas">Ограничение набора доверенных ЦС</h3> 142 143<p> 144 Если приложению не нужно доверять всем ЦС, которым доверяет система, для него 145 можно указать сокращенный набор доверенных ЦС. Это позволит защитить 146 приложение от поддельных сертификатов, выпущенных любыми другими ЦС. 147</p> 148 149<p> 150 Настройка ограниченного набора доверенных ЦС похожа на <a href="#TrustingACustomCa">настройку доверия пользовательскому ЦС</a> для определенного домена, за тем исключением, 151 что в ресурсе указывается несколько ЦС. 152</p> 153 154<p> 155<code>res/xml/network_security_config.xml</code>: 156<pre> 157<?xml version="1.0" encoding="utf-8"?> 158<network-security-config> 159 <domain-config> 160 <domain includeSubdomains="true">secure.example.com</domain> 161 <domain includeSubdomains="true">cdn.example.com</domain> 162 <trust-anchors> 163 <certificates src="@raw/trusted_roots"/> 164 </trust-anchors> 165 </domain-config> 166</network-security-config> 167</pre> 168</p> 169 170<p> 171 Добавьте список доверенных ЦС в формате PEM или DER в {@code res/raw/trusted_roots}. 172 Обратите внимание, что файл в формате PEM должен содержать <em>только</em> данные PEM 173 без какого-либо дополнительного текста. Вы также можете указать несколько элементов 174 <a href="#certificates"><code><certificates></code></a> 175вместо одного. 176</p> 177 178 179<h3 id="TrustingAdditionalCas"> 180 Добавление дополнительных ЦС в доверенные 181</h3> 182 183<p> 184 Приложению может потребоваться доверять дополнительным ЦС, которые не входят в список доверенных ЦС системы. 185 Это может быть связано с тем, что эти ЦС еще не добавлены в систему или 186 не соответствуют требованиям для включения в систему Android. Приложение 187 может добавить такие ЦС в доверенные, указав несколько источников сертификатов для 188 конфигурации. 189</p> 190<p> 191<code>res/xml/network_security_config.xml</code>: 192<pre> 193<?xml version="1.0" encoding="utf-8"?> 194<network-security-config> 195 <base-config> 196 <trust-anchors> 197 <certificates src="@raw/extracas"/> 198 <certificates src="system"/> 199 </trust-anchors> 200 </base-config> 201</network-security-config> 202</pre> 203</p> 204 205 206<h2 id="TrustingDebugCa">Настройка конфигурации ЦС для отладки</h2> 207 208<p> 209 При отладке приложения, которое использует для подключения протокол HTTPS, вам может потребоваться 210 подключение к локальному серверу разработки, у которого нет сертификата SSL 211 для рабочего сервера. Чтобы выполнить отладку без изменения кода 212 приложения, вы можете указать ЦС для отладки, 213 которые входят в число доверенных, <i>только</i> если для параметра <a href="{@docRoot}guide/topics/manifest/application-element.html#debug"> 214android:debuggable</a> 215 установлено значение {@code true} с использованием {@code debug-overrides}. Обычно среды разработки и инструменты 216 сборки устанавливают этот флаг автоматически для всех сборок, кроме выпускаемой версии. 217</p> 218 219<p> 220 Такая схема работы более безопасна, чем использование обычного условного кода, поскольку в качестве 221 меры предосторожности магазины приложений не принимают приложения, помеченные 222 как доступные для отладки. 223</p> 224 225<p> 226<code>res/xml/network_security_config.xml</code>: 227<pre> 228<?xml version="1.0" encoding="utf-8"?> 229<network-security-config> 230 <debug-overrides> 231 <trust-anchors> 232 <certificates src="@raw/debug_cas"/> 233 </trust-anchors> 234 </debug-overrides> 235</network-security-config> 236</pre> 237</p> 238 239 240<h2 id="UsesCleartextTraffic">Отказ от передачи данных открытым текстом</h2> 241 242<p> 243 Приложения, которым нужно подключаться к узлам только через защищенные соединения, 244 могут отказаться от поддержки передачи данных открытым текстом (с использованием нешифрованного протокола HTTP 245 вместо HTTPS) на эти узлы. Эта возможность помогает предотвратить 246 случайные неполадки в приложениях, связанные с изменениями URL-адресов, предоставленных внешними 247 источниками, например, инфраструктурными серверами. 248 Дополнительную информацию можно найти в описании метода {@link android.security.NetworkSecurityPolicy#isCleartextTrafficPermitted 249 NetworkSecurityPolicy.isCleartextTrafficPermitted()}. 250</p> 251 252<p> 253 Например, приложение может потребовать обязательное использование протокола HTTPS для всех соединений с {@code 254 secure.example.com}, чтобы защитить важный трафик 255 от небезопасных сетей. 256</p> 257 258<p> 259<code>res/xml/network_security_config.xml</code>: 260<pre> 261<?xml version="1.0" encoding="utf-8"?> 262<network-security-config> 263 <domain-config usesCleartextTraffic="false"> 264 <domain includeSubdomains="true">secure.example.com</domain> 265 </domain-config> 266</network-security-config> 267</pre> 268</p> 269 270 271<h2 id="CertificatePinning">Прикрепление сертификатов</h2> 272 273<p> 274 Обычно приложение доверяет всем предустановленным ЦС. Если любой из этих ЦС выпустит 275 поддельный сертификат, приложение подвергается риску атаки с перехватом данных. 276 Некоторым приложениям требуется ограничить принимаемый набор сертификатов 277 либо ограничением списка доверенных ЦС, либо прикреплением сертификатов. 278</p> 279 280<p> 281 Прикрепление сертификатов осуществляется путем предоставления набора сертификатов через хэш 282 открытого ключа (SubjectPublicKeyInfo сертификата X.509). В этом случае цепочка 283 сертификатов будет действительна, только если она содержит хотя бы один 284 прикрепленный открытый ключ. 285</p> 286 287<p> 288 При использовании прикрепления сертификатов всегда необходимо добавлять резервный 289 ключ, чтобы работа приложения не пострадала при необходимости перехода на новые ключи или смены ЦС (при 290 прикреплении сертификата ЦС или посредника этого ЦС). 291 Без резервного ключа для восстановления возможности подключения приложения потребуется срочно выпускать 292 его обновление. 293</p> 294 295<p> 296 Кроме того, существует возможность установить срок прикрепления, по истечении которого 297 прикрепление не выполняется. Это помогает предотвратить проблемы с подключением 298 приложений, которые не были обновлены. Однако установка срока действия 299 прикреплений позволяет обойти их ограничения. 300</p> 301 302<p> 303<code>res/xml/network_security_config.xml</code>: 304<pre> 305<?xml version="1.0" encoding="utf-8"?> 306<network-security-config> 307 <domain-config> 308 <domain includeSubdomains="true">example.com</domain> 309 <pin-set expiration="2018-01-01"> 310 <pin digest="SHA-256">7HIpactkIAq2Y49orFOOQKurWxmmSFZhBCoQYcRhJ3Y=</pin> 311 <!-- backup pin --> 312 <pin digest="SHA-256">fwza0LRMXouZHRC8Ei+4PyuldPDcf3UKgO/04cDM1oE=</pin> 313 </domain-config> 314</network-security-config> 315</pre> 316</p> 317 318 319<h2 id="ConfigInheritance">Поведение при наследовании конфигурации</h2> 320 321<p> 322 Значения, не установленные в определенной конфигурации, наследуются. Такое поведение позволяет создавать более 323 сложные конфигурации, сохраняя при этом файл конфигурации в читаемом виде. 324</p> 325 326<p> 327 Если в определенной записи не установлено значение, используется значение из следующей более общей записи. 328 Значения, не установленные в {@code domain-config}, 329 берутся из родительского элемента {@code domain-config} в многоуровневых конфигурациях или из элемента {@code 330 base-config} в простых конфигурациях. Для значений, не установленных в {@code base-config}, используются 331 значения по умолчанию для платформы. 332</p> 333 334<p> 335 Рассмотрим пример, где все соединения с доменами нижнего уровня {@code 336 example.com} должны использовать пользовательский набор ЦС. Кроме того, для этих доменов разрешена 337 передача данных открытым текстом, <em>кроме</em> случаев подключения к {@code 338 secure.example.com}. При вложении конфигурации {@code 339 secure.example.com} в конфигурацию {@code example.com} не требуется дублирование 340 {@code trust-anchors}. 341</p> 342 343<p> 344<code>res/xml/network_security_config.xml</code>: 345<pre> 346<?xml version="1.0" encoding="utf-8"?> 347<network-security-config> 348 <domain-config> 349 <domain includeSubdomains="true">example.com</domain> 350 <trust-anchors> 351 <certificates src="@raw/my_ca"/> 352 </trust-anchors> 353 <domain-config cleartextTrafficPermitted="false"> 354 <domain includeSubdomains="true">secure.example.com</domain> 355 </domain-config> 356 </domain-config> 357</network-security-config> 358</pre> 359</p> 360 361 362<h2 id="FileFormat">Формат файла конфигурации</h2> 363 364<p> 365 Функция конфигурации сетевой безопасности использует формат файлов XML. 366 Общая структура файла показана в следующем примере кода: 367</p> 368 369<pre> 370<?xml version="1.0" encoding="utf-8"?> 371<network-security-config> 372 <base-config> 373 <trust-anchors> 374 <certificates src="..."/> 375 ... 376 </trust-anchors> 377 </base-config> 378 379 <domain-config> 380 <domain>android.com</domain> 381 ... 382 <trust-anchors> 383 <certificates src="..."/> 384 ... 385 </trust-anchors> 386 <pin-set> 387 <pin digest="...">...</pin> 388 ... 389 </pin-set> 390 </domain-config> 391 ... 392 <debug-overrides> 393 <trust-anchors> 394 <certificates src="..."/> 395 ... 396 </trust-anchors> 397 </debug-overrides> 398</network-security-config> 399</pre> 400 401<p> 402 В следующих разделах содержится описание синтаксиса и других деталей формата 403 файла. 404</p> 405 406<h3 id="network-security-config"> 407 <network-security-config> 408</h3> 409 410<dl class="xml"> 411 <dt> 412 Может содержать: 413 </dt> 414 415 <dd> 416 0 или 1 <code><a href="#base-config"><base-config></a></code><br> 417 Любое количество <code><a href= 418 "#domain-config"><domain-config></a></code><br> 419 0 или 1 <code><a href="#debug-overrides"><debug-overrides></a></code> 420 </dd> 421</dl> 422 423<h3 id="base-config"> 424 <base-config> 425</h3> 426 427<dl class="xml"> 428 <dt> 429 Синтаксис: 430 </dt> 431</dl> 432 433<pre class="stx"> 434<base-config <a href= 435"#usesCleartextTraffic">usesCleartextTraffic</a>=["true" | "false"]> 436 ... 437</base-config> 438</pre> 439<dl class="xml"> 440 <dt> 441 Может содержать: 442 </dt> 443 444 <dd> 445 <code><a href="#trust-anchors"><trust-anchors></a></code> 446 </dd> 447 448 <dt> 449 Описание: 450 </dt> 451 452 <dd> 453 Конфигурация по умолчанию, используемая всеми подключениями к узлам, не входящим в <a href="#domain-config"><code>domain-config</code></a>. 454 455 456<p> 457 Если значения не установлены, используются значения по умолчанию для платформы. Конфигурация по умолчанию 458 для приложений, использующих API уровня 24 или выше: 459</p> 460 461<pre> 462<base-config usesCleartextTraffic="true"> 463 <trust-anchors> 464 <certificates src="system" /> 465 </trust-anchors> 466</base-config> 467</pre> 468Конфигурация по умолчанию для приложений, использующих API уровня 23 или ниже: 469<pre> 470<base-config usesCleartextTraffic="true"> 471 <trust-anchors> 472 <certificates src="system" /> 473 <certificates src="user" /> 474 </trust-anchors> 475</base-config> 476</pre> 477 478 </dd> 479</dl> 480 481<h3 id="domain-config"><domain-config></h3> 482<dl class="xml"> 483<dt>Синтаксис:</dt> 484<dd> 485<pre class="stx"><domain-config <a href="#usesCleartextTraffic">usesCleartextTraffic</a>=["true" | "false"]> 486 ... 487</domain-config></pre> 488</dd> 489 490<dt>Может содержать:</dt> 491 492<dd> 4931 или более <code><a href="#domain"><domain></a></code> 494<br/>0 или 1 <code><a href="#trust-anchors"><trust-anchors></a></code> 495<br/>0 или 1 <code><a href="#pin-set"><pin-set></code></a> 496<br/>Любое количество вложенных <code><domain-config></code></dd> 497 498<dt>Описание</dt> 499<dd>Конфигурация, используемая для подключения к конкретным узлам, определенными элементами {@code domain}. 500 501<p>Если для узла назначения существует несколько элементов {@code domain-config}, используется правило для наиболее конкретного (самого длинного) совпадающего домена. 502</p></dd> 503</dl> 504 505 506<h3 id="domain"><domain></h3> 507 508<dl class="xml"> 509 <dt> 510 Синтаксис: 511 </dt> 512 513 <dd> 514 <pre class="stx"> 515<domain includeSubdomains=["true" | "false"]>example.com</domain> 516</pre> 517 </dd> 518 519 <dt> 520 Атрибуты: 521 </dt> 522 523 <dd> 524 <dl class="attr"> 525 <dt> 526 {@code includeSubdomains} 527 </dt> 528 529 <dd> 530 Если значение равно {@code "true"}, то правило домена соответствует указанному домену и всем доменам его 531 нижних уровней. В противном случае правило действует 532 только для полных совпадений. 533 </dd> 534 </dl> 535 </dd> 536 537 <dt> 538 Описание: 539 </dt> 540</dl> 541 542<h3 id="debug-overrides"><debug-overrides></h3> 543 544<dl class="xml"> 545 <dt> 546 Синтаксис: 547 </dt> 548 549 <dd> 550 <pre class="stx"> 551<debug-overrides> 552 ... 553</debug-overrides> 554</pre> 555 </dd> 556 557 <dt> 558 Может содержать: 559 </dt> 560 561 <dd> 562 0 или 1 <code><a href="#trust-anchors"><trust-anchors></a></code> 563 </dd> 564 565 <dt> 566 Описание: 567 </dt> 568 569 <dd> 570 Переопределения применяются, когда параметр <a href="{@docRoot}guide/topics/manifest/application-element.html#debug">android:debuggable</a> 571 имеет значение {@code "true"}, что обычно верно для промежуточных сборок, 572 создаваемых средами разработки и инструментами сборки. Якоря доверия, указанные в {@code 573 debug-overrides}, добавляются ко всем другим конфигурациям, и прикрепление 574 сертификатов не выполняется, если цепочка сертификатов сервера использует один из этих 575 якорей доверия, предназначенных только для отладки. Если параметр <a href="{@docRoot}guide/topics/manifest/application-element.html#debug">android:debuggable</a> 576 имеет значение {@code "false"}, этот раздел полностью игнорируется. 577 </dd> 578</dl> 579 580<h3 id="trust-anchors"><trust-anchors></h3> 581<dl class="xml"> 582 <dt> 583 Синтаксис: 584 </dt> 585 586 <dd> 587 <pre class="stx"> 588<trust-anchors> 589... 590</trust-anchors> 591</pre> 592 </dd> 593 594 <dt> 595 Может содержать: 596 </dt> 597 598 <dd> 599 Любое количество <code><a href="#certificates"><certificates></a></code> 600 </dd> 601 602 <dt> 603 Описание: 604 </dt> 605 606 <dd> 607 Набор якорей доверия для защищенных соединений. 608 </dd> 609</dl> 610 611 612<h3 id="certificates"><certificates></h3> 613<dl class="xml"> 614<dt>Синтаксис:</dt> 615<dd><pre class="stx"><certificates src=["system" | "user" | "<i>raw resource</i>"] 616 overridePins=["true" | "false"] /> 617</pre></dd> 618<dt>Описание:</dt> 619<dd>Набор сертификатов X.509 для элементов {@code trust-anchors}.</dd> 620 621<dt>Атрибуты:</dt> 622<dd><dl class="attr"> 623<dt>{@code src}</dt> 624<dd> 625Источник сертификатов ЦС может представлять собой 626<ul> 627 <li>идентификатор исходного ресурса, указывающий на файл с сертификатами X.509. 628 Сертификаты должны быть закодированы в формате DER или PEM. При использовании сертификатов PEM 629 файл <em>не должен</em> содержать ничего, кроме данных PEM, например, 630 комментариев. 631 </li> 632 633 <li>{@code "system"} для предустановленных в системе сертификатов ЦС 634 </li> 635 636 <li>{@code "user"} для добавленных пользователем сертификатов ЦС 637 </li> 638</ul> 639</dd> 640 641<dt>{@code overridePins}</dt> 642<dd> 643 <p> 644 Указывает, пропускается ли прикрепление сертификатов для ЦС из этого источника. Если значение равно {@code 645 "true"}, то прикрепление сертификатов не выполняется для цепочек сертификатов, проходящих через один из ЦС этого 646 источника. Это применяется для отладки ЦС 647 или для разрешения пользователю перехватывать защищенный трафик вашего приложения. 648 </p> 649 650 <p> 651 По умолчанию используется значение {@code "false"}, но если указан элемент {@code debug-overrides}, 652 то по умолчанию используется значение {@code "true"}. 653 </p> 654</dd> 655</dl> 656</dd> 657 658 659<h3 id="pin-set"><pin-set></h3> 660 661<dl class="xml"> 662 <dt> 663 Синтаксис: 664 </dt> 665 666 <dd> 667<pre class="stx"> 668<pin-set expiration="date"> 669... 670</pin-set> 671</pre> 672 </dd> 673 674 <dt> 675 Может содержать: 676 </dt> 677 678 <dd> 679 Любое количество <code><a href="#pin"><pin></a></code> 680 </dd> 681 682 <dt> 683 Описание: 684 </dt> 685 686 <dd> 687 Набор прикрепленных открытых ключей. Чтобы защищенное соединение было доверенным, один из 688 открытых ключей в цепочке доверия должен входить в набор прикрепленных ключей. Формат ключей указан в 689 <code><a href="#pin"><pin></a></code>. 690 </dd> 691 692 <dt> 693 Атрибуты: 694 </dt> 695 696 <dd> 697 <dl class="attr"> 698 <dt> 699 {@code expiration} 700 </dt> 701 702 <dd> 703 Дата в формате {@code yyyy-MM-dd}, начиная с которой истекает срок прикрепления 704 и оно отключается. Если этот атрибут не установлен, 705 срок прикрепления не истекает. 706 <p> 707 Истечение срока прикрепления помогает предотвратить проблемы с подключением в приложениях, которые 708 не получают обновления набора прикрепленных элементов, например в связи с тем, что пользователь 709 отключил обновления приложений. 710 </p> 711 </dd> 712 </dl> 713 </dd> 714</dl> 715 716<h3 id="pin"><pin></h3> 717<dl class="xml"> 718 <dt> 719 Синтаксис: 720 </dt> 721 722 <dd> 723<pre class="stx"> 724<pin digest=["SHA-256"]>base64 encoded digest of X.509 725 SubjectPublicKeyInfo (SPKI)</pin> 726</pre> 727 </dd> 728 729 <dt> 730 Атрибуты: 731 </dt> 732 733 <dd> 734 <dl class="attr"> 735 <dt> 736 {@code digest} 737 </dt> 738 739 <dd> 740 Алгоритм хэширования, используемый для создания прикреплений. В настоящее время поддерживается только алгоритм 741 {@code "SHA-256"}. 742 </dd> 743 </dl> 744 </dd> 745</dl> 746
