Розробка модуля електронної підписи 1С-Бітрікс
Електронна підпис у контексті 1С-Бітрікс — це не «кнопка підписати», а інтеграція криптографічного стеку в веб-середовище: браузерний плагін, серверна верифікація, зберігання підписаних документів з гарантією юридичної значимості. Завдання торкається фронтенду (взаємодія з токеном/сертифікатом через JavaScript), бекенду (перевірка цепочки сертифікатів, робота з CRL/OCSP) та інфраструктури (налаштування криптопровайдера на сервері).
Криптографічний стек: КриптоПро та формати підписи
Стандарт де-факто для російської електронної підписи — КриптоПро CSP. У веб-приложеннях використовується зв'язка:
- КриптоПро CSP — криптопровайдер, установлений на машині користувача (або на сервері для серверної підписи). Реалізує ГОСТ Р 34.10-2012 та ГОСТ Р 34.11-2012.
- КриптоПро ЕЦП Browser plug-in — NPAPI/ActiveX плагін (для старих браузерів) або його сучасна замінa через нативне приложення + розширення для Chrome/Firefox/Edge.
-
cadesplugin.js — JavaScript-бібліотека від КриптоПро, що надає API для роботи з плагіном через
cadesplugin.CreateObjectAsync().
Формати підписи, які зустрічаються в реальних проектах:
| Формат | Опис | Застосування |
|---|---|---|
| CAdES-BES | Базова удосконалена підпис. Містить підпис, сертифікат підписанта та цепочку сертифікатів. | Внутрішній документообіг, де не потрібна довгострокова перевірка |
| CAdES-T | CAdES-BES + штамп часу від TSP-сервера. | Фіксація моменту підписання |
| CAdES-X Long Type 1 | CAdES-T + повні дані для перевірки (OCSP-відповіді, CRL). | Юридично значимий документообіг, довгострокове зберігання |
Для більшості проектів на Бітрікс достатньо CAdES-BES для внутрішніх процесів та CAdES-X Long Type 1 для документів з контрагентами та держорганами.
Технічна реалізація підписи через КриптоПро
Це ключовий технічний блок. Процес підписання документа з браузера складається з кількох етапів, й кожен з них — потенційна точка відмови.
Крок 1: ініціалізація плагіну.
На стороні клієнта завантажується cadesplugin.js. Бібліотека визначає тип браузера та спосіб взаємодії — через нативне приложення (CryptoPro Extension for CAdES Browser Plug-in) або через NPAPI (застарілий шлях). Ініціалізація асинхронна:
cadesplugin.then(function() {
// плагін готовий
}, function(error) {
// плагін не установлений або не налаштований
});
На цьому етапі критично обробити випадок, коли плагін не установлений — показати користувачу зрозумілу інструкцію, а не пустий екран.
Крок 2: вибір сертифіката.
Через API плагіну запитується сховище сертифікатів (cadescom.CAPICOM_MY_STORE). Користувач бачить список сертифікатів з іменами власників та термінами дії. На практиці у сховищі може бути 5–10 сертифікатів — особисті, організації, тестові. Фільтрація за OID призначення (підписання документів — 1.3.6.1.5.5.7.3.4) звужує список.
Для кожного сертифіката перевіряється:
- Термін дії (
ValidFromDate,ValidToDate) - Наявність закритого ключа (
HasPrivateKey()) - Статус — чи не відозваний (попередня перевірка через кешований CRL)
Крок 3: формування підписи.
Документ (PDF, XML, довільний файл) передається у вигляді Base64-строки. Для CAdES-BES:
- Створюється об'єкт
CAdESCOM.CadesSignedData - Встановлюється вміст (
ContentEncoding=CADESCOM_BASE64_TO_BINARY) - Викликається метод
SignCades()з указанням сертифіката та типу підписи
Результат — строка у форматі CMS (PKCS#7), закодована в Base64. Це відкріплена (detached) підпис.
Крок 4: відправлення на сервер.
Підпис передається на сервер Бітрікс через AJAX-запит. На сервері зберігається:
- Оригінальний документ
- Файл підписи (
.sigабо.p7s) - Метадані: хто підписав (субзект сертифіката), коли, серійний номер сертифіката
Для CAdES-X Long Type 1 процес складніше — потрібен доступ до TSP-сервера (штамп часу) та OCSP-респондера. Ці запити виконує плагін автоматично, якщо вказаний відповідний формат підписи, але TSP-сервер повинен бути доступний (за замовчуванням — http://cryptopro.ru/tsp/, для продакшену потрібен свій або платна підписка).
Обробка помилок — окрема тема. Типові проблеми:
- Плагін установлений, але розширення браузера відключене —
cadespluginпромісс відхиляється - Сертифікат є, але закритий ключ на токені, який не підключений —
HasPrivateKey()повертаєfalse - TSP-сервер недоступний — підпис CAdES-X Long Type 1 не формується, потрібен fallback на CAdES-BES з попередженням
- PIN-код токена — користувач повиненввести PIN при зверненні до закритого ключа, це системний діалог, який неможливо кастомізувати
Перевірка підписи та сертифікатів
Перевірка виконується на сервері через КриптоПро CSP, установлений на серверній машині. Для PHP доступний модуль phpcades (розширення для PHP від КриптоПро) або виклик утиліти cryptcp через exec().
Серверна перевірка включає:
- Цілісність підписи — хеш документа совпадает с хешем в подписи
- Валідність сертифіката — не істік, не відозваний
- Цепочка довіри — від сертифіката підписанта до кореневого УЦ
Перевірка відзиву сертифіката реалізується двома способами:
- CRL (Certificate Revocation List) — періодично завантажуваний список відозваних сертифікатів. Завантажується у сховище CSP на сервері. Мінус — затримка між відзивом та оновленням CRL (зазвичай 24 години).
- OCSP (Online Certificate Status Protocol) — запит статусу в реальному часі до респондера УЦ. Точніше, але залежить від доступності сервісу. КриптоПро CSP підтримує OCSP через налаштування в реєстрі або конфігурації.
Зберігання підписаних документів
Підписані документи зберігаються в Бітрікс через highload-блок або окремту таблицю:
-
DOCUMENT_ID— зв'язок з сутністю (замовлення, договір, акт) -
FILE_ID— оригінальний документ у таблиціb_file -
SIGNATURE_FILE_ID— файл підписи -
SIGNER_SUBJECT— дані з сертифіката (ФІО, ІНН організації) -
SIGN_DATE— дата підписання -
SIGN_FORMAT— CAdES-BES / CAdES-X Long Type 1 -
VERIFICATION_STATUS— результат останньої перевірки
Для довгострокового зберігання (архів) рекомендується періодична переподпись — додавання нового штампа часу до істікання терміну дії попереднього. Це забезпечує можливість перевірки підписи через 5–10 років, коли алгоритми можуть бути признані застарілими.
Інтеграція в документообіг Бітрікс
У модулі sale підпис вбудовується в життєвий цикл замовлення:
- Статус замовлення «Очікує підписання» — клієнт у особистому кабінеті бачить документи для підписи
- Після підписання статус змінюється автоматично через обробник — AJAX-callback викликає
CSaleOrder::Update()або метод D7 - У адміністративній панелі у менеджера відображається статус підписи: підписан / не підписан / підпись не пройшла перевірку
Якщо проект використовує Бітрікс24, підпис можна вбудувати в бізнес-процеси через активити модуля bizproc. Документ проходить маршрут узгодження, і на финальному етапі підписується ЕЦП відповідальної особи.
Модуль електронної підписи — це інфраструктурний компонент. Його складність не в обсязі коду, а в кількості зовнішніх залежностей: криптопровайдер, браузерний плагін, TSP-сервер, OCSP-респондер, кореневі сертифікати УЦ. Кожен з цих елементів вимагає налаштування та моніторингу.