Как установить сертификаты безопасности для API?

Текущие TLS-сертификаты T-API могут быть отозваны — в таком случае T-API будет переведен на сертификат Минцифры. Если не выполнить настройку заранее, в момент переключения сертификатов запросы к API будут возвращать ошибку проверки TLS-сертификата (certificate verify failed, unable to get local issuer certificate, PKIX path building failed) и интеграция перестанет работать.

mTLS-сертификаты продолжают работать — с ними ничего делать не нужно.

Зачем это нужно

CA/Browser Forum — международная организация, в которую входят крупнейшие центры сертификации и компании, разрабатывающие браузеры, например Google, Apple, Microsoft, Mozilla. CA/Browser Forum ужесточила правила проверки организаций — сертификаты GlobalSign, которые банк использует сейчас, пока действительны, но могут быть отозваны.

Когда это произойдет, банк перейдет на сертификаты Национального удостоверяющего центра Минцифры России (Russian Trusted CA). Рекомендуем выполнить настройку заранее, чтобы переключение прошло для вас незаметно.

Сертификаты Минцифры не входят в доверенные хранилища большинства операционных систем, языковых рантаймов и HTTP-библиотек по умолчанию. Поскольку ваш код обращается к API программно, а не через браузер, добавьте сертификаты в trust store серверного окружения, из которого выполняются запросы.

Вам нужно установить два сертификата:

  • Russian Trusted Root CA — корневой;
  • Russian Trusted Sub CA — промежуточный.

Ключевые различия TLS и mTLS

TLS (Transport Layer Security) — сертификат, который обеспечивает шифрование данных между клиентом и сервером. Когда вы открываете сайт по HTTPS, браузер устанавливает TLS-соединение с сервером. Аутентификация односторонняя — сервер предъявляет клиенту сертификат, клиент проверяет его по цепочке доверия (через корневые сертификаты, встроенные в операционную систему или браузер) и убеждается, что соединение установлено именно с тем сервером, за который он себя выдает. 

Сертификат можно установить вручную или установить Яндекс Браузер — в нем они есть по умолчанию.

mTLS (mutual TLS, взаимный TLS) — этот сертификат выпускается в личном кабинете Т-Бизнеса. Тот же протокол TLS, но с дополнительным шагом: сервер запрашивает и проверяет сертификат клиента. Аутентификация становится двусторонней.

 

TLS

mTLS

Кто предъявляет сертификат

Только сервер

Сервер и клиент

Что подтверждается

Подлинность сервера

Подлинность сервера и клиента

Аутентификация клиента

На уровне приложения — логин/пароль, токен, API-ключ

На уровне транспорта, до начала работы приложения

Сертификаты клиента

Не нужны

Требуется отдельный клиентский сертификат

Типичное применение

Публичные сайты, открытые API

Межсервисное взаимодействие, банковские и платежные интеграции, доступ к закрытым API

Сложность настройки

Низкая

Выше: нужно выпускать, хранить и обновлять сертификаты на стороне клиента

Шаг 1. Скачайте сертификаты

Скачайте сертификаты с портала госуслуг. На странице перейдите в раздел для вашей операционной системы и скачайте два файла:

  • russian_trusted_root_ca.cer — корневой сертификат;
  • russian_trusted_sub_ca.cer — промежуточный сертификат.

Проверьте формат файла сертификата. Файлы .cer бывают двух форматов: 

  • текстового — PEM, он начинается с -----BEGIN CERTIFICATE-----;
  • бинарного — DER. 

Утилиты update-ca-certificates и keytool принимают только PEM. Поэтому DER-файл нужно сконвертировать в PEM:

Шаг 2. Установите сертификаты для вашего окружения

Если окружений несколько, например JVM-приложение в Docker, выполните настройку для каждого из них:

Сертификаты для Linux

Если окружений несколько, например JVM-приложение в Docker, выполните настройку для каждого из них.

Для Linux (Debian / Ubuntu)

Для Linux (RHEL / CentOS / Alma / Rocky)

Сертификаты для Java / JVM

JVM не использует системное хранилище ОС. Рекомендуем создать отдельный truststore, а не изменять cacerts внутри JRE. Изменения в cacerts сбрасываются при обновлении JDK, а в prod-среде на запись в этот файл часто нет прав.

Укажите truststore при запуске приложения:

Отдельный truststore не наследует системные доверенные CA — он содержит только явно добавленные сертификаты. Если приложению нужно доверять одновременно публичным CA и сертификатам Минцифры, импортируйте сертификаты Минцифры в копию стандартного cacerts и используйте ее или добавьте все необходимые корневые сертификаты в truststore.

Путь к стандартному хранилищу зависит от версии JDK: 

Java 8 — $JAVA_HOME/jre/lib/security/cacerts; 

Java 9+ — $JAVA_HOME/lib/security/cacerts.

Сертификаты для Python (requests / httpx / aiohttp)

Эти библиотеки используют bundle certifi, а не системное хранилище. Доступны два варианта:

  • через переменные окружения (действуют на весь процесс):
  • явно в коде:

Сертификаты для Node.js и Docker

Node.js по умолчанию игнорирует системное хранилище:

Для Docker добавляйте сертификаты на этапе сборки образа, а не в рантайме:

Сертификаты для Windows, .NET и IIS

.NET использует системное хранилище сертификатов Windows. Для установки в хранилище LocalMachine, которое используется сервисами и приложениями, работающими не от имени текущего пользователя, выполните команды:

Корневой сертификат устанавливается в хранилище Root (доверенные корневые CA), промежуточный — в CA (промежуточные CA). То же самое можно сделать через GUI в certlm.msc. После установки перезапустите пул приложений или сервис.

Шаг 3. Проверьте установку

Если в выводе команд сейчас отображается сертификат GlobalSign — переключения еще не было и банк использует действующий сертификат. Цепочка сменится автоматически в момент перехода. Убедитесь, что в выводе есть SSL certificate verify ok и сертификаты Минцифры уже установлены в вашем окружении.

После установки сертификатов пересоберите и перезапустите сервисы в контейнерах, чтобы изменения вступили в силу.

Что делать, если возникли проблемы

Проблема

Причина

Решение

unable to get local issuer certificate

Не установлен промежуточный сертификат (Sub CA)

Установить оба сертификата

Ошибка сохраняется после update-ca-certificates

Python/Node.js используют собственный bundle

Задать переменные REQUESTS_CA_BUNDLE / NODE_EXTRA_CA_CERTS

В Docker все падает в рантайме

Сертификат добавлен после сборки

Добавить сертификат на этапе build и пересобрать образ

Работает локально, падает в production

Разные окружения или разные truststore

Выполнить настройку в каждом окружении

update-ca-certificates отработал, но CA не доверяется

Файл в формате DER вместо PEM

Сконвертировать: openssl x509 -inform DER -in cert.cer -out cert.pem

Соединение отклонено при корректно установленном CA

Включен certificate pinning

Обновить pin на новый сертификат

При проверке возвращается не тот сертификат

Не передан SNI

Добавить флаг -servername <домен> в команду openssl s_client

При проверке возвращается сертификат GlobalSign / другой УЦ

Переключение еще не произошло

Это нормально — сейчас используется действующий сертификат GlobalSign. Цепочка сменится автоматически в момент переключения. Убедитесь, что сертификаты Минцифры уже установлены

Как откатить изменения

Если после установки возникли проблемы, удалите добавленные сертификаты:

Как установить сертификаты для 1С: ДиректБанк

Чтобы сервис 1С «Интеграция» (1С:ДиректБанк) работал без сбоев и безопасно, установите сертификаты Национального удостоверяющего центра Минцифры России на свои устройства. Также обновите программу 1С:

  • На компьютере: установите патч 1С № EF_00_00484604.
  • Для мобильных устройств: обновите приложение «1С:Мобильная бухгалтерия» до версии 1.0.102 или выше (на платформе 8.3.21 и новее).

После этого все будет работать стабильно и безопасно.