ДОКУМЕНТАЦИЯ НА ПЛАГИН СМАРТ-КАРТЫ BLITZ

Для работы веб-приложений со средствами электронной подписи на ПК пользователя

Вы можете проверить работу плагина, если у вас есть ключ электронной подписи семейств JaCarta и eToken
(Аладдин Р. Д.), Рутокен (Актив) или ESMART (ISBC). Полный перечень поддерживаемых типов ключей, операционных
систем и браузеров размещен в
документации.

Обнаружили ошибку или ваш ключ электронной подписи не работает?
Напишите нам и мы
исправим ошибку.

Демонстрация работы плагина состоит из трех шагов:

1. Создание объекта плагина на веб-странице

Далее следует вызвать функцию createFactory со следующими параметрами:

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

Результатом выполнения функции createFactory станет «фабрика плагина» (pluginFactory).
Инстанцирование плагина выполняется асинхронно с помощью полученной фабрики. При вызове этой функции
указываются параметры:

функция, которая будет вызвана при успехе создания плагина;

функция, которая будет выполнена при ошибке создания плагина (см.
детальное описание).

Общие сведения

Программный интерфейс плагина предполагает вызов асинхронных операций, реализованных на основе объектов promise. Подробнее про использованную в реализации плагина спецификацию можно прочитать здесь. На promise необходимо устанавливать обработчики двух типов:

Универсальный метод для установки обработчиков имеет следующий вид:

Инициализация плагина

Для работы с плагином необходимо вызвать функцию инициализации PKCS#11-компонента plugin.initPKCS11. Данная функция в качестве параметров принимает перечень названий модулей (в виде массива). Перечень предусмотренных модулей можно посмотреть здесь. Если модули не указаны, то плагин произведет инициирование всех модулей.
При необходимости указать, какие именно криптопровайдеры следует использовать при работе модуля capi, следует использовать следующий формат записи:

В этой записи:

Пример инициирования модуля для получения ключей из системного хранилища Windows:

При успешной инициализации функция возвращает объект (здесь и далее – с помощью механизма promise), имеющий функции modules и getCertsForSign.

Просмотр перечня модулей и их состояния

Для просмотра перечня модулей и их состояния необходимо вызвать функцию modules.
Пример запроса:

Пример ответа функции (разрывы даны для удобства чтения):

Просмотр перечня сертификатов

Для просмотра перечня обнаруженных сертификатов необходимо вызвать функцию getCertsForSign. В качестве параметра вызова функции необходимо указать, следует ли использовать параллельный режим опроса инициализированных PKCS#11 модулей:

Перечень сертификатов представляет собой массив (JavaScript Array), элементами которого являются объекты сертификатов. На объекте сертификата можно выполнить функции full_info, cms_sign_on_it и start_signing.

Просмотр данных о конкретном сертификате

Для просмотра данных о конкретном сертификате необходимо вызвать свойство full_info, возвращающее сведения о сертификате в виде json-объекта. Он включает в себя следующие параметры:

Время начала / окончания действия сертификата в формате ASN1_TIME может быть переведено в стандартный формат с помощью функции new Date(ASN1_TIME).

Просмотр данных о ключе электронной подписи

Для просмотра данных о конкретном ключе электронной подписи сертификата необходимо вызвать метод token_info. Метод возвращает json-объект со следующими данными:

Для ключей, работающих через capi-модуль, возвращаемые данные имеют иной вид. Атрибут model всегда принимает значение “capi”, атрибут serialNumber отсутствует, manufacturerID соответствует названию криптопровайдера, а label – это название контейнера.

Операция подписания с помощью выбранного сертификата

Простой режим подписания

Для подписания строки с помощью выбранного сертификата необходимо вызвать функцию cms_sign_on_it, принимающую следующие входные параметры:

В качестве ответа функция возвращает строку с подписью в формате CAdES-BES / PKCS#7 attached/detached.
Пример вызова функции, которая должна быть вызвана на объекте сертификата:

Расширенный режим подписания

Расширенный режим позволяет:

Для подписания данных с помощью выбранного сертификата необходимо предварительно инициализировать объект signer с помощью функции start_signing на объекте сертификата. Параметры функции:

На объекте signer будут доступны методы:

Пример команды, позволяющей подписать строку:

В данной команде «1234» — это строка, которую необходимо подписать.

Установка нескольких подписей

После финализации подписи объект signer возвращается в исходное состояние. В рамках сессии его можно использовать повторно для подписания других данных, например, нового файла. В этом случае пин-код не будет запрошен повторно.

Чтобы произвести подписание на другом сертификате, необходимо очистить объект signer. В большинстве браузеров этот объект очищается автоматически, когда он покидает область видимости (scope). Однако в Internet Explorer возможны ситуации, когда очищение signer не происходит, что приводит к ошибке. Для избегания ошибки рекомендуется явно очищать signer.free(). Данную операцию можно проводить во всех браузерах, чтобы унифицировать код. Пример подписи на сертификате с очисткой объекта signer:

Подписание файла большого объема

При подписании файлов большого объема рекомендуется осуществлять последовательное чтение и подписание фрагментов файла. В качестве примера можно воспользоваться следующей функцией:

Следует учесть, что поскольку подписание выполняется локально, то для последующей передачи выбранного пользователем файла и подписи на сервер необходимо реализовать соответствующую логику на стороне веб-страницы.

Остались вопросы?

Мы готовы проконсультировать вас по любым вопросам, связанным с Blitz Smart Card Plugin.

Blitz Smart Card Plugin

Вашим пользователям нужно загружать на сайт документы и подписывать их электронной подписью? Blitz Smart Card Plugin позволяет веб-странице просто и быстро получить данные об устройстве и сформировать электронную подпись. Если вашему сайту нужна возможность подтверждать вход пользователей электронной подписью, то наше решение позволяет браузеру получить данные о сертификате и подписать запрос на аутентификацию ключом пользователя.

Принцип работы

Для работы веб-приложения с электронной подписью вам понадобится браузерный плагин. Плагин — это специальная программа, которая позволяет через браузер взаимодействовать с аппаратными ресурсами компьютера — в нашем случае, обращаться к подключенным к ПК и его USB-портам смарт-картам и токенам или вызывать установленные на ПК программные криптопровайдеры.

При разработке собственного плагина необходимо учитывать специфику браузеров. Браузеры Apple Safari и Microsoft Internet Explorer используют для взаимодействия с плагинами программный интерфейс NPAPI или ActiveX. Браузеры Google Chrome, Mozilla Firefox, Edge, Яндекс. Браузер, Спутник используют технологию Native Messaging. При работе с Native Messaging дополнительно к плагину необходимо разработать расширение браузера (browser extention) и зарегистрировать его у производителя браузера.

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

Чтобы пользователи могли установить плагин — нужно позаботиться о создании установщика плагина для каждой из операционных систем. Установщики необходимо подписать специальной подписью производителя, сертификат которой штатно признается в соответствующей операционной системе — иначе при установке плагина пользователи будут получать от операционной системы предупреждения об установке опасного непроверенного программного обеспечения.

Blitz Smart Card Plugin делает простым решение задачи установки электронной подписи

При использовании Blitz Smart Card Plugin для работы с электронной подписью нужно только разместить на своем сайте JavaScript-код. Доступны следующие действия по работе с электронной подписью:

Данные для подписания передаются в виде строк одного из форматов: utf-8, hex, base64.

Подпись формируется в формате PKCS#7 или CAdES-BES. Возможно формирование как отсоединенной, так и присоединенной подписи.

Преимущества Blitz Smart Card Plugin

Универсально

Плагин работает в популярных ОС (Windows, Linux, macOS), браузерах (Chrome, Firefox, Safari, Internet Explorer, Edge, Спутник, Яндекс. Браузер). Поддерживает ключи eToken, JaCarta, Рутокен, SafeNet, ESMART, КриптоПро CSP, ViPNet CSP, Signal-COM CSP

Просто встроить на сайт

Для вызова плагина используется JavaScript API. Встраивание плагина на сайт не займет много времени

Понятно пользователю

Процесс установки плагина линейный и сопровождается контекстными подсказками. Пользователь настроит свой ПК для работы с подписью буквально за минуту