02.02.2024

Интеграция ЭЦП в информационные системы: быстрый старт

Всем привет!

Эта вводная статья поможет разработчикам разобраться в том как интегрировать ЭЦП в информационные системы.

Процесс интеграции цифровых подписей в информационные системы разумно разделить на четыре этапа:

• формирование электронных документов для подписания и последующего хранения;
• подписание электронных документов - то есть формирование цифровых подписей под ними с помощью ключей ЭЦП;
• проверка подписей под документами путем их регистрации на нашем сервисе для обеспечение юридической значимости электронных документов в соответствии с Законодательством;
• экспорт документов с подписями в различных форматах для передачи третьим лицам и в сторонние информационные системы.

Схема взаимодействия выглядит следующим образом:

Для того, чтобы не путаться в терминологии и хорошо понимать принципы работы цифровых подписей, стоит ознакомиться со статьей Что такое ЭЦП?.

Важно: Мы настоятельно рекомендуем взаимодействовать с нашими API с бекенда, так как только так Вы можете быть уверенными в достоверности ответов!

# Формирование документа

Мы рекомендуем подписывать электронные документы в формате PDF по следующим причинам:

• формат PDF открыт и стандартизован, существует множество реализаций библиотек и программного обеспечения для работы с ним, он предназначен для долгосрочного хранения электронных документов;
• документы в форматах текстовых процессоров (MS Word/Excel, Libreoffice и т.п.) очень легко случайно пересохранить, а это изменит байты файла и ЭЦП под документом перестанет проходить проверку;
• XML документы очень хрупки, а так же их сложно интерпретировать человеку.

Важно понимать что тот документ (файл), который был передан на подписание пользователю, нужно будет хранить в неизменном виде. Если допустить изменение хоть одного байта в нем, цифровые подписи под ним перестанут проходить проверку. Вот примеры ситуаций приводящих к непреднамеренной (и визуально незаметной) порче документов:

• открыть файлы MS Word и кликнуть Ctrl+S, текст документа сохранится неизменным, но внутри файла изменится информация о последнем пользователе его редактировавшем;
• повторно сформировать PDF из того же шаблона и тех же данных, два файла будут выглядеть идентично, но в метаданных внутри тела файлов будут прописаны разные даты создания.

Наша опция архивирования подлинников электронных документов предназначена для обеспечения сохранности документов. Попавший в архив документ нельзя удалить или изменить.

# Подписание

Вычислять цифровые подписи под электронными документами можно с помощью следующих инструментов:

• NCALayer - программное обеспечение для настольных ОС (Windows, macOS, Linux), ему можно отправлять запросы на подписание через WebSocket интерфейс;
• eGov mobile/business - мобильные приложения для iOS и Android, позволяют подписывать через QR коды и диплинки;
• KAZTOKEN desktop - альтернатива NCALayer (повторяет его основной API) с дополнительными функциями, такими как мультиподписание и подписание больших файлов ЭЦП;
• KAZTOKEN mobile - мобильная версия KAZTOKEN desktop для Android.

Особенностью KAZTOKEN desktop и KAZTOKEN mobile является то, что они работают только с ключами ЭЦП на устройствах KAZTOKEN. То есть подписывать файловыми ключами ЭЦП с помощью этих приложений не получится.

Интеграция с NCALayer, KAZTOKEN desktop и KAZTOKEN mobile выполняется на фронтенде веб приложений или в клиентской части других видов приложений, так как они все являются WebSocket серверами, запущенными на компьютерах (или мобильных устройствах) пользователей и ожидающих запросов с локального хоста (127.0.0.1). То есть, к примеру, обратиться к NCALayer запущенному на компьютере определенного пользователя можно только с компьютера этого пользователя.

Для интеграции этих трех инструментов во фроненды веб приложений удобно использовать JavaScript библиотеку с открытым исходным кодом ncalayer-js-client. Интеграция, чаще всего, сводится к трем действиям: создать экземпляр класса, подключиться к NCALayer, подписать. Примеры использования приведены на странице приложения. Библиотека подходит как для десктопов (NCALayer или KAZTOKEN desktop), так и для мобильных платформ (KAZTOKEN mobile).

Разработчикам других видов приложений потребуется реализовать взаимодействие по протоколу WebSocket самостоятельно, описание команд, а так же песочница для их выполнения, доступно на странице интерактивной документации по KAZTOKEN mobile (основной API у этих трех приложений одинаковый): https://kaztoken.kz/mobile-docs/

С 1С ситуация несколько специфичнее так как в 1С нет нативной поддержки протокола WebSocket. Для того, чтобы добавить поддержку ЭЦП в 1С, можно воспользоваться HTTP API KAZTOKEN desktop.

Получится следующая процедура подписания на примере NCALayer (вместо него может быть KAZTOKEN desktop или KAZTOKEN mobile) и веб приложения:

Принцип работы мобильных приложений eGov mobile и eGov business тоже основан на ЭЦП, но взаимодействие с ними осуществляется по другому: через QR код или диплинк приложению передается ссылка на скачивание документа, оно выкачивает документ, пользователь проверяет его и подтверждает подписание, после этого приложение возвращает подпись серверу. Подробности в статьях: ЭЦП через QR на базе eGov mobile (QR подписание) и Мы добавили функцию подписания документов прямо на мобильных устройствах.

На тарифе Крупный бизнес доступен Упрощенный API для подписания через eGov mobile/business.

Подписи, полученные от eGov mobile и eGov business нужно точно так же проверять, как и подписи полученные из NCALayer, KAZTOKEN desktop и KAZTOKEN mobile.

Не смотря на то, что мы опубликовали JavaScript библиотеку с открытым исходным кодом для упрощения интеграции с нашими API подписания через QR, для серьезных внедрений мы рекомендуем взаимодействовать с этими API не с фронтенда, а с бекенда. Коллекцию Postman для этих API можно найти в документации по методам API.

В заключении рекомендуем обратить внимание на статью Мультиподписание - подписываем большое количество документов.

# Проверка подписей

Для обеспечения юридической значимости электронных документов, подписанных ЭЦП, в соответствии с Законодательством РК, необходимо выполнять проверку ЭЦП и документа. Наш сервис выполняет эти проверки в момент регистрации документов и подписей.

Процедура регистрации нового документа и подписи состоит, как минимум, из двух обращений:

1. POST /api - регистрация нового документа в системе
2. POST /api/{id}/data - фиксация значений хешей документа

Важно: Только после вызова двух этих API документ считается зарегистрированным.

Для того, чтобы добавить подпись под документ следует воспользоваться POST /api/{id} - добавление подписи к документу.

Получить информацию о документе и зарегистрированных под ним подписях можно с помощью GET /api/{id}?lastSignId=X - получение данных о зарегистрированном документе.

Рекомендуем обратить внимание на настройки документов, которые задаются в момент регистрации, они позволяют указывать требования к подписантам, отправлять уведомления по электронной почте и управлять контролем доступа.

Так же с помощью нашего сервиса легко реализовать Взаимодействие с внешними контрагентами.

# Экспорт

Мы поддерживаем различные форматы экспорта электронных документов и цифровых подписей:

• экспортировать подписи “как есть” можно с помощью GET /api/{id}/signature/{signId}?signFormat=X&cmsAsPem=false - экспорт одной подписи документа;
• либо в формате сервиса ezSigner.kz;
• но мы рекомендуем использовать формат Карточки электронного документа.

Документация по API находится в открытом доступе в разделе Для разработчиков (API), тематические статьи для разработчиков мы публикуем в разделе Интеграция и API, если у Вас остались вопросы, спросите нас, контакты здесь.