Технические разборы

Как работает ЭЦП в Казахстане: руководство для разработчика

· Автор: Команда SmartConnect

Электронная цифровая подпись (ЭЦП) в Казахстане: как устроена инфраструктура НУЦ РК, в чём разница между ключами, как подписывать запросы к ШЭП и почему HashiCorp Vault — правильное решение для хранения ключей.

Зачем ЭЦП при интеграции с государством

Любой обмен с государственными системами Казахстана (ШЭП, Smart Bridge, портал eGov) требует подписи запросов. ЭЦП подтверждает: «этот запрос исходит от конкретного юридического лица, данные не изменялись в пути».

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

Инфраструктура PKI в Казахстане

Национальный удостоверяющий центр РК (НУЦ РК) выдаёт несколько типов ключей:

Тип Для чего
RSA (AUTH) Аутентификация
RSA (SIGN) Подпись документов и запросов
GOST Для систем, требующих ГОСТ-алгоритмы

Ключи хранятся в файлах формата .p12 (PKCS#12) и защищены паролем. Срок действия — обычно 1–2 года. Просрочённый ключ = отказ всех интеграций.

Подпись запросов к ШЭП

ШЭП ожидает SOAP-сообщение с блоком wsse:Security, содержащим:

  • wsse:BinarySecurityToken — сам сертификат в формате Base64
  • ds:Signature — подпись тела запроса по XML-DSig

Ручная реализация этого требует понимания XML-DSig, CanonicalizationMethod, обработки namespace и нескольких алгоритмов. На практике разработчики теряют на этом недели.

Управление ключами в production

Хранить .p12-файл рядом с кодом или в environment-переменной — плохая практика. Ключ утечёт в логи, попадёт в git, сломается при ротации. Правильный подход:

  1. HashiCorp Vault или аналогичное key management решение
  2. Автоматическое отслеживание срока действия и алерты заблаговременно
  3. Ротация ключей без даунтайма сервиса

SmartConnect встраивает управление ЭЦП-ключами через HashiCorp Vault — ключи никогда не оказываются в коде или логах приложения.

Тестирование

НУЦ РК предоставляет тестовый удостоверяющий центр (тестовый НУЦ). Тестовые сертификаты работают только с тестовой средой ШЭП — не смешивайте их с продуктивными.

Если вам нужна помощь с настройкой подписи запросов к ШЭП — свяжитесь с командой SmartConnect.