Как установить сертификаты безопасности для API?
Текущие
Когда это произойдет, банк перейдет на сертификаты Национального удостоверяющего центра Минцифры России (Russian Trusted CA). Рекомендуем выполнить настройку заранее, чтобы переключение прошло для вас незаметно.
Сертификаты Минцифры не входят в доверенные хранилища большинства операционных систем, языковых рантаймов и
Вам нужно установить два сертификата:
TLS (Transport Layer Security) — сертификат, который обеспечивает шифрование данных между клиентом и сервером. Когда вы открываете сайт по HTTPS, браузер устанавливает
Сертификат можно установить вручную или установить Яндекс Браузер — в нем они есть по умолчанию.
mTLS (mutual TLS, взаимный TLS) — этот сертификат выпускается в личном кабинете
TLS | mTLS | |
|---|---|---|
Кто предъявляет сертификат | Только сервер | Сервер и клиент |
Что подтверждается | Подлинность сервера | Подлинность сервера и клиента |
Аутентификация клиента | На уровне приложения — | На уровне транспорта, до начала работы приложения |
Сертификаты клиента | Не нужны | Требуется отдельный клиентский сертификат |
Типичное применение | Публичные сайты, открытые API | Межсервисное взаимодействие, банковские и платежные интеграции, доступ к закрытым API |
Сложность настройки | Низкая | Выше: нужно выпускать, хранить и обновлять сертификаты на стороне клиента |
Скачайте сертификаты с портала госуслуг. На странице перейдите в раздел для вашей операционной системы и скачайте два файла:
Проверьте формат файла сертификата. Файлы .cer бывают двух форматов:
Утилиты
# Проверить формат
openssl x509 -in cert.cer -noout -text >/
# Конвертировать DER в PEM
openssl x509 -inform DER -in cert.cer -out cert.pem
Если окружений несколько, например
Если окружений несколько, например
Для Linux (Debian / Ubuntu)
sudo cp russian_trusted_root_ca.pem /
sudo cp russian_trusted_sub_ca.pem /
sudo
Для Linux (RHEL / CentOS / Alma / Rocky)
sudo cp russian_trusted_*.pem /
sudo
JVM не использует системное хранилище ОС. Рекомендуем создать отдельный truststore, а не изменять cacerts внутри JRE. Изменения в cacerts сбрасываются при обновлении JDK, а в
# Создать отдельный truststore и импортировать оба сертификата
keytool -importcert -alias russian_trusted_root \
-file russian_trusted_root_ca.pem \
-keystore russian_truststore.jks \
-storepass <пароль> -noprompt
keytool -importcert -alias russian_trusted_sub \
-file russian_trusted_sub_ca.pem \
-keystore russian_truststore.jks \
-storepass <пароль> -noprompt
Укажите truststore при запуске приложения:
java -Djavax.net.ssl.trustStore=/
-Djavax.net.ssl.trustStorePassword=<пароль> \
-jar app.jar
Отдельный truststore не наследует системные доверенные CA — он содержит только явно добавленные сертификаты. Если приложению нужно доверять одновременно публичным CA и сертификатам Минцифры, импортируйте сертификаты Минцифры в копию стандартного cacerts и используйте ее или добавьте все необходимые корневые сертификаты в truststore.
Путь к стандартному хранилищу зависит от версии JDK:
Java 8 — $JAVA_
Java 9+ — $JAVA_
Эти библиотеки используют bundle certifi, а не системное хранилище. Доступны два варианта:
export REQUESTS_CA_BUNDLE=/
export SSL_CERT_FILE=/
import requests
requests.get ("<домен_
Node.js по умолчанию игнорирует системное хранилище:
NODE_EXTRA_CA_CERTS=/
Для Docker добавляйте сертификаты на этапе сборки образа, а не в рантайме:
COPY
RUN
# Для Node.js и Python внутри контейнера задайте переменные окружения:
ENV NODE_EXTRA_CA_CERTS=/
ENV REQUESTS_CA_BUNDLE=/
.NET использует системное хранилище сертификатов Windows. Для установки в хранилище LocalMachine, которое используется сервисами и приложениями, работающими не от имени текущего пользователя, выполните команды:
# PowerShell с правами администратора
-CertStoreLocation Cert:\LocalMachine\Root
-CertStoreLocation Cert:\LocalMachine\CA
Корневой сертификат устанавливается в хранилище Root (доверенные корневые CA), промежуточный — в CA (промежуточные CA). То же самое можно сделать через GUI в certlm.msc. После установки перезапустите пул приложений или сервис.
curl -v https://mddc.tbank.ru/
# Ожидаемый результат: SSL certificate verify ok
openssl s_client -connect mddc.tbank.ru:443 -servername mddc.tbank.ru -showcerts </
# Флаг -servername (SNI) обязателен: без него на
# В цепочке должны присутствовать Russian Trusted Root CA и Russian Trusted Sub CA.
# Проверить срок действия установленного сертификата
echo | openssl s_client -connect mddc.tbank.ru:443 -servername securepay.tinkoff.ru 2>/
| openssl x509 -noout -dates
Если в выводе команд сейчас отображается сертификат GlobalSign — переключения еще не было и банк использует действующий сертификат. Цепочка сменится автоматически в момент перехода. Убедитесь, что в выводе есть SSL certificate verify ok и сертификаты Минцифры уже установлены в вашем окружении.
После установки сертификатов пересоберите и перезапустите сервисы в контейнерах, чтобы изменения вступили в силу.
Проблема | Причина | Решение |
|---|---|---|
unable to get local issuer certificate | Не установлен промежуточный сертификат (Sub CA) | Установить оба сертификата |
Ошибка сохраняется после | Задать переменные REQUESTS_CA_BUNDLE / NODE_EXTRA_CA_CERTS | |
В Docker все падает в рантайме | Сертификат добавлен после сборки | Добавить сертификат на этапе build и пересобрать образ |
Работает локально, падает в production | Разные окружения или разные truststore | Выполнить настройку в каждом окружении |
Файл в формате DER вместо PEM | Сконвертировать: openssl x509 -inform DER -in cert.cer -out cert.pem | |
Соединение отклонено при корректно установленном CA | Включен certificate pinning | Обновить pin на новый сертификат |
При проверке возвращается не тот сертификат | Не передан SNI | Добавить флаг -servername <домен> в команду openssl s_client |
При проверке возвращается сертификат GlobalSign / другой УЦ | Переключение еще не произошло | Это нормально — сейчас используется действующий сертификат GlobalSign. Цепочка сменится автоматически в момент переключения. Убедитесь, что сертификаты Минцифры уже установлены |
Если после установки возникли проблемы, удалите добавленные сертификаты:
# Debian / Ubuntu
sudo rm /
# RHEL / CentOS
sudo rm /
# Java — уберите флаги -Djavax.net.ssl.trustStore и -Djavax.net.ssl.trustStorePassword при запуске
# Windows
#
Чтобы сервис 1С «Интеграция» (1С:ДиректБанк) работал без сбоев и безопасно, установите сертификаты Национального удостоверяющего центра Минцифры России на свои устройства. Также обновите программу 1С:
После этого все будет работать стабильно и безопасно.