Войти как партнер
Войти как партнер
Перейти к содержанию

Установка и запуск КриптоАРМ Gate#

В этой инструкции вы узнаете как установить и настроить сервис КриптоАРМ Gate с использованием Docker.

Содержание:

Условия применения#

Требования для установки и настройки#

Характеристика Минимальное значение Дополнение
ОЗУ 4 ГБ
HDD 10 ГБ
Процессор x86_64 (amd64)
Поддерживаемые ОС Ubuntu 18.04/20.04, Debian 11, Astra Linux SE 1.8 Орел Поддерживаются другие Linux-дистрибутивы с поддержкой Docker
Дополнительно Docker Средство автоматизации развертывания и контейнеризации

Используемый стек технологий#

Apache 2.4, КриптоПро CSP 5.0 (mod_ssl), Docker. Опционально: модуль КриптоАРМ OIDC-mTLS (для проверки квалифицированности сертификата).

Установка#

Установка Docker и Docker Compose#

Для запуска проекта необходимы Docker и Docker Compose.
Инструкции: официальная документация Docker.

Минимальные версии: - Docker Engine: 20.10 или выше (для работы Docker Compose v2) - Docker Compose: 2.x (плагин docker compose или отдельная установка)

Установка и первый запуск#

  1. Создайте и перейдите в рабочую директорию:
mkdir cryptoarm-gate && cd cryptoarm-gate
  1. Загрузите конфигурационные файлы:
curl -O https://git.digtlab.ru/trusted/cryptoarm/gate/-/raw/main/docker-compose.yml
curl -O https://git.digtlab.ru/trusted/cryptoarm/gate/-/raw/main/Dockerfile
curl -O https://git.digtlab.ru/trusted/cryptoarm/gate/-/raw/main/.env
curl -O https://git.digtlab.ru/trusted/cryptoarm/gate/-/raw/main/entrypoint.sh
  1. Создайте необходимые директории и загрузите конфигурацию сайта:
mkdir -p cryptopro certs/gost certs/rsa certs/root conf html logs
curl -o conf/ssl.conf https://git.digtlab.ru/trusted/cryptoarm/gate/-/raw/main/conf/ssl.conf

  1. Скачайте актуальную версию КриптоПро CSP 5.0 для Linux (x64, deb) и поместите архив linux-amd64_deb.tgz в каталог cryptoarm-gate/cryptopro/.
    Для скачивания требуется авторизация на сайте КриптоПро.

  2. Отредактируйте настройки в файле .env:

  3. CRYPTO_PRO_LICENSE — серверная лицензия КриптоПро CSP (при необходимости).

  4. При использовании бэкенда укажите его адрес в конфигурации Apache (см. Проксирование на бэкенд).

  5. Разместите сертификаты сервера в соответствующих каталогах (см. Сертификаты; для теста можно скачать примеры из репозитория командами curl, указанными в этом разделе).

  6. Запустите сборку и сервис:

docker compose build --pull
docker compose up -d

Дополнительно: - Просмотр логов: docker compose logs -f - Остановка: docker compose stop - Обновление до актуальной версии: повторите п. 2, затем docker compose build --pull и docker compose up -d

Сборка на базе Astra Linux#

Для развёртывания в средах, где предъявляются требования к использованию ОС Astra Linux, предусмотрена сборка образа на базе универсального базового образа (UBI) Astra Linux.

  1. Загрузите файл сборки для Astra Linux (в дополнение к п. 2 раздела Установка и первый запуск):
curl -O https://git.digtlab.ru/trusted/cryptoarm/gate/-/raw/main/Dockerfile.astralinux

  1. Убедитесь, что в каталоге есть все артефакты: docker-compose.yml, .env, entrypoint.sh, каталог cryptopro/ с архивом КриптоПро CSP, при необходимости conf/ssl.conf и сертификаты.

  2. Соберите образ с использованием Dockerfile для Astra Linux (базовый образ — Astra Linux SE, реестр registry.astralinux.ru). При необходимости замените тег базового образа в Dockerfile.astralinux на актуальный из вашего реестра:

docker build -f Dockerfile.astralinux -t cryptoarm.gate .
  1. Запустите сервис так же, как при сборке на Ubuntu — через Docker Compose (образ уже собран под именем cryptoarm.gate):
docker compose up -d

Состав установленного ПО (Apache 2.4, КриптоПро CSP, mod_ssl, entrypoint) совпадает с вариантом на базе Ubuntu; отличается только базовый слой ОС. Остальные шаги настройки (сертификаты, mTLS, проксирование) выполняются так же, как описано в разделах Настройка и Проверка работы.

Настройка#

Сертификаты#

  • ГОСТ (обязательно): серверные сертификаты в certs/gost/ (например, localhost.cer, localhost.pfx). Используются для HTTPS и для приёма клиентских ГОСТ-сертификатов при mTLS.
  • RSA (опционально): серверные сертификаты в certs/rsa/ (например, localhost.cer, localhost.pfx). Подключаются только если нужно поднять один веб-ресурс одновременно по ГОСТ и по RSA (совместимость с клиентами без поддержки ГОСТ). Вход по сертификату и mTLS при этом выполняются только по ГОСТ.
  • Корневые и доверенные CA: в certs/root/ (файлы .cer) — для проверки клиентских ГОСТ-сертификатов при mTLS. При старте контейнера устанавливаются в хранилище КриптоПро.

В качестве примеров для тестирования можно скачать сертификаты из репозитория:

mkdir -p certs/gost certs/rsa certs/root
curl -o certs/gost/localhost.cer https://git.digtlab.ru/trusted/cryptoarm/gate/-/raw/main/certs/gost/localhost.cer
curl -o certs/gost/localhost.pfx https://git.digtlab.ru/trusted/cryptoarm/gate/-/raw/main/certs/gost/localhost.pfx
curl -o certs/rsa/localhost.cer https://git.digtlab.ru/trusted/cryptoarm/gate/-/raw/main/certs/rsa/localhost.cer
curl -o certs/rsa/localhost.pfx https://git.digtlab.ru/trusted/cryptoarm/gate/-/raw/main/certs/rsa/localhost.pfx
curl -o certs/root/cryptopro_test.cer https://git.digtlab.ru/trusted/cryptoarm/gate/-/raw/main/certs/root/cryptopro_test.cer

Внимание: примеры предназначены только для проверки развёртывания и тестовых сценариев. В продуктивной среде используйте собственные сертификаты и корневые CA.

Конфигурация SSL задаётся в conf/ssl.conf, монтируемом в контейнер.

Режим mTLS и OIDC#

Вход по сертификату и допуск к защищённым ресурсам выполняются по ГОСТ-сертификату клиента. В конфигурации Apache включают проверку клиентского сертификата и передачу его данных бэкенду:

  • В conf/ssl.conf раскомментируйте SSLVerifyClient require при необходимости обязательной проверки клиентского сертификата (принимаются только ГОСТ-сертификаты, настроенные в КриптоПро).
  • Раскомментируйте блоки RequestHeader set X-SSL-Client-*, чтобы передавать в бэкенд атрибуты предъявленного сертификата:
  • X-SSL-Client-Verify, X-SSL-Client-DN, X-SSL-Client-Serial, X-SSL-Client-Issuer, X-SSL-Client-Cert, X-SSL-Client-S-DN-CN, X-SSL-Client-I-DN-CN.

Проверка квалифицированности предъявленного ГОСТ-сертификата выполняется с привлечением модуля КриптоАРМ OIDC-mTLS: GATE передаёт данные подписи/сертификата в API модуля; по результату проверки принимается решение о допуске пользователя для OIDC-входа.

Переменные mTLS и заголовки для бэкенда#

При успешной проверке клиентского ГОСТ-сертификата Apache (mod_ssl) устанавливает переменные окружения SSL_CLIENT_* и при включённых RequestHeader передаёт их бэкенду в HTTP-заголовках X-SSL-Client-*. Ниже — пример значений (из SSI, например index.shtml).

Переменные сертификата клиента (mTLS):

Переменная / заголовок Описание Пример значения
SSL_CLIENT_VERIFY / X-SSL-Client-Verify Результат проверки клиентского сертификата SUCCESS
SSL_CLIENT_S_DN_CN / X-SSL-Client-S-DN-CN Common Name субъекта сертификата TEST_КРИПТОАРМ
SSL_CLIENT_I_DN_CN / X-SSL-Client-I-DN-CN Common Name издателя (УЦ) Тестовый УЦ ООО "КРИПТО-ПРО"
SSL_CLIENT_S_DN / X-SSL-Client-DN Distinguished Name субъекта CN=TEST_КРИПТОАРМ
SSL_CLIENT_I_DN / X-SSL-Client-Issuer DN издателя CN=Тестовый УЦ ООО "КРИПТО-ПРО",O=ООО "КРИПТО-ПРО",L=Москва,ST=г. Москва,C=RU,...
SSL_CLIENT_M_SERIAL / X-SSL-Client-Serial Серийный номер сертификата 7C002E6AAA722B2E8F1A3D81930012002E6AAA
SSL_CLIENT_CERT / X-SSL-Client-Cert Сертификат клиента (PEM) -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----
SSL_CLIENT_A_KEY Алгоритм ключа GOST R 34.10-2012 with 256 bit modulus
SSL_CLIENT_A_SIG Алгоритм подписи GOST R 34.10-2012 with GOST R 34.11-2012 (256 bit)
SSL_CLIENT_V_START / SSL_CLIENT_V_END Срок действия сертификата Feb 13 08:58:40 2026 GMT … Apr 13 09:08:40 2026 GMT

Дополнительные переменные SSL (только на стороне GATE, в SSI/скриптах):

HTTPS=on
SSL_PROTOCOL=TLSv1.2
SSL_CLIENT_I_DN_C=RU
SSL_CLIENT_I_DN_ST=г. Москва
SSL_CLIENT_I_DN_L=Москва
SSL_CLIENT_I_DN_O=ООО "КРИПТО-ПРО"
SSL_CLIENT_I_DN_CN=Тестовый УЦ ООО "КРИПТО-ПРО"
SSL_VERSION_INTERFACE=mod_ssl/2.4.41
SSL_VERSION_LIBRARY=OpenSSL/1.1.1f

Бэкенд (OIDC-провайдер и др.) при проксировании получает заголовки HTTP_X_SSL_CLIENT_VERIFY, HTTP_X_SSL_CLIENT_DN, HTTP_X_SSL_CLIENT_SERIAL, HTTP_X_SSL_CLIENT_ISSUER, HTTP_X_SSL_CLIENT_CERT, HTTP_X_SSL_CLIENT_S_DN_CN, HTTP_X_SSL_CLIENT_I_DN_CN (префикс HTTP_ и замена - на _ задаются правилами сервера/приложения).

Проксирование на бэкенд#

В conf/ssl.conf задаётся проксирование на внутренний бэкенд (в т.ч. OIDC-провайдер):

ProxyPass        /api http://backend/
ProxyPassReverse /api http://backend/

Измените http://backend/ на фактический адрес бэкенда (в Docker Compose — имя сервиса и порт, например http://cryptoarm-id-back:3005/).

Пример бэкенда для проверки. В docker-compose.yml можно использовать тестовый бэкенд kennethreitz/httpbin: он возвращает в ответе все заголовки запроса, в том числе переданные GATE заголовки mTLS (X-Ssl-Client-*). Сервис уже описан в составе проекта:

  backend:
    image: kennethreitz/httpbin
    container_name: backend

После запуска docker compose up -d запрос к https://SERVER:4443/api/headers (с предъявлением ГОСТ-сертификата при включённом mTLS) вернёт JSON с заголовками, среди которых будут X-Ssl-Client-Verify, X-Ssl-Client-Dn, X-Ssl-Client-Serial, X-Ssl-Client-Issuer, X-Ssl-Client-Cert, X-Ssl-Client-S-Dn-Cn, X-Ssl-Client-I-Dn-Cn и др.

Проверка работы#

  • Доступ по HTTPS (порт 4443 по умолчанию): https://SERVER:4443
  • Статическая раздача из /var/www/html (монтируется из html/).
  • Проксирование запросов по путям, указанным в ProxyPass (например, /api), на бэкенд.

Проверка mTLS и передачи данных сертификата бэкенду. Подключитесь к GATE с клиентским ГОСТ-сертификатом и выполните запрос к примеру бэкенда (httpbin):

https://SERVER:4443/api/headers

В ответе (JSON) в объекте headers будут переданные GATE заголовки, например:

{
  "headers": {
    "Host": "172.17.1.115:14443",
    "X-Forwarded-Host": "172.17.1.115:14443",
    "X-Ssl-Client-Verify": "SUCCESS",
    "X-Ssl-Client-Dn": "CN=TEST_КРИПТОАРМ",
    "X-Ssl-Client-S-Dn-Cn": "TEST_КРИПТОАРМ",
    "X-Ssl-Client-I-Dn-Cn": "Тестовый УЦ ООО \"КРИПТО-ПРО\"",
    "X-Ssl-Client-Serial": "7C002E6AAA722B2E8F1A3D81930012002E6AAA",
    "X-Ssl-Client-Issuer": "CN=Тестовый УЦ ООО \"КРИПТО-ПРО\",O=ООО \"КРИПТО-ПРО\",L=Москва,ST=г. Москва,C=RU,...",
    "X-Ssl-Client-Cert": "-----BEGIN CERTIFICATE----- MIIE5DCCBJGgAwIBAgITfAAuaqpy ... -----END CERTIFICATE-----"
  }
}

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

Для повышения удобства работы и хранения данных веб-сайт TRUSTED.RU использует файлы COOKIE. Продолжая работу с веб-сайтом, Вы даете свое согласие на работу с этими файлами.