Адаптер плагина blitz smart card plugin что это
Blitz Smart Card Plugin
Для работы веб-приложений со средствами электронной подписи на ПК пользователя
Blitz Smart Card Plugin
Вашим пользователям нужно загружать на сайт документы и подписывать их электронной подписью? Blitz Smart Card Plugin позволяет веб-странице просто и быстро получить данные об устройстве и сформировать электронную подпись. Если вашему сайту нужна возможность подтверждать вход пользователей электронной подписью, то наше решение позволяет браузеру получить данные о сертификате и подписать запрос на аутентификацию ключом пользователя.
Преимущества 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. Встраивание плагина на сайт не займет много времени
Понятно пользователю
Процесс установки плагина линейный и сопровождается контекстными подсказками. Пользователь настроит свой ПК для работы с подписью буквально за минуту
Принцип работы
Обратиться из веб-сайта к смарт-карте или USB-токену совсем не просто
Для работы веб-приложения с электронной подписью вам понадобится браузерный плагин. Плагин — это специальная программа, которая позволяет через браузер взаимодействовать с аппаратными ресурсами компьютера — в нашем случае, обращаться к подключенным к ПК и его 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
Введение
Общие сведения
Веб-плагин Blitz Smart Card Plugin обеспечивает взаимодействие веб-сайта с подключенными к ПК устройствами электронной подписи. Он позволяет получить перечень доступных ключевых контейнеров и сертификатов и запросить установку на выбранном ключе электронной подписи. Для этого веб-плагин предоставляет возможность выполнения следующих операций:
Поддерживаемые ключи электронной подписи, операционные системы и браузеры
Производители поддерживаемых ключей электронной подписи, совместимые браузеры и операционные системы указаны в таблице ниже. Поддерживаются алгоритмы электронной подписи RSA, ГОСТ Р 34.10-2001, ГОСТ Р 34.10-2012 и ECDSA.
Также плагин позволяет использовать ключи, загруженные в системное хранилище Windows.
Перечень не является закрытым и регулярно обновляется. Вы можете проверить работу вашего ключа электронной подписи на нашей демонстрационной странице.
Свяжитесь с нами, если хотите добавить в перечень новый тип электронной подписи.
| Производитель | Название ключа | Название модуля 1 | Операционные системы | ||
|---|---|---|---|---|---|
| Аладдин Р.Д. | JaCarta PKI 3 | Aladdin R.D. Unified JaCarta |     | | |
| Аладдин Р.Д. | JaCarta ГОСТ / eToken ГОСТ | Aladdin R.D. eToken GOST 4 | | | |
| Компания «Актив» | Рутокен ЭЦП/ ЭЦП 2.0 / ЭЦП PKI / ЭЦП micro Рутокен ЭЦП Smart Card | Rutoken | | | |
| Компания «Актив» | Рутокен S / S micro, Рутокен Lite / Lite micro, Рутокен Lite Smart Card | Rutoken | | — | — |
| КРИПТО-ПРО | Ключи на основе КриптоПро CSP 3.9 и 4.0 | capi | | | |
| Signal-COM | Ключи на основе Signal-COM CSP 3.0 | capi | | — | — |
| ViPNet | Ключи на основе ViPNet CSP 4.2 | capi | | — | — |
| ISBC 5,6 | ESMART Token / Token ГОСТ | ISBC ESMART | | | |
| SafeNet 7 | SafeNet eToken | SafeNet | | | |
Примечания:
1 Используется при работе с интерфейсом плагина
2 Возможна установка плагина в Linux Debian 9, Mint 19, Ubuntu 18 в виде deb-пакета и Linux Fedora 23, CentOS 7 в виде rpm-пакета
3 Для использовании JaCarta PKI в macOS и Linux необходимо установить единую библиотеку от производителя
4 При использовании JaCarta ГОСТ / eToken ГОСТ в ОС Windows название модуля будет Aladdin R.D. Unified JaCarta
5 Для ключей этого производителя требуется установка драйвера и программного обеспечения (PKI Client для Windows и macOS, библиотеки PKCS#11 для Linux)
6 Перед установкой драйвера в macOS необходимо убедиться, что существует папка /usr/local/lib
7 Для ключей этого производителя требуется установка SafeNet Authentication Client
Таблица изменений
| Версия продукта | Описание изменений |
|---|---|
| 1.16.1 | Добавлена поддержка операционных систем семейства Linux: Debian 9, Mint 19, Ubuntu 18 |
| 1.16.0 | Добавлена поддержка ключей на основе Signal-COM CSP, работающих по алгоритму ГОСТ Р 34.10-2012 и имеющих длину ключа 256 и 512 бит |
| 1.13.0 | Добавлена поддержка ключей на основе ViPNet CSP, работающих по алгоритму ГОСТ Р 34.10-2012 |
| 1.12.0 | Добавлена поддержка ключей на основе КриптоПро CSP, работающих по алгоритму ГОСТ Р 34.10-2012 |
| 1.10.0 | 1. Добавлена поддержка ключей и сертификатов, размещенных в системном хранилище Windows (хранилище my). 2. Расширен объем данных, получаемых из сертификата с помощью функции full_info. |
| 1.9.0 | 1. Добавлена поддержка средств электронной подписи, работающих по алгоритмам ГОСТ Р 34.10-2012 и ГОСТ Р 34.11-2012. 2. Доработан механизм отображения перечня сертификатов пользователя. Перечень отображается корректно при наличии у пользователя более 64-х сертификатов. 3. Улучшен алгоритм поиска ключей на носителе. Обеспечено корректное отображение полей сертификатов, имеющих нестандартную кодировку. |
| 1.8.0 | Добавлена поддержка браузера Microsoft Edge. |
| 1.7.0 | Добавлена поддержка ViPNet CSP. |
| 1.6.0 | 1. Добавлена поддержка Firefox версии 52 и выше. 2. Добавлена поддержка Signal-COM. |
| 1.5.0 | 1. Предусмотрена возможность последовательного подписания нескольких документов без повторного запроса пин-кода. 2. Добавлена поддержка формата электронной подписи CAdES-BES. |
| 1.4.0 | Оптимизирована работа плагина. |
| 1.3.0 | 1. Добавлена поддержка КриптоПро CSP и ключей SafeNet. 2. Оптимизирована работа с JaCarta ГОСТ в части подписания файлов. |
| 1.2.0 | Добавлена возможность подписания файлов. |
| 1.1.0 | Инициализирующая версия продукта. |
Руководство пользователя
Установка плагина
При корректном встраивании плагина Blitz Smart Card Plugin в веб-приложение пользователь будет уведомлен обо всех необходимых шагах для настройки работы с электронной подписью. Приведены примеры, как это может быть реализовано в средах Windows и macOS.
При работе с брендированной сборкой плагина на основе Blitz Smart Card Plugin (например, «Федресурс: ЭП Плагин») следует учесть, что мастер установки может иметь иной вид (за счет других логотипов), а для удаления плагина следует использовать иную команду.
Пример установки в Windows
Обычно установка плагина в Windows включает в себя:
Пример установки в macOS
Обычно установка плагина в macOS включает в себя:
Пример установки в Linux Fedora / RHEL
Обычно установка плагина в Linux Fedora / RHEL при помощи rpm-пакета включает в себя выполнение команды:
где Downloads/BlitzScPlugin.rpm — имя (с путем) загруженного файла плагина. При работе с брендированной сборкой плагина имя пакета будет соответствовать названию плагина. Например, для плагина «Федресурс: ЭП Плагин» он будет иметь вид FedresursDSPlugin.rpm.
Установка расширения браузера выполняется таким же образом, как и в среде Windows / macOS.
Пример установки в Linux Linux Debian / Mint / Ubuntu
Обычно установка плагина в Linux Debian / Mint / Ubuntu при помощи deb-пакета включает в себя выполнение команды:
где Downloads/BlitzScPlugin.deb — имя (с путем) загруженного файла плагина. При работе с брендированной сборкой плагина имя пакета будет соответствовать названию плагина. Например, для плагина «Федресурс: ЭП Плагин» он будет иметь вид FedresursDSPlugin.deb.
Установка расширения браузера выполняется таким же образом, как и в среде Windows / macOS.
Обновление и удаление
Обновление плагина
Для обновления плагина установите новую версию, используя инструкцию. При обновлении не требуется предварительного удаления Blitz Smart Card Plugin.
Удаление плагина в среде Windows
При необходимости удалить плагин в среде Windows перейдите в «Панель управления», найдите раздел «Установка и удаление программ» (или «Удаление программы»). В появившемся окне выберите приложение Blitz Smart Card Plugin и нажмите на кнопку «Удалить»: 
После этого будет запущен мастер удаления приложения.
При работе с брендированной сборкой плагина имя приложения будет другим. Например, «Федресурс: ЭП Плагин».
Удаление плагина в среде macOS
Для удаления плагина в macOS необходимо выполнить следующие шаги:
Следует учесть, что брендированная сборка плагина устанавливается не в BlitzScPlugin.plugin, а в иную директорию. Например, «Федресурс: ЭП Плагин» устанавливается в FedresursDSPlugin.plugin.
Удаление плагина в среде Linux Fedora / RHEL
Для удаления плагина в Linux Fedora / RHEL, установленного с помощью rpm-пакета, необходимо выполнить команду:
Для удаления брендированной сборки плагина BlitzScPlugin следует заменить на название плагина. Например, для удаления «Федресурс: ЭП Плагин» должна быть выполнена команда:
Удаление плагина в среде Linux Debian / Mint / Ubuntu
Для удаления плагина в Linux Debian / Mint / Ubuntu, установленного с помощью deb-пакета, необходимо выполнить команду:
Для удаления брендированной сборки плагина BlitzScPlugin следует заменить на название плагина. Например, для удаления «Федресурс: ЭП Плагин» должна быть выполнена команда:
Использование плагина
Если плагин установлен корректно, то использование электронной подписи обычно включает следующие шаги:
Если пин-код введен неверно, будет отображено сообщение об ошибке. Если вы не уверены, что помните свой пин-код, не вводите его несколько раз подряд — это может привести к блокированию средства электронной подписи.
Руководство разработчика
Общие сведения
Программное обеспечение Blitz Smart Card Plugin включает в себя следующие компоненты:
- JavaScript – скрипт, обеспечивающий инстанцирование плагина, то есть создание объекта плагина на странице. Специфика инстанцирования различается в зависимости от используемого браузера, но JavaScript унифицирует этот процесс; Плагин – программное обеспечение, которое должно быть установлено на компьютер конечного пользователя. Плагин отвечает за взаимодействие между браузером пользователя и средством электронной подписи; Расширение – программное обеспечение, устанавливаемое конечным пользователем при использовании браузера Google Chrome и Mozilla Firefox версии 52 и выше. Расширение обеспечивает корректное взаимодействие этих браузеров с плагином: необходимость его установки связана тем, что эти браузеры блокируют работу плагинов на основе системы NPAPI.
Посмотреть работу плагина можно на демонстрационной странице. Разработку рекомендуем начать с простого скрипта, позволяющего посмотреть перечень подключенных средств электронной подписи.
Знакомство с плагином
Начните работать с плагином на примере операции по просмотру перечня сертификатов подключенных средств электронной подписи. Для этого:
Далее в документации описываются использованные в данном скрипте функции, а также даются инструкции по дальнейшей работе со средством электронной подписи.
Создание объекта плагина
Перед тем, как веб-страница сможет работать с плагином, она должна его инстанцировать, то есть создать объект плагина на странице. Инстанцирование осуществляется в зависимости от используемого браузера. Для упрощения этого процесса рекомендуется использовать специальный JavaScript. Далее описываются функции этого скрипта.
После приобретения плагина значения этих параметров предоставляются клиенту. Например, для использования плагина «Федресурс: ЭП Плагин» необходимо использовать следующие параметры:
- pluginName: Fedresurs DS Plugin mimeType: application/x-fedresurs-d-s-plugin hostname: ru.fedresurs.firewyrmhost
Функция createFactory возвращает функцию, необходимую для создания плагина на странице. При вызове этой функции в качестве параметров следует указать:
- функцию, которую необходимо выполнить при успехе создания плагина; функцию, которую необходимо выполнить при ошибке создания плагина. Данная функция в качестве первого параметра принимает код ошибки, второго – описание ошибки, третьего и последующих – функции, вызываемые в зависимости от типа ошибки.
При создании плагина возможны следующие ошибки:
- plugin_not_available – плагин не установлен (или не разрешен запуск), в этом случае необходимо рекомендовать пользователю установить плагин. Также данная ошибка возможна и в случае попытки обращения к плагину версии 1.5.0.0 из Firefox версии 52 и выше – обновление плагина до версии 1.6.0.0 и выше решает эту проблему. В качестве третьего параметра передается функция waitingPluginCb, позволяющая перейти в режим ожидания установки плагина; plugin_not_allowed – плагин заблокирован браузером, в этом случае необходимо рекомендовать пользователю разблокировать плагин. В качестве третьего параметра передается функция waitingAllowCb, позволяющая перейти в режим ожидания разблокирования плагина; chrome_extension_not_available – не установлено или не доступно расширение для Chrome, необходимое для работы плагина. В этом случае следует рекомендовать пользователю установить расширение, предоставив ссылку для перехода на страницу плагина (второй параметр). В качестве третьего параметра передается функция waitingExtensionCb, позволяющая перейти в режим ожидания установки плагина; firefox_extension_not_available – не установлено или недоступно расширение для Firefox (версии 52 и выше), необходимое для работы плагина. В этом случае следует рекомендовать пользователю установить расширение, предоставив ссылку для перехода на страницу плагина — второй параметр (ссылка временно недоступна, поскольку расширение пока не прошло процесс рецензирования для выкладывания на официальном сайте Firefox). В качестве третьего параметра передается функция waitingExtensionCb, позволяющая перейти в режим ожидания установки плагина. В качестве четвертого параметра можно указать URL на загрузку расширения с сайта производителя плагина (Identityblitz.ru). Поскольку расширение может быть установлено только по явному нажатию по ссылке, то в качестве пятого параметра следует указать функцию для установки расширения; plugin_not_valid – плагин установлен, но работает некорректно, в этом случае необходимо рекомендовать пользователю обратиться к администратору (детальное описание ошибки передается во втором параметре); plugin_old_version – старая версия плагина, текущая версия плагина передается в качестве второго параметра.
Интерфейс плагина
Общие сведения
Программный интерфейс плагина предполагает вызов асинхронных операций, реализованных на основе объектов promise. Подробнее про использованную в реализации плагина спецификацию можно прочитать здесь. На promise необходимо устанавливать обработчики двух типов:
- onFulfilled – срабатывают, когда promise в состоянии «выполнен успешно»; onRejected – срабатывают, когда promise в состоянии «завершен с ошибкой».
Универсальный метод для установки обработчиков имеет следующий вид:
Инициализация плагина
Пример инициирования модуля для получения ключей из системного хранилища Windows:
Просмотр перечня модулей и их состояния
Пример ответа функции (разрывы даны для удобства чтения):
Просмотр перечня сертификатов
Просмотр данных о конкретном сертификате
Просмотр данных о ключе электронной подписи
Операция подписания с помощью выбранного сертификата
Простой режим подписания
Расширенный режим подписания
Расширенный режим позволяет:
- подписывать данные большого объема, например, файлы; подписывать несколько файлов без повторного запроса пин-кода.
Для подписания данных с помощью выбранного сертификата необходимо предварительно инициализировать объект signer с помощью функции start_signing на объекте сертификата. Параметры функции:
- тип подписи — является ли подпись присоединенной (необходимо передавать значение true) или отсоединенной (false); количество попыток ввода пин-кода (например, значение «1» означает, что у пользователя имеется только одна попытка, после чего функция возвращает ошибку).
На объекте signer будут доступны методы:
Пример команды, позволяющей подписать строку:
В данной команде «1234» — это строка, которую необходимо подписать.
Установка нескольких подписей
После финализации подписи объект signer возвращается в исходное состояние. В рамках сессии его можно использовать повторно для подписания других данных, например, нового файла. В этом случае пин-код не будет запрошен повторно.
Подписание файла большого объема
При подписании файлов большого объема рекомендуется осуществлять последовательное чтение и подписание фрагментов файла. В качестве примера можно воспользоваться следующей функцией:
Следует учесть, что поскольку подписание выполняется локально, то для последующей передачи выбранного пользователем файла и подписи на сервер необходимо реализовать соответствующую логику на стороне веб-страницы.