Конфигурация сетевой безопасности

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Функция конфигурации сетевой безопасности позволяет вам настроить параметры сетевой безопасности вашего приложения в безопасном декларативном файле конфигурации без изменения кода приложения. Эти параметры можно настроить для определенных доменов и для конкретного приложения. Ключевые возможности этой функции:

• Пользовательские якоря доверия. Настройте, каким центрам сертификации (CA) будут доверять безопасные соединения приложения. Например, доверяя определенным самозаверяющим сертификатам или ограничивая набор общедоступных центров сертификации, которым доверяет приложение.
• Переопределения только для отладки: безопасная отладка безопасных соединений в приложении без дополнительного риска для установленной базы.
• Отказ от трафика открытого текста: защитите приложения от случайного использования трафика открытого текста (незашифрованного).
• Согласие на прозрачность сертификатов: Ограничьте безопасные подключения приложения, используя доказуемо зарегистрированные сертификаты.
• Закрепление сертификата: Ограничьте безопасное соединение приложения определенными сертификатами.

Добавьте файл конфигурации сетевой безопасности

Функция конфигурации сетевой безопасности использует XML-файл, в котором вы указываете параметры своего приложения. Вы должны включить в манифест вашего приложения запись, указывающую на этот файл. Следующий фрагмент кода из манифеста демонстрирует, как создать эту запись:

<?xml version="1.0" encoding="utf-8"?>
<manifest ... >
    <application android:networkSecurityConfig="@xml/network_security_config"
                    ... >
        ...
    </application>
</manifest>

Настройка доверенных центров сертификации

Возможно, вы захотите, чтобы ваше приложение доверяло пользовательскому набору центров сертификации, а не стандартному набору центров сертификации. Наиболее распространенными причинами этого являются:

• Подключение к хосту с помощью специального центра сертификации, например центра сертификации, который является самоподписанным или выдан внутри компании.
• Ограничьте набор центров сертификации только теми центрами сертификации, которым вы доверяете, а не каждым предварительно установленным центром сертификации.
• Доверие дополнительным центрам сертификации, не включенным в систему.

По умолчанию безопасные соединения (с использованием таких протоколов, как TLS и HTTPS) всех приложений доверяют предустановленным системным центрам сертификации, а приложения, предназначенные для Android 6.0 (уровень API 23) и ниже, также по умолчанию доверяют добавленному пользователем хранилищу центров сертификации. Вы можете настроить соединения вашего приложения с помощью base-config (для настройки всего приложения) или domain-config (для настройки для каждого домена).

Настройка пользовательского центра сертификации

Возможно, вы захотите подключиться к хосту, который использует самозаверяющий сертификат SSL, или к хосту, сертификат SSL которого выдан закрытым центром сертификации, которому вы доверяете, например внутренним центром сертификации вашей компании. В следующем фрагменте кода показано, как настроить приложение для пользовательского центра сертификации в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

Добавьте самозаверяющий или закрытый сертификат CA в формате PEM или DER в res/raw/my_ca .

Ограничьте набор доверенных центров сертификации

Если вы не хотите, чтобы ваше приложение доверяло всем центрам сертификации, которым доверяет система, вместо этого вы можете указать сокращенный набор центров сертификации, которым можно доверять. Это защищает приложение от поддельных сертификатов, выданных любым другим центром сертификации.

Конфигурация ограничения набора доверенных центров сертификации аналогична настройке доверия пользовательскому центру сертификации для определенного домена, за исключением того, что в ресурсе предусмотрено несколько центров сертификации. В следующем фрагменте кода показано, как ограничить набор доверенных центров сертификации вашего приложения в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">secure.example.com</domain>
        <domain includeSubdomains="true">cdn.example.com</domain>
        <trust-anchors>
            <certificates src="@raw/trusted_roots"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

Добавьте доверенные центры сертификации в формате PEM или DER в res/raw/trusted_roots . Обратите внимание: если вы используете формат PEM, файл должен содержать только данные PEM и не содержать дополнительного текста. Вы также можете предоставить несколько элементов <certificates> вместо одного.

Доверяйте дополнительным центрам сертификации

Возможно, вы захотите, чтобы ваше приложение доверяло дополнительным центрам сертификации, которым не доверяет система, например, если система еще не включает центр сертификации или центр сертификации не соответствует требованиям для включения в систему Android. Вы можете указать несколько источников сертификатов для конфигурации в файле res/xml/network_security_config.xml используя код, подобный следующему фрагменту.

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <trust-anchors>
            <certificates src="@raw/extracas"/>
            <certificates src="system"/>
        </trust-anchors>
    </base-config>
</network-security-config>

Настройка центров сертификации для отладки

При отладке приложения, подключающегося через HTTPS, вам может потребоваться подключиться к локальному серверу разработки, у которого нет сертификата SSL для вашего рабочего сервера. Чтобы обеспечить это без каких-либо изменений в коде вашего приложения, вы можете указать центры сертификации только для отладки, которым доверяют только в том случае, если android:debuggable имеет true , с помощью debug-overrides . Обычно IDE и инструменты сборки автоматически устанавливают этот флаг для нерелизных сборок.

Это безопаснее, чем обычный условный код, поскольку в целях безопасности магазины приложений не принимают приложения, помеченные как отлаживаемые.

В приведенном ниже отрывке показано, как указать центры сертификации только для отладки в файле res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <debug-overrides>
        <trust-anchors>
            <certificates src="@raw/debug_cas"/>
        </trust-anchors>
    </debug-overrides>
</network-security-config>

Включите прозрачность сертификата

Примечание. Поддержка прозрачности сертификатов доступна только в Android 16 (уровень API 36).

Прозрачность сертификатов (CT, RFC 6962 ) — это Интернет-стандарт, разработанный для повышения безопасности цифровых сертификатов. Он требует от центров сертификации отправлять все выданные сертификаты в общедоступный журнал, в котором они фиксируются, что повышает прозрачность и подотчетность в процессе выдачи сертификатов.

Поддерживая проверяемый учет всех сертификатов, CT значительно затрудняет подделку сертификатов злоумышленниками или их ошибочную выдачу центрами сертификации. Это помогает защитить пользователей от атак «злоумышленник посередине» и других угроз безопасности. Для получения дополнительной информации см. объяснение на сайтеtransparency.dev . Дополнительную информацию о соответствии требованиям CT на Android см. в политике Android CT .

По умолчанию сертификаты принимаются независимо от того, зарегистрированы ли они в журнале CT. Чтобы ваше приложение подключалось только к местам назначения с сертификатами, зарегистрированными в журнале CT, вы можете включить эту функцию либо глобально , либо для каждого домена .

Отключить трафик открытого текста

Примечание. Рекомендации в этом разделе применимы только к приложениям, предназначенным для Android 8.1 (уровень API 27) или ниже. Начиная с Android 9 (уровень API 28), поддержка открытого текста отключена по умолчанию.

Если вы хотите, чтобы ваше приложение подключалось к местам назначения, используя только безопасные соединения, вы можете отказаться от поддержки открытого текста (с использованием незашифрованного протокола HTTP вместо HTTPS) для этих мест назначения. Этот параметр помогает предотвратить случайные регрессии в приложениях из-за изменений URL-адресов, предоставленных внешними источниками, такими как внутренние серверы. Дополнительные сведения см. в разделе NetworkSecurityPolicy.isCleartextTrafficPermitted() .

Например, вы можете захотеть, чтобы ваше приложение гарантировало, что подключения к secure.example.com всегда выполняются через HTTPS, чтобы защитить конфиденциальный трафик от враждебных сетей.

В приведенном ниже отрывке показано, как отказаться от открытого текста в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="false">
        <domain includeSubdomains="true">secure.example.com</domain>
    </domain-config>
</network-security-config>

ПИН-сертификаты

Обычно приложение доверяет всем предустановленным центрам сертификации. Если бы какой-либо из этих центров сертификации выдал поддельный сертификат, приложение подверглось бы риску со стороны злоумышленника на пути. Некоторые приложения предпочитают ограничивать набор принимаемых сертификатов, ограничивая набор центров сертификации, которым они доверяют, или закрепляя сертификаты.

Закрепление сертификата осуществляется путем предоставления набора сертификатов по хешу открытого ключа ( SubjectPublicKeyInfo сертификата X.509). В этом случае цепочка сертификатов действительна только в том случае, если цепочка сертификатов содержит хотя бы один из закрепленных открытых ключей.

Обратите внимание, что при использовании закрепления сертификата вы всегда должны включать резервный ключ, чтобы, если вам придется переключиться на новые ключи или изменить центр сертификации (при закреплении сертификата центра сертификации или промежуточного центра этого центра сертификации), подключение вашего приложения не пострадало. В противном случае вам придется обновить приложение, чтобы восстановить соединение.

Дополнительно можно установить срок действия для булавок, по истечении которого закрепление не будет выполняться. Это помогает предотвратить проблемы с подключением в приложениях, которые не были обновлены. Однако установка срока действия для контактов может позволить злоумышленникам обойти ваши закрепленные сертификаты.

В приведенном ниже отрывке показано, как закрепить сертификаты в res/xml/network_security_config.xml :

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

Поведение наследования конфигурации

Значения, не заданные в конкретной конфигурации, наследуются. Такое поведение позволяет создавать более сложные конфигурации, сохраняя при этом файл конфигурации доступным для чтения.

Например, значения, не заданные в domain-config берутся из родительского domain-config , если он вложен, или из base-config , если нет. Значения, не заданные в base-config используют значения платформы по умолчанию.

Например, рассмотрим случай, когда все подключения к субдоменам example.com должны использовать специальный набор центров сертификации. Кроме того, трафик в открытом виде к этим доменам разрешен, за исключением случаев подключения к secure.example.com . Если вложить конфигурацию secure.example.com в конфигурацию example.com , нет необходимости дублировать trust-anchors .

В приведенном ниже отрывке показано, как это вложение будет выглядеть в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
        <domain-config cleartextTrafficPermitted="false">
            <domain includeSubdomains="true">secure.example.com</domain>
        </domain-config>
    </domain-config>
</network-security-config>

Формат файла конфигурации

Функция конфигурации сетевой безопасности использует формат файла XML. Общая структура файла показана в следующем примере кода:

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

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

В следующих разделах описываются синтаксис и другие детали формата файла.

<конфигурация-сети-безопасности>

может содержать:

0 или 1 из <base-config>
Любое количество <domain-config>
0 или 1 из <debug-overrides>

<базовая-конфигурация>

синтаксис:

<base-config cleartextTrafficPermitted=["true" | "false"]>
    ...
</base-config>

может содержать:

<trust-anchors> <certificateTransparency>

описание:

Конфигурация по умолчанию, используемая всеми соединениями, назначение которых не указано в файле domain-config .

Любые значения, которые не заданы, используют значения платформы по умолчанию.

Конфигурация по умолчанию для приложений, ориентированных на Android 9 (уровень API 28) и выше, выглядит следующим образом:

<base-config cleartextTrafficPermitted="false">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

Конфигурация по умолчанию для приложений, ориентированных на Android 7.0 (уровень API 24) — Android 8.1 (уровень API 27), выглядит следующим образом:

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

Конфигурация по умолчанию для приложений, ориентированных на Android 6.0 (уровень API 23) и ниже, выглядит следующим образом:

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
        <certificates src="user" />
    </trust-anchors>
</base-config>

<конфигурация-домена>

синтаксис:

<domain-config cleartextTrafficPermitted=["true" | "false"]>
    ...
</domain-config>

может содержать:

1 или более <domain>
0 или 1 <certificateTransparency>
0 или 1 <trust-anchors> >
0 или 1 <pin-set> >
Любое количество вложенных <domain-config>

описание:

Конфигурация, используемая для подключений к определенным местам назначения, как определено элементами domain .

Обратите внимание: если несколько элементов domain-config охватывают пункт назначения, используется конфигурация с наиболее конкретным (самым длинным) соответствующим правилом домена.

<домен>

синтаксис:

<domain includeSubdomains=["true" | "false"]>example.com</domain>

атрибуты:

includeSubdomains

Если "true" , то это правило домена соответствует домену и всем субдоменам, включая субдомены субдоменов. В противном случае правило применяется только к точным совпадениям.

<сертификатПрозрачность>

синтаксис:

<certificateTransparency enabled=["true" | "false"]/>

описание:

Если true , приложение будет использовать журналы прозрачности сертификатов для проверки сертификатов. Когда приложение использует собственный сертификат (или хранилище пользователя), вполне вероятно, что сертификат не является общедоступным и, следовательно, не поддается проверке с использованием прозрачности сертификата. По умолчанию проверка в этих случаях отключена. Принудительно выполнить проверку по-прежнему можно, используя <certificateTransparency enabled="true"/> в конфигурации домена. Для каждого <domain-config> оценка выполняется в следующем порядке:

1. Если certificateTransparency включен, включите проверку.
2. Если какой-либо <trust-anchors> является "user" или встроенным (т. е. "@raw/cert.pem" ), отключите проверку.
3. В противном случае полагайтесь на унаследованную конфигурацию .

<переопределения-отладки>

синтаксис:

<debug-overrides>
    ...
</debug-overrides>

может содержать:

0 или 1 <trust-anchors> >

описание:

Переопределения, которые будут применяться, когда android:debuggable имеет значение "true" , что обычно имеет место для нерелизных сборок, созданных IDE и инструментами сборки. Якоря доверия, указанные в debug-overrides добавляются ко всем остальным конфигурациям, а закрепление сертификата не выполняется, если цепочка сертификатов сервера использует один из этих якорей доверия только для отладки. Если android:debuggable имеет значение "false" , то этот раздел полностью игнорируется.

<якоря доверия>

синтаксис:

<trust-anchors>
...
</trust-anchors>

может содержать:

Любое количество <certificates>

описание:

Набор якорей доверия для безопасных соединений.

<сертификаты>

синтаксис:

<certificates src=["system" | "user" | "raw resource"]
              overridePins=["true" | "false"] />

описание:

Набор сертификатов X.509 для элементов trust-anchors .

атрибуты:

src

Источник сертификатов CA. Каждый сертификат может быть одним из следующих:

• необработанный идентификатор ресурса, указывающий на файл, содержащий сертификаты X.509. Сертификаты должны быть закодированы в формате DER или PEM. В случае сертификатов PEM файл не должен содержать дополнительных данных, не относящихся к PEM, таких как комментарии.
• "system" для предустановленных системных сертификатов CA.
• "user" для сертификатов CA, добавленных пользователем.

overridePins

Указывает, обходят ли центры сертификации из этого источника закрепление сертификата. Если "true" , то закрепление не выполняется для цепочек сертификатов, подписанных одним из центров сертификации из этого источника. Это может быть полезно для отладки центров сертификации или для тестирования атак «человек посередине» на безопасный трафик вашего приложения.

Значение по умолчанию — "false" если не указано иное в элементе debug-overrides ; в этом случае значение по умолчанию — "true" .

<набор контактов>

синтаксис:

<pin-set expiration="date">
...
</pin-set>

может содержать:

Любое количество <pin>

описание:

Набор контактов открытого ключа. Чтобы безопасное соединение было надежным, один из открытых ключей в цепочке доверия должен находиться в наборе контактов. См. <pin> для получения информации о формате выводов.

атрибуты:

expiration

Дата в формате yyyy-MM-dd , когда истекает срок действия закреплений, что позволяет отключить закрепление. Если атрибут не установлен, срок действия контактов не истекает.

Срок действия помогает предотвратить проблемы с подключением в приложениях, которые не получают обновления своего набора контактов, например, когда пользователь отключает обновления приложений.

<булавка>

синтаксис:

<pin digest=["SHA-256"]>base64 encoded digest of X.509
    SubjectPublicKeyInfo (SPKI)</pin>

атрибуты:

digest

Алгоритм дайджеста, используемый для генерации вывода. В настоящее время поддерживается только "SHA-256" .

Функция конфигурации сетевой безопасности позволяет вам настроить параметры сетевой безопасности вашего приложения в безопасном декларативном файле конфигурации без изменения кода приложения. Эти параметры можно настроить для определенных доменов и для конкретного приложения. Ключевые возможности этой функции:

• Пользовательские якоря доверия. Настройте, каким центрам сертификации (CA) будут доверять безопасные соединения приложения. Например, доверяя определенным самозаверяющим сертификатам или ограничивая набор общедоступных центров сертификации, которым доверяет приложение.
• Переопределения только для отладки: безопасная отладка безопасных соединений в приложении без дополнительного риска для установленной базы.
• Отказ от трафика открытого текста: защитите приложения от случайного использования трафика открытого текста (незашифрованного).
• Согласие на прозрачность сертификатов: Ограничьте безопасные подключения приложения, используя доказуемо зарегистрированные сертификаты.
• Закрепление сертификата: Ограничьте безопасное соединение приложения определенными сертификатами.

Добавьте файл конфигурации сетевой безопасности

Функция конфигурации сетевой безопасности использует XML-файл, в котором вы указываете параметры своего приложения. Вы должны включить в манифест вашего приложения запись, указывающую на этот файл. Следующий фрагмент кода из манифеста демонстрирует, как создать эту запись:

<?xml version="1.0" encoding="utf-8"?>
<manifest ... >
    <application android:networkSecurityConfig="@xml/network_security_config"
                    ... >
        ...
    </application>
</manifest>

Настройка доверенных центров сертификации

Возможно, вы захотите, чтобы ваше приложение доверяло пользовательскому набору центров сертификации, а не стандартному набору центров сертификации. Наиболее распространенными причинами этого являются:

• Подключение к хосту с помощью специального центра сертификации, например центра сертификации, который является самоподписанным или выдан внутри компании.
• Ограничьте набор центров сертификации только теми центрами сертификации, которым вы доверяете, а не каждым предварительно установленным центром сертификации.
• Доверие дополнительным центрам сертификации, не включенным в систему.

По умолчанию безопасные соединения (с использованием таких протоколов, как TLS и HTTPS) всех приложений доверяют предустановленным системным центрам сертификации, а приложения, предназначенные для Android 6.0 (уровень API 23) и ниже, также по умолчанию доверяют добавленному пользователем хранилищу центров сертификации. Вы можете настроить соединения вашего приложения с помощью base-config (для настройки всего приложения) или domain-config (для настройки для каждого домена).

Настройка пользовательского центра сертификации

Возможно, вы захотите подключиться к хосту, который использует самозаверяющий сертификат SSL, или к хосту, сертификат SSL которого выдан закрытым центром сертификации, которому вы доверяете, например внутренним центром сертификации вашей компании. В следующем фрагменте кода показано, как настроить приложение для пользовательского центра сертификации в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

Добавьте самозаверяющий или закрытый сертификат CA в формате PEM или DER в res/raw/my_ca .

Ограничьте набор доверенных центров сертификации

Если вы не хотите, чтобы ваше приложение доверяло всем центрам сертификации, которым доверяет система, вместо этого вы можете указать сокращенный набор центров сертификации, которым можно доверять. Это защищает приложение от поддельных сертификатов, выданных любым другим центром сертификации.

Конфигурация ограничения набора доверенных центров сертификации аналогична настройке доверия пользовательскому центру сертификации для определенного домена, за исключением того, что в ресурсе предусмотрено несколько центров сертификации. В следующем фрагменте кода показано, как ограничить набор доверенных центров сертификации вашего приложения в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">secure.example.com</domain>
        <domain includeSubdomains="true">cdn.example.com</domain>
        <trust-anchors>
            <certificates src="@raw/trusted_roots"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

Добавьте доверенные центры сертификации в формате PEM или DER в res/raw/trusted_roots . Обратите внимание: если вы используете формат PEM, файл должен содержать только данные PEM и не содержать дополнительного текста. Вы также можете предоставить несколько элементов <certificates> вместо одного.

Доверяйте дополнительным центрам сертификации

Возможно, вы захотите, чтобы ваше приложение доверяло дополнительным центрам сертификации, которым не доверяет система, например, если система еще не включает центр сертификации или центр сертификации не соответствует требованиям для включения в систему Android. Вы можете указать несколько источников сертификатов для конфигурации в файле res/xml/network_security_config.xml используя код, подобный следующему фрагменту.

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <trust-anchors>
            <certificates src="@raw/extracas"/>
            <certificates src="system"/>
        </trust-anchors>
    </base-config>
</network-security-config>

Настройка центров сертификации для отладки

При отладке приложения, подключающегося через HTTPS, вам может потребоваться подключиться к локальному серверу разработки, у которого нет сертификата SSL для вашего рабочего сервера. Чтобы обеспечить это без каких-либо изменений в коде вашего приложения, вы можете указать центры сертификации только для отладки, которым доверяют только в том случае, если android:debuggable имеет true , с помощью debug-overrides . Обычно IDE и инструменты сборки автоматически устанавливают этот флаг для нерелизных сборок.

Это безопаснее, чем обычный условный код, поскольку в целях безопасности магазины приложений не принимают приложения, помеченные как отлаживаемые.

В приведенном ниже отрывке показано, как указать центры сертификации только для отладки в файле res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <debug-overrides>
        <trust-anchors>
            <certificates src="@raw/debug_cas"/>
        </trust-anchors>
    </debug-overrides>
</network-security-config>

Включите прозрачность сертификата

Примечание. Поддержка прозрачности сертификатов доступна только в Android 16 (уровень API 36).

Прозрачность сертификатов (CT, RFC 6962 ) — это Интернет-стандарт, разработанный для повышения безопасности цифровых сертификатов. Он требует от центров сертификации отправлять все выданные сертификаты в общедоступный журнал, в котором они фиксируются, что повышает прозрачность и подотчетность в процессе выдачи сертификатов.

Поддерживая проверяемый учет всех сертификатов, CT значительно затрудняет подделку сертификатов злоумышленниками или их ошибочную выдачу центрами сертификации. Это помогает защитить пользователей от атак «злоумышленник посередине» и других угроз безопасности. Для получения дополнительной информации см. объяснение на сайтеtransparency.dev . Дополнительную информацию о соответствии требованиям CT на Android см. в политике Android CT .

По умолчанию сертификаты принимаются независимо от того, зарегистрированы ли они в журнале CT. Чтобы ваше приложение подключалось только к местам назначения с сертификатами, зарегистрированными в журнале CT, вы можете включить эту функцию либо глобально , либо для каждого домена .

Отключить трафик открытого текста

Примечание. Рекомендации в этом разделе применимы только к приложениям, предназначенным для Android 8.1 (уровень API 27) или ниже. Начиная с Android 9 (уровень API 28), поддержка открытого текста отключена по умолчанию.

Если вы хотите, чтобы ваше приложение подключалось к местам назначения, используя только безопасные соединения, вы можете отказаться от поддержки открытого текста (с использованием незашифрованного протокола HTTP вместо HTTPS) для этих мест назначения. Этот параметр помогает предотвратить случайные регрессии в приложениях из-за изменений URL-адресов, предоставленных внешними источниками, такими как внутренние серверы. Дополнительные сведения см. в разделе NetworkSecurityPolicy.isCleartextTrafficPermitted() .

Например, вы можете захотеть, чтобы ваше приложение гарантировало, что подключения к secure.example.com всегда выполняются через HTTPS, чтобы защитить конфиденциальный трафик от враждебных сетей.

В приведенном ниже отрывке показано, как отказаться от открытого текста в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="false">
        <domain includeSubdomains="true">secure.example.com</domain>
    </domain-config>
</network-security-config>

ПИН-сертификаты

Обычно приложение доверяет всем предустановленным центрам сертификации. Если бы какой-либо из этих центров сертификации выдал поддельный сертификат, приложение подверглось бы риску со стороны злоумышленника на пути. Некоторые приложения предпочитают ограничивать набор принимаемых сертификатов, ограничивая набор центров сертификации, которым они доверяют, или закрепляя сертификаты.

Закрепление сертификата осуществляется путем предоставления набора сертификатов по хешу открытого ключа ( SubjectPublicKeyInfo сертификата X.509). В этом случае цепочка сертификатов действительна только в том случае, если цепочка сертификатов содержит хотя бы один из закрепленных открытых ключей.

Обратите внимание, что при использовании закрепления сертификата вы всегда должны включать резервный ключ, чтобы, если вам придется переключиться на новые ключи или изменить центр сертификации (при закреплении сертификата центра сертификации или промежуточного центра этого центра сертификации), подключение вашего приложения не пострадало. В противном случае вам придется обновить приложение, чтобы восстановить соединение.

Дополнительно можно установить срок действия для булавок, по истечении которого закрепление не будет выполняться. Это помогает предотвратить проблемы с подключением в приложениях, которые не были обновлены. Однако установка срока действия для контактов может позволить злоумышленникам обойти ваши закрепленные сертификаты.

В приведенном ниже отрывке показано, как закрепить сертификаты в res/xml/network_security_config.xml :

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

Поведение наследования конфигурации

Значения, не заданные в конкретной конфигурации, наследуются. Такое поведение позволяет создавать более сложные конфигурации, сохраняя при этом файл конфигурации доступным для чтения.

Например, значения, не заданные в domain-config берутся из родительского domain-config , если он вложен, или из base-config , если нет. Значения, не заданные в base-config используют значения платформы по умолчанию.

Например, рассмотрим случай, когда все подключения к субдоменам example.com должны использовать специальный набор центров сертификации. Кроме того, трафик в открытом виде к этим доменам разрешен, за исключением случаев подключения к secure.example.com . Если вложить конфигурацию secure.example.com в конфигурацию example.com , нет необходимости дублировать trust-anchors .

В приведенном ниже отрывке показано, как это вложение будет выглядеть в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
        <domain-config cleartextTrafficPermitted="false">
            <domain includeSubdomains="true">secure.example.com</domain>
        </domain-config>
    </domain-config>
</network-security-config>

Формат файла конфигурации

Функция конфигурации сетевой безопасности использует формат файла XML. Общая структура файла показана в следующем примере кода:

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

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

В следующих разделах описываются синтаксис и другие детали формата файла.

<конфигурация-сети-безопасности>

может содержать:

0 или 1 из <base-config>
Любое количество <domain-config>
0 или 1 из <debug-overrides>

<базовая-конфигурация>

синтаксис:

<base-config cleartextTrafficPermitted=["true" | "false"]>
    ...
</base-config>

может содержать:

<trust-anchors> <certificateTransparency>

описание:

Конфигурация по умолчанию, используемая всеми соединениями, назначение которых не указано в файле domain-config .

Любые значения, которые не заданы, используют значения платформы по умолчанию.

Конфигурация по умолчанию для приложений, ориентированных на Android 9 (уровень API 28) и выше, выглядит следующим образом:

<base-config cleartextTrafficPermitted="false">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

Конфигурация по умолчанию для приложений, ориентированных на Android 7.0 (уровень API 24) — Android 8.1 (уровень API 27), выглядит следующим образом:

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

Конфигурация по умолчанию для приложений, ориентированных на Android 6.0 (уровень API 23) и ниже, выглядит следующим образом:

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
        <certificates src="user" />
    </trust-anchors>
</base-config>

<конфигурация-домена>

синтаксис:

<domain-config cleartextTrafficPermitted=["true" | "false"]>
    ...
</domain-config>

может содержать:

1 или более <domain>
0 или 1 <certificateTransparency>
0 или 1 <trust-anchors> >
0 или 1 <pin-set> >
Любое количество вложенных <domain-config>

описание:

Конфигурация, используемая для подключений к определенным местам назначения, как определено элементами domain .

Обратите внимание: если несколько элементов domain-config охватывают пункт назначения, используется конфигурация с наиболее конкретным (самым длинным) соответствующим правилом домена.

<домен>

синтаксис:

<domain includeSubdomains=["true" | "false"]>example.com</domain>

атрибуты:

includeSubdomains

Если "true" , то это правило домена соответствует домену и всем субдоменам, включая субдомены субдоменов. В противном случае правило применяется только к точным совпадениям.

<сертификатПрозрачность>

синтаксис:

<certificateTransparency enabled=["true" | "false"]/>

описание:

Если true , приложение будет использовать журналы прозрачности сертификатов для проверки сертификатов. Когда приложение использует собственный сертификат (или хранилище пользователя), вполне вероятно, что сертификат не является общедоступным и, следовательно, не поддается проверке с использованием прозрачности сертификата. По умолчанию проверка в этих случаях отключена. Принудительно выполнить проверку по-прежнему можно, используя <certificateTransparency enabled="true"/> в конфигурации домена. Для каждого <domain-config> оценка выполняется в следующем порядке:

1. Если certificateTransparency включен, включите проверку.
2. Если какой-либо <trust-anchors> является "user" или встроенным (т. е. "@raw/cert.pem" ), отключите проверку.
3. В противном случае полагайтесь на унаследованную конфигурацию .

<переопределения-отладки>

синтаксис:

<debug-overrides>
    ...
</debug-overrides>

может содержать:

0 или 1 <trust-anchors> >

описание:

Переопределения, которые будут применяться, когда android:debuggable имеет значение "true" , что обычно имеет место для нерелизных сборок, созданных IDE и инструментами сборки. Якоря доверия, указанные в debug-overrides добавляются ко всем остальным конфигурациям, а закрепление сертификата не выполняется, если цепочка сертификатов сервера использует один из этих якорей доверия только для отладки. Если android:debuggable имеет значение "false" , то этот раздел полностью игнорируется.

<якоря доверия>

синтаксис:

<trust-anchors>
...
</trust-anchors>

может содержать:

Любое количество <certificates>

описание:

Набор якорей доверия для безопасных соединений.

<сертификаты>

синтаксис:

<certificates src=["system" | "user" | "raw resource"]
              overridePins=["true" | "false"] />

описание:

Набор сертификатов X.509 для элементов trust-anchors .

атрибуты:

src

Источник сертификатов CA. Каждый сертификат может быть одним из следующих:

• необработанный идентификатор ресурса, указывающий на файл, содержащий сертификаты X.509. Сертификаты должны быть закодированы в формате DER или PEM. В случае сертификатов PEM файл не должен содержать дополнительных данных, не относящихся к PEM, таких как комментарии.
• "system" для предустановленных системных сертификатов CA.
• "user" для сертификатов CA, добавленных пользователем.

overridePins

Указывает, обходят ли центры сертификации из этого источника закрепление сертификата. Если "true" , то закрепление не выполняется для цепочек сертификатов, подписанных одним из центров сертификации из этого источника. Это может быть полезно для отладки центров сертификации или для тестирования атак «человек посередине» на безопасный трафик вашего приложения.

Значение по умолчанию — "false" если не указано иное в элементе debug-overrides ; в этом случае значение по умолчанию — "true" .

<набор контактов>

синтаксис:

<pin-set expiration="date">
...
</pin-set>

может содержать:

Любое количество <pin>

описание:

Набор контактов открытого ключа. Чтобы безопасное соединение было надежным, один из открытых ключей в цепочке доверия должен находиться в наборе контактов. См. <pin> для получения информации о формате выводов.

атрибуты:

expiration

Дата в формате yyyy-MM-dd , когда истекает срок действия закреплений, что позволяет отключить закрепление. Если атрибут не установлен, срок действия контактов не истекает.

Срок действия помогает предотвратить проблемы с подключением в приложениях, которые не получают обновления своего набора контактов, например, когда пользователь отключает обновления приложений.

<булавка>

синтаксис:

<pin digest=["SHA-256"]>base64 encoded digest of X.509
    SubjectPublicKeyInfo (SPKI)</pin>

атрибуты:

digest

Алгоритм дайджеста, используемый для генерации вывода. В настоящее время поддерживается только "SHA-256" .

Функция конфигурации сетевой безопасности позволяет вам настроить параметры сетевой безопасности вашего приложения в безопасном декларативном файле конфигурации без изменения кода приложения. Эти параметры можно настроить для определенных доменов и для конкретного приложения. Ключевые возможности этой функции:

• Пользовательские якоря доверия. Настройте, каким центрам сертификации (CA) будут доверять безопасные соединения приложения. Например, доверяя определенным самозаверяющим сертификатам или ограничивая набор общедоступных центров сертификации, которым доверяет приложение.
• Переопределения только для отладки: безопасная отладка безопасных соединений в приложении без дополнительного риска для установленной базы.
• Отказ от трафика открытого текста: защитите приложения от случайного использования трафика открытого текста (незашифрованного).
• Согласие на прозрачность сертификатов: Ограничьте безопасные подключения приложения, используя доказуемо зарегистрированные сертификаты.
• Закрепление сертификата: Ограничьте безопасное соединение приложения определенными сертификатами.

Добавьте файл конфигурации сетевой безопасности

Функция конфигурации сетевой безопасности использует XML-файл, в котором вы указываете параметры своего приложения. Вы должны включить в манифест вашего приложения запись, указывающую на этот файл. Следующий фрагмент кода из манифеста демонстрирует, как создать эту запись:

<?xml version="1.0" encoding="utf-8"?>
<manifest ... >
    <application android:networkSecurityConfig="@xml/network_security_config"
                    ... >
        ...
    </application>
</manifest>

Настройка доверенных центров сертификации

Возможно, вы захотите, чтобы ваше приложение доверяло пользовательскому набору центров сертификации, а не стандартному набору центров сертификации. Наиболее распространенными причинами этого являются:

• Подключение к хосту с помощью специального центра сертификации, например центра сертификации, который является самоподписанным или выдан внутри компании.
• Ограничьте набор центров сертификации только теми центрами сертификации, которым вы доверяете, а не каждым предварительно установленным центром сертификации.
• Доверие дополнительным центрам сертификации, не включенным в систему.

По умолчанию безопасные соединения (с использованием таких протоколов, как TLS и HTTPS) всех приложений доверяют предустановленным системным центрам сертификации, а приложения, предназначенные для Android 6.0 (уровень API 23) и ниже, также по умолчанию доверяют добавленному пользователем хранилищу центров сертификации. Вы можете настроить соединения вашего приложения с помощью base-config (для настройки всего приложения) или domain-config (для настройки для каждого домена).

Настройка пользовательского центра сертификации

Возможно, вы захотите подключиться к хосту, который использует самозаверяющий сертификат SSL, или к хосту, сертификат SSL которого выдан закрытым центром сертификации, которому вы доверяете, например внутренним центром сертификации вашей компании. В следующем фрагменте кода показано, как настроить приложение для пользовательского центра сертификации в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

Добавьте самозаверяющий или закрытый сертификат CA в формате PEM или DER в res/raw/my_ca .

Ограничьте набор доверенных центров сертификации

Если вы не хотите, чтобы ваше приложение доверяло всем центрам сертификации, которым доверяет система, вместо этого вы можете указать сокращенный набор центров сертификации, которым можно доверять. Это защищает приложение от поддельных сертификатов, выданных любым другим центром сертификации.

Конфигурация ограничения набора доверенных центров сертификации аналогична настройке доверия пользовательскому центру сертификации для определенного домена, за исключением того, что в ресурсе предусмотрено несколько центров сертификации. В следующем фрагменте кода показано, как ограничить набор доверенных центров сертификации вашего приложения в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">secure.example.com</domain>
        <domain includeSubdomains="true">cdn.example.com</domain>
        <trust-anchors>
            <certificates src="@raw/trusted_roots"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

Добавьте доверенные центры сертификации в формате PEM или DER в res/raw/trusted_roots . Обратите внимание: если вы используете формат PEM, файл должен содержать только данные PEM и не содержать дополнительного текста. Вы также можете предоставить несколько элементов <certificates> вместо одного.

Доверяйте дополнительным центрам сертификации

Возможно, вы захотите, чтобы ваше приложение доверяло дополнительным центрам сертификации, которым не доверяет система, например, если система еще не включает центр сертификации или центр сертификации не соответствует требованиям для включения в систему Android. Вы можете указать несколько источников сертификатов для конфигурации в файле res/xml/network_security_config.xml используя код, подобный следующему фрагменту.

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <trust-anchors>
            <certificates src="@raw/extracas"/>
            <certificates src="system"/>
        </trust-anchors>
    </base-config>
</network-security-config>

Настройка центров сертификации для отладки

При отладке приложения, подключающегося через HTTPS, вам может потребоваться подключиться к локальному серверу разработки, у которого нет сертификата SSL для вашего рабочего сервера. Чтобы обеспечить это без каких-либо изменений в коде вашего приложения, вы можете указать центры сертификации только для отладки, которым доверяют только в том случае, если android:debuggable имеет true , с помощью debug-overrides . Обычно IDE и инструменты сборки автоматически устанавливают этот флаг для нерелизных сборок.

Это безопаснее, чем обычный условный код, поскольку в целях безопасности магазины приложений не принимают приложения, помеченные как отлаживаемые.

В приведенном ниже отрывке показано, как указать центры сертификации только для отладки в файле res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <debug-overrides>
        <trust-anchors>
            <certificates src="@raw/debug_cas"/>
        </trust-anchors>
    </debug-overrides>
</network-security-config>

Включите прозрачность сертификата

Примечание. Поддержка прозрачности сертификатов доступна только в Android 16 (уровень API 36).

Прозрачность сертификатов (CT, RFC 6962 ) — это Интернет-стандарт, разработанный для повышения безопасности цифровых сертификатов. Он требует от центров сертификации отправлять все выданные сертификаты в общедоступный журнал, в котором они фиксируются, что повышает прозрачность и подотчетность в процессе выдачи сертификатов.

Поддерживая проверяемый учет всех сертификатов, CT значительно затрудняет подделку сертификатов злоумышленниками или их ошибочную выдачу центрами сертификации. Это помогает защитить пользователей от атак «злоумышленник посередине» и других угроз безопасности. Для получения дополнительной информации см. объяснение на сайтеtransparency.dev . Дополнительную информацию о соответствии требованиям CT на Android см. в политике Android CT .

По умолчанию сертификаты принимаются независимо от того, зарегистрированы ли они в журнале CT. Чтобы ваше приложение подключалось только к местам назначения с сертификатами, зарегистрированными в журнале CT, вы можете включить эту функцию либо глобально , либо для каждого домена .

Отключить трафик открытого текста

Примечание. Рекомендации в этом разделе применимы только к приложениям, предназначенным для Android 8.1 (уровень API 27) или ниже. Начиная с Android 9 (уровень API 28), поддержка открытого текста отключена по умолчанию.

Если вы хотите, чтобы ваше приложение подключалось к местам назначения, используя только безопасные соединения, вы можете отказаться от поддержки открытого текста (с использованием незашифрованного протокола HTTP вместо HTTPS) для этих мест назначения. Этот параметр помогает предотвратить случайные регрессии в приложениях из-за изменений URL-адресов, предоставленных внешними источниками, такими как внутренние серверы. Дополнительные сведения см. в разделе NetworkSecurityPolicy.isCleartextTrafficPermitted() .

Например, вы можете хотеть, чтобы ваше приложение гарантировало, что соединения в secure.example.com всегда выполняются по HTTPS, чтобы защитить конфиденциальное трафик от враждебных сетей.

Выдержка ниже показывает, как отказаться от ClearText в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="false">
        <domain includeSubdomains="true">secure.example.com</domain>
    </domain-config>
</network-security-config>

Сертификаты

Обычно приложение доверяет всем предварительно установленным CAS. Если бы какой-либо из этих CAS выпустил мошеннический сертификат, приложение будет подвергаться риску со стороны нападавшего в пути. Некоторые приложения предпочитают ограничить набор сертификатов, которые они принимают, либо ограничивая набор CAS, которые они доверяют, или сертификатом.

Закрепление сертификата выполняется путем предоставления набора сертификатов по хешу открытого ключа ( SubjectPublicKeyInfo сертификата X.509). Цепочка сертификатов действительна только в том случае, если цепочка сертификатов содержит как минимум один из закрепленных общественных ключей.

Обратите внимание, что при использовании закрепления сертификата вы всегда должны включать клавишу резервного копирования, чтобы, если вы вынуждены переключаться на новые клавиши или изменить CAS (при закреплении сертификата CA или промежуточное соединение этого CA), подключение вашего приложения не зависит от. В противном случае вы должны выдвинуть обновление приложения для восстановления подключения.

Кроме того, можно установить время истечения для выводов, после чего не выполняется закрепление. Это помогает предотвратить проблемы с подключением в приложениях, которые не были обновлены. Тем не менее, установление времени истечения срока действия на выводах может позволить злоумышленникам обойти ваши прикрепленные сертификаты.

Выдержка ниже показывает, как прикреплять сертификаты в res/xml/network_security_config.xml :

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

Поведение наследования конфигурации

Значения, не установленные в определенной конфигурации, унаследованы. Такое поведение обеспечивает более сложные конфигурации при сохранении читаемого файла конфигурации.

Например, значения, не установленные в domain-config , взяты из родительского domain-config , если вложенные или из base-config , если нет. Значения, не установленные в base-config используют значения платформы по умолчанию.

Например, рассмотрим случай, когда все соединения с субдоменом example.com должны использовать пользовательский набор CAS. Кроме того, разрешен трафик Clartext в эти домены, за исключением случаев, когда подключение к secure.example.com . Гнездывая конфигурацию для secure.example.com внутри конфигурации, example.com trust-anchors

Выдержка ниже показывает, как это гнездование будет выглядеть в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
        <domain-config cleartextTrafficPermitted="false">
            <domain includeSubdomains="true">secure.example.com</domain>
        </domain-config>
    </domain-config>
</network-security-config>

Формат файла конфигурации

Функция конфигурации безопасности сети использует формат файла XML. Общая структура файла показана в следующем примере кода:

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

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

В следующих разделах описываются синтаксис и другие детали формата файла.

<сеть-безопасность-config>

может содержать:

0 или 1 из <base-config>
Любое количество <domain-config>
0 или 1 из <debug-overrides>

<base-config>

синтаксис:

<base-config cleartextTrafficPermitted=["true" | "false"]>
    ...
</base-config>

может содержать:

<trust-anchors> <certificateTransparency>

описание:

Конфигурация по умолчанию, используемая всеми соединениями, пункт назначения которых не покрывается domain-config .

Любые значения, которые не установлены, используют значения платформы по умолчанию.

Конфигурация по умолчанию для приложений, нацеленных на Android 9 (API -уровень 28) и выше, выглядит следующим образом:

<base-config cleartextTrafficPermitted="false">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

Конфигурация по умолчанию для приложений, нацеленных на Android 7.0 (уровень API 24) на Android 8.1 (уровень API 27) выглядит следующим образом:

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

Конфигурация по умолчанию для приложений, нацеленных на Android 6.0 (уровень 23) и ниже:

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
        <certificates src="user" />
    </trust-anchors>
</base-config>

<домен-конфиг>

синтаксис:

<domain-config cleartextTrafficPermitted=["true" | "false"]>
    ...
</domain-config>

может содержать:

1 или более <domain>
0 или 1 <certificateTransparency>
0 или 1 <trust-anchors>
0 или 1 <pin-set> >
Любое количество вложенного <domain-config>

описание:

Конфигурация, используемая для подключений к конкретным направлениям, как определено элементами domain .

Обратите внимание, что если используется несколько элементов domain-config доменного конфигурации, используется конфигурация с наиболее специфическим (самым длинным) соответствующим правилом домена.

<Домен>

синтаксис:

<domain includeSubdomains=["true" | "false"]>example.com</domain>

Атрибуты:

includeSubdomains

Если "true" , то это правило домена соответствует домену и всем субдоменам, включая субдомены субдоменов. В противном случае правило относится только к точным совпадениям.

<сертификат обращений>

синтаксис:

<certificateTransparency enabled=["true" | "false"]/>

описание:

Если true , то приложение будет использовать журналы прозрачности сертификата для проверки сертификатов. Когда приложение использует свой собственный сертификат (или магазин пользователей), вполне вероятно, что сертификат не является общедоступным и, следовательно, не поддается проверке, используя прозрачность сертификата. По умолчанию проверка отключена для этих случаев. По -прежнему возможно заставить проверку, используя <certificateTransparency enabled="true"/> в конфигурации домена. Для каждого <domain-config> оценка следует за этим порядком:

1. Если certificateTransparency включена, включите проверку.
2. Если какой-либо <trust-anchors> является "user" или встроенным (т.е. "@raw/cert.pem" ), отключите проверку.
3. В противном случае полагайтесь на наследственную конфигурацию .

<отладка-переверды>

синтаксис:

<debug-overrides>
    ...
</debug-overrides>

может содержать:

0 или 1 <trust-anchors>

описание:

Переопределения, которые должны применяться, когда Android: Regaintable является "true" , что обычно имеет место для неразрушающих сборки, генерируемых IDE и инструментами для сборки. Доверительные якоря, указанные в debug-overrides добавляются ко всем другим конфигурациям, а закрепление сертификатов не выполняется, когда цепочка сертификатов сертификата использует один из этих трастовых якорей только отладки. Если Android: Regaintable "false" , то этот раздел полностью игнорируется.

<доверие-ангоры>

синтаксис:

<trust-anchors>
...
</trust-anchors>

может содержать:

Любое количество <certificates>

описание:

Набор трастовых якорей для безопасных соединений.

<сертификаты>

синтаксис:

<certificates src=["system" | "user" | "raw resource"]
              overridePins=["true" | "false"] />

описание:

Набор сертификатов X.509 для элементов trust-anchors .

Атрибуты:

src

Источник сертификатов CA. Каждый сертификат может быть одним из следующих действий:

• необработанный идентификатор ресурса, указывающий на файл, содержащий сертификаты X.509. Сертификаты должны быть закодированы в формате DER или PEM. В случае сертификатов PEM в файл не должен содержать дополнительные данные, не являющиеся PEM, такие как комментарии.
• "system" для предварительно установленных системных сертификатов CA
• "user" для сертификатов CA с добавлением пользователя

overridePins

Указывает, если CAS из этого источника обходного сертификата. Если "true" , то закрепление не выполняется на сети сертификатов, которые подписаны одним из CAS из этого источника. Это может быть полезно для отладки CAS или для тестирования атак с человеком в среднем уровне на безопасном трафике вашего приложения.

По умолчанию является "false" если только не указан в элементе debug-overrides , и в этом случае по умолчанию по умолчанию является "true" .

<PIN-SET>

синтаксис:

<pin-set expiration="date">
...
</pin-set>

может содержать:

Любое количество <pin>

описание:

Набор открытых ключевых булавок. Чтобы надежно доверилось безопасное соединение, один из общественных ключей в цепочке доверия должен быть в наборе булавок. Смотрите <pin> для формата булавок.

Атрибуты:

expiration

Дата, в формате yyyy-MM-dd , на котором истекает штифты, что отключает прикрепление. Если атрибут не установлен, то контакты не истекают.

Срок годности помогает предотвратить проблемы с подключением в приложениях, которые не получают обновления для их набора PIN -кода, например, когда пользователь отключает обновления приложений.

<пин -пин>

синтаксис:

<pin digest=["SHA-256"]>base64 encoded digest of X.509
    SubjectPublicKeyInfo (SPKI)</pin>

Атрибуты:

digest

Алгоритм дайджеста, используемый для генерации вывода. В настоящее время поддерживается только "SHA-256" .

Функция конфигурации сети безопасности позволяет настроить настройки безопасности вашего приложения в безопасном, декларативном файле конфигурации без изменения кода приложения. Эти настройки могут быть настроены для конкретных доменов и для конкретного приложения. Ключевыми возможностями этой функции являются:

• Пользовательские трастовые якоря: настраивайте, какие сертификаты властям (CA) доверяют для безопасных соединений приложения. Например, доверие конкретных самопоглаживаемых сертификатов или ограничение набора общественных CAS, которым доверяет приложение.
• Переопределение только отладки: безопасно отлаживать безопасные соединения в приложении без добавления риска к установленной базе.
• Отказ от трафика CLEEXTEXT: Защитите приложения от случайного использования прозрачного текста (незашифрованного) трафика.
• Прозрачность сертификата. Обратите внимание: ограничить безопасные подключения приложения для использования доказуемо зарегистрированных сертификатов.
• Закрепление сертификата: ограничить безопасное соединение приложения с конкретными сертификатами.

Добавить файл конфигурации безопасности сети

Функция конфигурации сети безопасности использует файл XML, в котором вы указываете настройки для вашего приложения. Вы должны включить запись в манифест вашего приложения, чтобы указать на этот файл. Следующий выдержка из кода из манифеста демонстрирует, как создать эту запись:

<?xml version="1.0" encoding="utf-8"?>
<manifest ... >
    <application android:networkSecurityConfig="@xml/network_security_config"
                    ... >
        ...
    </application>
</manifest>

Настроить доверенный CAS

Вы можете захотить, чтобы ваше приложение доверяло пользовательскому набору CAS вместо платформы по умолчанию. Наиболее распространенными причинами этого являются:

• Подключение к хозяину с пользовательским CA, таким как CA, который самореагируется или выдается внутри компании.
• Ограничение набора CAS только для CAS, которым вы доверяете, а не каждому предварительно установленному CA.
• Доверяя дополнительным CAS, не включенному в систему.

По умолчанию безопасные подключения (с использованием протоколов, таких как TLS и HTTPS) из всех приложений, доверяют предварительно установленной системе CAS, и приложения, нацеленные на Android 6.0 (уровень 23) и более низкие, также доверяют добавленному пользователю магазину CA по умолчанию. Вы можете настроить подключения вашего приложения, используя base-config (для настройки приложения) или domain-config (для настройки для каждого домена).

Настройте пользовательский CA

Возможно, вы захотите подключиться к хозяину, который использует самореагированный сертификат SSL или к хосту, чей сертификат SSL выдается непубличным CA, которому вы доверяете, например, внутренний CA вашей компании. В следующем коде выдержка демонстрирует, как настроить ваше приложение для пользовательского CA в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

Добавьте самоопределенный или непубличный сертификат CA, в PEM или DER FORMAT, в res/raw/my_ca .

Ограничьте набор доверенных CAS

Если вы не хотите, чтобы ваше приложение доверяло всем CAS, которым доверяют систему, вы можете вместо этого указать сокращенный набор CAS для доверия. Это защищает приложение от мошеннических сертификатов, выпущенных любым другим CAS.

Конфигурация для ограничения набора доверенных CAS аналогична доверию пользовательского CA для определенного домена, за исключением того, что в ресурсе предоставляется несколько CAS. В следующем отрывке кода демонстрируется, как ограничить набор доверенных CAS вашего приложения в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">secure.example.com</domain>
        <domain includeSubdomains="true">cdn.example.com</domain>
        <trust-anchors>
            <certificates src="@raw/trusted_roots"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

Добавьте доверенный CAS, в формате PEM или DER, в res/raw/trusted_roots . Обратите внимание, что если вы используете формат PEM, файл должен содержать только данные PEM и отсутствие дополнительного текста. Вы также можете предоставить несколько элементов <certificates> вместо одного.

Доверьте дополнительных CAS

Вы можете хотеть, чтобы ваше приложение доверяло дополнительным CAS, которым не доверяют система, например, если система еще не включает CA или CA не соответствует требованиям для включения в систему Android. Вы можете указать несколько источников сертификата для конфигурации в res/xml/network_security_config.xml используя код, такой как следующая выдержка.

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <trust-anchors>
            <certificates src="@raw/extracas"/>
            <certificates src="system"/>
        </trust-anchors>
    </base-config>
</network-security-config>

Настройка CAS для отладки

При отладке приложения, которое подключается к HTTPS, вы можете подключиться к локальному серверу разработки, который не имеет сертификата SSL для вашего производственного сервера. Чтобы поддержать это без каких-либо изменений в коде вашего приложения, вы можете указать CAS только отладки, которым доверяют только тогда, когда Android: Regaintable true , используя debug-overrides . Обычно IDE и инструменты сборки устанавливают этот флаг автоматически для неразрешающих сборки.

Это безопаснее, чем обычный условный код, потому что, в качестве меры безопасности, магазины приложений не принимают приложения, которые отменяются.

Выдержка ниже показывает, как указать CAS только отладки в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <debug-overrides>
        <trust-anchors>
            <certificates src="@raw/debug_cas"/>
        </trust-anchors>
    </debug-overrides>
</network-security-config>

Выберите прозрачность сертификата

ПРИМЕЧАНИЕ. Поддержка прозрачности сертификата доступна только от Android 16 (уровень API 36).

Прозрачность сертификата (CT, RFC 6962 ) - это интернет -стандарт, предназначенный для повышения безопасности цифровых сертификатов. Это требует, чтобы CAS отправил все выпущенные сертификаты в публичный журнал, который их записывает, повышая прозрачность и подотчетность в процессе выпуска сертификатов.

Поддерживая проверяемую запись всех сертификатов, КТ делает для вредоносных актеров значительно труднее создавать сертификаты или CAS, чтобы ошибочно выпустить их. Это помогает защитить пользователей от атак человека в среднем и других угроз безопасности. Для получения дополнительной информации см. Объяснение по прозрачности .dev . Для получения дополнительной информации о соответствии КТ на Android, см. Политику CT Android .

По умолчанию сертификаты принимаются независимо от того, регистрируются ли они в журнале CT. Чтобы ваше приложение подключалось только к направлениям с сертификатами, зарегистрированными в журнале CT, вы можете выбрать эту функцию либо во всем мире , либо на основе для каждого домена .

Отказаться от прозрачного трафика

ПРИМЕЧАНИЕ. Руководство в этом разделе применяется только к приложениям, которые нацелены на Android 8.1 (уровень API 27) или ниже. Начиная с Android 9 (уровень API 28), поддержка Clartext отключена по умолчанию.

Если вы намереваетесь, чтобы ваше приложение подключилось к пунктам назначения, используя только безопасные подключения, вы можете отказаться от поддержки CLEEXTEXT (используя незашифрованный протокол HTTP вместо HTTP) в эти направления. Этот вариант помогает предотвратить случайные регрессии в приложениях из -за изменений в URL -адресах, предоставленных внешними источниками, такими как серверы бэкэнд. См. NetworkSecurityPolicy.isCleartextTrafficPermitted() для получения более подробной информации.

Например, вы можете хотеть, чтобы ваше приложение гарантировало, что соединения в secure.example.com всегда выполняются по HTTPS, чтобы защитить конфиденциальное трафик от враждебных сетей.

Выдержка ниже показывает, как отказаться от ClearText в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="false">
        <domain includeSubdomains="true">secure.example.com</domain>
    </domain-config>
</network-security-config>

Сертификаты

Обычно приложение доверяет всем предварительно установленным CAS. Если бы какой-либо из этих CAS выпустил мошеннический сертификат, приложение будет подвергаться риску со стороны нападавшего в пути. Некоторые приложения предпочитают ограничить набор сертификатов, которые они принимают, либо ограничивая набор CAS, которые они доверяют, или сертификатом.

Закрепление сертификата выполняется путем предоставления набора сертификатов по хешу открытого ключа ( SubjectPublicKeyInfo сертификата X.509). Цепочка сертификатов действительна только в том случае, если цепочка сертификатов содержит как минимум один из закрепленных общественных ключей.

Обратите внимание, что при использовании закрепления сертификата вы всегда должны включать клавишу резервного копирования, чтобы, если вы вынуждены переключаться на новые клавиши или изменить CAS (при закреплении сертификата CA или промежуточное соединение этого CA), подключение вашего приложения не зависит от. В противном случае вы должны выдвинуть обновление приложения для восстановления подключения.

Кроме того, можно установить время истечения для выводов, после чего не выполняется закрепление. Это помогает предотвратить проблемы с подключением в приложениях, которые не были обновлены. Тем не менее, установление времени истечения срока действия на выводах может позволить злоумышленникам обойти ваши прикрепленные сертификаты.

Выдержка ниже показывает, как прикреплять сертификаты в res/xml/network_security_config.xml :

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

Поведение наследования конфигурации

Значения, не установленные в определенной конфигурации, унаследованы. Такое поведение обеспечивает более сложные конфигурации при сохранении читаемого файла конфигурации.

Например, значения, не установленные в domain-config , взяты из родительского domain-config , если вложенные или из base-config , если нет. Значения, не установленные в base-config используют значения платформы по умолчанию.

Например, рассмотрим случай, когда все соединения с субдоменом example.com должны использовать пользовательский набор CAS. Кроме того, разрешен трафик Clartext в эти домены, за исключением случаев, когда подключение к secure.example.com . Гнездывая конфигурацию для secure.example.com внутри конфигурации, example.com trust-anchors

Выдержка ниже показывает, как это гнездование будет выглядеть в res/xml/network_security_config.xml :

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
        <domain-config cleartextTrafficPermitted="false">
            <domain includeSubdomains="true">secure.example.com</domain>
        </domain-config>
    </domain-config>
</network-security-config>

Формат файла конфигурации

Функция конфигурации безопасности сети использует формат файла XML. Общая структура файла показана в следующем примере кода:

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

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

В следующих разделах описываются синтаксис и другие детали формата файла.

<сеть-безопасность-config>

может содержать:

0 или 1 из <base-config>
Любое количество <domain-config>
0 или 1 из <debug-overrides>

<base-config>

синтаксис:

<base-config cleartextTrafficPermitted=["true" | "false"]>
    ...
</base-config>

может содержать:

<trust-anchors> <certificateTransparency>

описание:

Конфигурация по умолчанию, используемая всеми соединениями, пункт назначения которых не покрывается domain-config .

Любые значения, которые не установлены, используют значения платформы по умолчанию.

Конфигурация по умолчанию для приложений, нацеленных на Android 9 (API -уровень 28) и выше, выглядит следующим образом:

<base-config cleartextTrafficPermitted="false">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

Конфигурация по умолчанию для приложений, нацеленных на Android 7.0 (уровень API 24) на Android 8.1 (уровень API 27) выглядит следующим образом:

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

Конфигурация по умолчанию для приложений, нацеленных на Android 6.0 (уровень 23) и ниже:

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
        <certificates src="user" />
    </trust-anchors>
</base-config>

<домен-конфиг>

синтаксис:

<domain-config cleartextTrafficPermitted=["true" | "false"]>
    ...
</domain-config>

может содержать:

1 или более <domain>
0 или 1 <certificateTransparency>
0 или 1 <trust-anchors>
0 или 1 <pin-set> >
Любое количество вложенного <domain-config>

описание:

Конфигурация, используемая для подключений к конкретным направлениям, как определено элементами domain .

Обратите внимание, что если используется несколько элементов domain-config доменного конфигурации, используется конфигурация с наиболее специфическим (самым длинным) соответствующим правилом домена.

<Домен>

синтаксис:

<domain includeSubdomains=["true" | "false"]>example.com</domain>

Атрибуты:

includeSubdomains

Если "true" , то это правило домена соответствует домену и всем субдоменам, включая субдомены субдоменов. В противном случае правило относится только к точным совпадениям.

<сертификат обращений>

синтаксис:

<certificateTransparency enabled=["true" | "false"]/>

описание:

Если true , то приложение будет использовать журналы прозрачности сертификата для проверки сертификатов. Когда приложение использует свой собственный сертификат (или магазин пользователей), вполне вероятно, что сертификат не является общедоступным и, следовательно, не поддается проверке, используя прозрачность сертификата. По умолчанию проверка отключена для этих случаев. По -прежнему возможно заставить проверку, используя <certificateTransparency enabled="true"/> в конфигурации домена. Для каждого <domain-config> оценка следует за этим порядком:

1. Если certificateTransparency включена, включите проверку.
2. Если какой-либо <trust-anchors> является "user" или встроенным (т.е. "@raw/cert.pem" ), отключите проверку.
3. В противном случае полагайтесь на наследственную конфигурацию .

<отладка-переверды>

синтаксис:

<debug-overrides>
    ...
</debug-overrides>

может содержать:

0 или 1 <trust-anchors>

описание:

Переопределения, которые должны применяться, когда Android: Regaintable является "true" , что обычно имеет место для неразрушающих сборки, генерируемых IDE и инструментами для сборки. Доверительные якоря, указанные в debug-overrides добавляются ко всем другим конфигурациям, а закрепление сертификатов не выполняется, когда цепочка сертификатов сертификата использует один из этих трастовых якорей только отладки. Если Android: Regaintable "false" , то этот раздел полностью игнорируется.

<доверие-ангоры>

синтаксис:

<trust-anchors>
...
</trust-anchors>

может содержать:

Любое количество <certificates>

описание:

Набор трастовых якорей для безопасных соединений.

<сертификаты>

синтаксис:

<certificates src=["system" | "user" | "raw resource"]
              overridePins=["true" | "false"] />

описание:

Набор сертификатов X.509 для элементов trust-anchors .

Атрибуты:

src

Источник сертификатов CA. Каждый сертификат может быть одним из следующих действий:

• необработанный идентификатор ресурса, указывающий на файл, содержащий сертификаты X.509. Сертификаты должны быть закодированы в формате DER или PEM. В случае сертификатов PEM в файл не должен содержать дополнительные данные, не являющиеся PEM, такие как комментарии.
• "system" для предварительно установленных системных сертификатов CA
• "user" для сертификатов CA с добавлением пользователя

overridePins

Указывает, если CAS из этого источника обходного сертификата. Если "true" , то закрепление не выполняется на сети сертификатов, которые подписаны одним из CAS из этого источника. Это может быть полезно для отладки CAS или для тестирования атак с человеком в среднем уровне на безопасном трафике вашего приложения.

По умолчанию является "false" если только не указан в элементе debug-overrides , и в этом случае по умолчанию по умолчанию является "true" .

<PIN-SET>

синтаксис:

<pin-set expiration="date">
...
</pin-set>

может содержать:

Любое количество <pin>

описание:

Набор открытых ключевых булавок. Чтобы надежно доверилось безопасное соединение, один из общественных ключей в цепочке доверия должен быть в наборе булавок. Смотрите <pin> для формата булавок.

Атрибуты:

expiration

Дата, в формате yyyy-MM-dd , на котором истекает штифты, что отключает прикрепление. Если атрибут не установлен, то контакты не истекают.

Срок годности помогает предотвратить проблемы с подключением в приложениях, которые не получают обновления для их набора PIN -кода, например, когда пользователь отключает обновления приложений.

<пин -пин>

синтаксис:

<pin digest=["SHA-256"]>base64 encoded digest of X.509
    SubjectPublicKeyInfo (SPKI)</pin>

Атрибуты:

digest

Алгоритм дайджеста, используемый для генерации вывода. В настоящее время поддерживается только "SHA-256" .