Разработка модуля электронной подписи 1С-Битрикс

Разработка модуля электронной подписи 1С-Битрикс

Электронная подпись в контексте Битрикс — это не кнопка «Подписать» на форме. Это интеграция криптографического стека в веб-среду: браузерный плагин, серверная верификация, хранение подписанных документов с юридической значимостью. Задача затрагивает фронтенд (взаимодействие с токеном через JavaScript), бэкенд (проверка цепочки сертификатов, OCSP/CRL) и инфраструктуру (криптопровайдер на сервере). И каждый из этих слоёв — потенциальная точка отказа с невнятными сообщениями об ошибках.

Криптографический стек: КриптоПро CSP и форматы подписи

Стандарт де-факто для российской ЭП — КриптоПро CSP. В веб-приложениях работает связка:

• КриптоПро CSP — криптопровайдер на машине пользователя (или на сервере для серверной подписи). Реализует ГОСТ Р 34.10-2012 (подпись) и ГОСТ Р 34.11-2012 (хеширование)
• КриптоПро ЭЦП Browser plug-in — нативное приложение + расширение для Chrome/Firefox/Edge (NPAPI давно мёртв)
• cadesplugin.js — JavaScript-библиотека от КриптоПро, API для работы с плагином через cadesplugin.CreateObjectAsync()

Форматы подписи, которые реально встречаются в проектах:

На практике: CAdES-BES для внутренних процессов, CAdES-X Long Type 1 для документов, которые уйдут за периметр организации. Выбор формата влияет на инфраструктурные требования — для CAdES-X Long Type 1 нужен доступ к TSP-серверу и OCSP-респондеру.

Процесс подписания: от клика до сервера

Это центральный технический блок, и разберём его послойно — каждый шаг содержит грабли.

Шаг 1: инициализация плагина. Загружается cadesplugin.js. Библиотека определяет браузер и способ взаимодействия — через нативное приложение CryptoPro Extension for CAdES Browser Plug-in. Инициализация асинхронная:

cadesplugin.then(function() {
    // плагин готов к работе
}, function(error) {
    // плагин не установлен или расширение отключено
});

Критично: если плагин не установлен — пользователь должен увидеть внятную инструкцию с ссылками на скачивание, а не белый экран. На практике в 30% случаев проблема именно здесь: плагин стоит, но расширение браузера отключено после обновления Chrome.

Шаг 2: выбор сертификата. Через API плагина запрашивается хранилище cadescom.CAPICOM_MY_STORE. Пользователь видит список сертификатов с ФИО и сроками действия. В реальном хранилище бывает 5–10 сертификатов: личные, организации, тестовые, просроченные. Фильтрация по OID назначения (1.3.6.1.5.5.7.3.4 — подписание документов) сужает список.

Для каждого сертификата проверяется:

• Срок действия (ValidFromDate, ValidToDate)
• Наличие закрытого ключа (HasPrivateKey()) — если ключ на токене, который не вставлен, вернёт false
• Предварительный статус отзыва через кешированный CRL

Шаг 3: формирование подписи. Документ (PDF, XML, произвольный файл) передаётся как Base64-строка. Процесс для CAdES-BES:

1. Создаётся объект CAdESCOM.CadesSignedData
2. Устанавливается содержимое (ContentEncoding = CADESCOM_BASE64_TO_BINARY)
3. Вызывается SignCades() с сертификатом и типом подписи
4. Результат — строка CMS (PKCS#7) в Base64. Открепленная (detached) подпись

При вызове SignCades() система запросит PIN-код токена — это системный диалог ОС, его невозможно кастомизировать или перехватить из JavaScript. Пользователь вводит PIN, подпись формируется.

Шаг 4: отправка и сохранение. Подпись уходит на сервер AJAX-запросом. Сохраняется:

• Оригинальный документ
• Файл подписи (.sig / .p7s)
• Метаданные: субъект сертификата (ФИО, ИНН), серийный номер, дата подписания

Для CAdES-X Long Type 1 плагин сам обращается к TSP-серверу и OCSP-респондеру — но они должны быть доступны. По умолчанию — http://cryptopro.ru/tsp/, для продуктива нужен собственный TSP или коммерческая подписка (КриптоПро TSP Server или сторонний).

Типичные ошибки при внедрении:

• Плагин установлен, расширение отключено — промис cadesplugin реджектится без внятного сообщения
• Сертификат есть, токен не подключён — HasPrivateKey() возвращает false, пользователь не понимает почему
• TSP-сервер недоступен — CAdES-X Long Type 1 не формируется. Нужен fallback на CAdES-BES с предупреждением «подпись без штампа времени»
• Сертификат выпущен тестовым УЦ КриптоПро — всё работает на тесте, на проде проверка не проходит из-за отсутствия корневого в доверенных

Серверная проверка подписи

Проверка выполняется на сервере через КриптоПро CSP (должен быть установлен на серверной машине). Для PHP — расширение phpcades от КриптоПро или вызов утилиты cryptcp через exec().

Что проверяется:

• Целостность — хеш документа совпадает с хешем в подписи
• Валидность сертификата — не истёк, не отозван
• Цепочка доверия — от подписанта до корневого УЦ

Проверка отзыва — два пути:

• CRL — периодически скачиваемый список отозванных сертификатов. Минус: задержка между отзывом и обновлением (обычно 24 часа). Загружается в хранилище CSP на сервере
• OCSP — запрос статуса в реальном времени к респондеру УЦ. Точнее, но зависит от доступности сервиса

Для модуля Битрикс проверка вызывается автоматически при загрузке подписи. Результат записывается в поле VERIFICATION_STATUS. Повторная проверка — по расписанию агентом (CRL обновляется, сертификат мог быть отозван после подписания).

Хранение подписанных документов

HL-блок или отдельная таблица:

Долгосрочное хранение. Если документ нужно хранить 5–10 лет, алгоритмы ГОСТ могут быть признаны устаревшими, сертификат подписанта — просрочен. Решение — периодическая переподпись: добавление нового штампа времени до истечения предыдущего. Агент раз в месяц проверяет, не истекает ли штамп в ближайшие 6 месяцев, и при необходимости добавляет новый. Без этого через 3–5 лет подпись CAdES-X Long Type 1 станет непроверяемой.

Интеграция в документооборот Битрикс

В модуле sale подпись встраивается в жизненный цикл заказа:

• Статус «Ожидает подписания» — клиент в личном кабинете видит документы
• После подписания статус меняется автоматически — AJAX-callback вызывает метод D7 Bitrix\Sale\Order::setField()
• В админке менеджер видит статус: подписан / не подписан / ошибка проверки

В Битрикс24 подпись встраивается в бизнес-процессы через activity модуля bizproc. Документ проходит маршрут согласования, на финальном этапе — подписание ЭЦП ответственного лица. Activity получает ID документа, формирует ссылку на страницу подписания, ожидает callback о завершении.

Требования 63-ФЗ. Закон «Об электронной подписи» разделяет простую, неквалифицированную и квалифицированную ЭП. Для юридической значимости документов между разными организациями нужна квалифицированная — сертификат выпущен аккредитованным УЦ, ключ на сертифицированном носителе (Рутокен, JaCarta). Для внутреннего документооборота достаточно неквалифицированной — сертификат собственного УЦ организации.

Модуль поддерживает оба варианта. Разница — в настройке корневых сертификатов на сервере и в правилах валидации.

Чек-лист перед внедрением

• КриптоПро CSP установлен на сервере (версия 5.0+ для ГОСТ-2012)
• PHP-расширение phpcades собрано и подключено (или утилита cryptcp доступна из PHP)
• Корневые сертификаты нужных УЦ добавлены в хранилище на сервере
• TSP-сервер доступен, если нужен формат CAdES-T или CAdES-X Long Type 1
• На рабочих местах пользователей — КриптоПро CSP, браузерный плагин, расширение
• Тестовые сертификаты от тестового УЦ КриптоПро для разработки и отладки

Модуль электронной подписи — инфраструктурный компонент. Его сложность не в объёме кода, а в количестве внешних зависимостей: криптопровайдер, плагин, TSP, OCSP, корневые сертификаты. Каждый элемент требует настройки и мониторинга. Стоимость рассчитывается после анализа: какие форматы подписи нужны, есть ли инфраструктура КриптоПро, сколько типов документов подписывается.