Установка TLS-сертификата Минцифры

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

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

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 — промежуточный.

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

Скачайте сертификаты с портала Госуслуг](https://www.gosuslugi.ru/crt). На странице перейдите в раздел для вашей операционной системы и скачайте два файла:

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

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

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

Утилиты update-ca-certificates и keytool принимают только PEM.

DER-файл нужно сконвертировать в PEM:

# Проверить формат
openssl x509 -in cert.cer -noout -text >/dev/null 2>&1 && echo "PEM" || echo "DER (нужна конвертация)"

# Конвертировать DER в PEM
openssl x509 -inform DER -in cert.cer -out cert.pem

Шаг 2. Установите сертификаты

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

Linux (Debian / Ubuntu)

sudo cp russian_trusted_root_ca.pem /usr/local/share/ca-certificates/russian_trusted_root_ca.crt
sudo cp russian_trusted_sub_ca.pem  /usr/local/share/ca-certificates/russian_trusted_sub_ca.crt
sudo update-ca-certificates

Linux (RHEL / CentOS / Alma / Rocky)

sudo cp russian_trusted_*.pem /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

Java / JVM

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

# Создать отдельный 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=/path/to/russian_truststore.jks \
     -Djavax.net.ssl.trustStorePassword=<пароль> \
     -jar app.jar

Отдельный 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, а не системное хранилище. Доступны два варианта:

# Через переменные окружения (действуют на весь процесс)
export REQUESTS_CA_BUNDLE=/path/to/russian-trusted-ca-bundle.pem
export SSL_CERT_FILE=/path/to/russian-trusted-ca-bundle.pem

# Или явно в коде
import requests
requests.get("https://mddc.tbank.ru/", verify="/path/to/russian-trusted-ca-bundle.pem")

Node.js

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

NODE_EXTRA_CA_CERTS=/path/to/russian-trusted-ca-bundle.pem node app.js

Docker

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

COPY russian-trusted-ca-bundle.pem /usr/local/share/ca-certificates/russian-trusted-ca.crt
RUN update-ca-certificates

# Для Node.js и Python внутри контейнера задайте переменные окружения:
ENV NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
ENV REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

Windows / .NET / IIS

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

# PowerShell с правами администратора
Import-Certificate -FilePath "C:\certs\russian_trusted_root_ca.cer" `
  -CertStoreLocation Cert:\LocalMachine\Root

Import-Certificate -FilePath "C:\certs\russian_trusted_sub_ca.cer" `
  -CertStoreLocation Cert:\LocalMachine\CA

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

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

curl -v https://mddc.tbank.ru/
# Ожидаемый результат: SSL certificate verify ok

openssl s_client -connect mddc.tbank.ru:443 -servername mddc.tbank.ru -showcerts </dev/null
# Флаг -servername (SNI) обязателен: без него на shared-хостинге может вернуться не тот сертификат.
# В цепочке должны присутствовать Russian Trusted Root CA и Russian Trusted Sub CA.

# Проверить срок действия установленного сертификата
echo | openssl s_client -connect mddc.tbank.ru:443 -servername mddc.tbank.ru 2>/dev/null \
  | openssl x509 -noout -dates

Если в выводе команд сейчас отображается сертификат 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. Цепочка сменится автоматически в момент переключения. Убедитесь, что сертификаты Минцифры уже установлены

Откатить изменения

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

# Debian / Ubuntu
sudo rm /usr/local/share/ca-certificates/russian_trusted_*.crt && sudo update-ca-certificates --fresh

# RHEL / CentOS
sudo rm /etc/pki/ca-trust/source/anchors/russian_trusted_*.pem && sudo update-ca-trust

# Java — уберите флаги -Djavax.net.ssl.trustStore и -Djavax.net.ssl.trustStorePassword при запуске

# Windows
# Remove-Item Cert:\LocalMachine\Root\<thumbprint>

Вопросы и ответы

Общие вопросы

Подготовка

Технические вопросы

Проверка