Документация Blitz Smart Card Plugin

Веб-плагин Blitz Smart Card Plugin обеспечивает взаимодействие веб-сайта с подключенными к ПК устройствами электронной подписи. Он позволяет получить перечень доступных ключевых контейнеров и сертификатов и запросить установку на выбранном ключе электронной подписи. Для этого веб-плагин предоставляет возможность выполнения следующих операций:

• Получения списка доступных сертификатов ключей подписи, считанных с подключенных к ПК устройств электронной подписи.
• Подпись строки данных с использованием указанного ключевого контейнера.
• Подпись файла на ПК пользователя с использованием указанного ключевого контейнера.

Производители поддерживаемых ключей электронной подписи, совместимые браузеры и операционные системы указаны в таблице ниже. Поддерживаются алгоритмы электронной подписи RSA, ГОСТ Р 34.10-2001, ГОСТ Р 34.10-2012 и ECDSA.
Также плагин позволяет использовать ключи, загруженные в системное хранилище Windows.
Перечень не является закрытым и регулярно обновляется. Вы можете проверить работу вашего ключа электронной подписи на нашей демонстрационной странице.
Свяжитесь с нами, если хотите добавить в перечень новый тип электронной подписи.

Производитель	Название ключа	Название модуля1	Операционные системы
			MS Windows 7/8.1/10	macOS	Linux2
Аладдин Р.Д.	JaCarta PKI3	Aladdin R.D. Unified JaCarta
Аладдин Р.Д.	JaCarta ГОСТ / eToken ГОСТ	Aladdin R.D. eToken GOST4
Компания «Актив»	Рутокен ЭЦП/ ЭЦП 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		—	—
ISBC5,6	ESMART Token / Token ГОСТ	ISBC ESMART
SafeNet7	SafeNet eToken	SafeNet

Примечания:
¹ Используется при работе с интерфейсом плагина
² Возможна установка плагина в Linux Debian 9, Mint 19, Ubuntu 18 в виде deb-пакета и Linux Fedora 23, CentOS 7 в виде rpm-пакета
³ Для использовании JaCarta PKI в macOS и Linux необходимо установить единую библиотеку от производителя
⁴ При использовании JaCarta ГОСТ / eToken ГОСТ в ОС Windows название модуля будет Aladdin R.D. Unified JaCarta
⁵ Для ключей этого производителя требуется установка драйвера и программного обеспечения (PKI Client для Windows и macOS, библиотеки PKCS#11 для Linux)
⁶ Перед установкой драйвера в macOS необходимо убедиться, что существует папка /usr/local/lib
⁷ Для ключей этого производителя требуется установка SafeNet Authentication Client

Версия продукта	Описание изменений
1.18.0	Сборка плагина подписана актуальными сертификатами Apple и Comodo
1.17.0	Обновлен PKCS#11 драйвер для ruToken ECP
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 включает в себя:

1. Загрузку плагина и его установку. В частности, запрос на установку плагина может иметь следующий вид:
   
   Следует выбрать свою операционную систему, загрузить установочный пакет и запустить его. В результате откроется следующая страница:
   
   Проследуйте по всем шагам мастера по установке: согласитесь с лицензионным соглашением, укажите путь для установки и дождитесь завершения установки:
   
2. Установку расширения. При использовании браузера Google Chrome / Mozilla Firefox версии 52 и выше требуется установка специального расширения. О необходимости установки расширения свидетельствует такое предупреждение:
   
   При переходе по ссылке отображается следующая страница установки расширения:
   
   Требуется нажать на кнопку «Установить» и дождаться завершения установки.
3. Разблокирование плагина в браузере. Если браузер блокирует работу плагина, необходимо разрешить его работу (либо временно, либо на постоянной основе).
4. Установку необходимого программного обеспечения. Для работы некоторых средств электронной подписи требуется установка специального программного обеспечения (обычно это указано в таблице совместимости).

Пример установки в macOS

Обычно установка плагина в macOS включает в себя:

1. Загрузку плагина и его установку. В частности, запрос на установку плагина может иметь следующий вид:
   
   Следует выбрать свою операционную систему, загрузить установочный пакет и запустить его. В результате откроется следующая страница:
   
   Проследуйте по всем шагам мастера по установке: согласитесь с лицензионным соглашением, при необходимости измените путь для установки и подтвердите установку паролем:
   
   Дождитесь завершения установки:
   
2. Установку расширения. При использовании браузера Google Chrome / Mozilla Firefox требуется установка специального расширения. О необходимости установки расширения свидетельствует такое предупреждение:
   
   При переходе по ссылке отображается следующая страница установки расширения:
   
   Требуется нажать на кнопку «Установить» и дождаться завершения установки.
3. Разблокирование плагина в браузере. Если браузер блокирует работу плагина, необходимо разрешить его работу (либо временно, либо на постоянной основе).
4. Установку необходимого программного обеспечения. Для работы некоторых средств электронной подписи требуется установка специального программного обеспечения (обычно это указано в таблице совместимости).

Пример установки в Linux Fedora / RHEL

Обычно установка плагина в Linux Fedora / RHEL при помощи rpm-пакета включает в себя выполнение команды:

sudo rpm -Uvh Downloads/BlitzScPlugin.rpm

где Downloads/BlitzScPlugin.rpm — имя (с путем) загруженного файла плагина. При работе с брендированной сборкой плагина имя пакета будет соответствовать названию плагина. Например, для плагина «Федресурс: ЭП Плагин» он будет иметь вид FedresursDSPlugin.rpm.

Установка расширения браузера выполняется таким же образом, как и в среде Windows / macOS.

Пример установки в Linux Linux Debian / Mint / Ubuntu

Обычно установка плагина в Linux Debian / Mint / Ubuntu при помощи deb-пакета включает в себя выполнение команды:

sudo dpkg -i Downloads/BlitzScPlugin.deb

где Downloads/BlitzScPlugin.deb — имя (с путем) загруженного файла плагина. При работе с брендированной сборкой плагина имя пакета будет соответствовать названию плагина. Например, для плагина «Федресурс: ЭП Плагин» он будет иметь вид FedresursDSPlugin.deb.

Установка расширения браузера выполняется таким же образом, как и в среде Windows / macOS.

Обновление плагина

Для обновления плагина установите новую версию, используя инструкцию. При обновлении не требуется предварительного удаления Blitz Smart Card Plugin.

Удаление плагина в среде Windows

При необходимости удалить плагин в среде Windows перейдите в «Панель управления», найдите раздел «Установка и удаление программ» (или «Удаление программы»). В появившемся окне выберите приложение Blitz Smart Card Plugin и нажмите на кнопку «Удалить»:

После этого будет запущен мастер удаления приложения.
При работе с брендированной сборкой плагина имя приложения будет другим. Например, «Федресурс: ЭП Плагин».

Удаление плагина в среде macOS

Для удаления плагина в macOS необходимо выполнить следующие шаги:

1. 1. Перейти в папку с установленным плагином:

/Users/<USERNAME>/Library/Internet Plug-Ins

1. 1. Выполнить скрипт:

bash BlitzScPlugin.plugin/Contents/remove.sh

Следует учесть, что брендированная сборка плагина устанавливается не в BlitzScPlugin.plugin, а в иную директорию. Например, «Федресурс: ЭП Плагин» устанавливается в FedresursDSPlugin.plugin.

Удаление плагина в среде Linux Fedora / RHEL

Для удаления плагина в Linux Fedora / RHEL, установленного с помощью rpm-пакета, необходимо выполнить команду:

sudo dnf remove BlitzScPlugin

Для удаления брендированной сборки плагина BlitzScPlugin следует заменить на название плагина. Например, для удаления «Федресурс: ЭП Плагин» должна быть выполнена команда:

sudo dnf remove FedresursDSPlugin

Удаление плагина в среде Linux Debian / Mint / Ubuntu

Для удаления плагина в Linux Debian / Mint / Ubuntu, установленного с помощью deb-пакета, необходимо выполнить команду:

sudo dpkg -r BlitzScPlugin

Для удаления брендированной сборки плагина BlitzScPlugin следует заменить на название плагина. Например, для удаления «Федресурс: ЭП Плагин» должна быть выполнена команда:

sudo dpkg -r FedresursDSPlugin

Если плагин установлен корректно, то использование электронной подписи обычно включает следующие шаги:

1. Выбор сертификата ключа электронной подписи.
   
2. Ввод пин-кода.
   

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

Программное обеспечение Blitz Smart Card Plugin включает в себя следующие компоненты:

• JavaScript – скрипт, обеспечивающий инстанцирование плагина, то есть создание объекта плагина на странице. Специфика инстанцирования различается в зависимости от используемого браузера, но JavaScript унифицирует этот процесс;
• Плагин – программное обеспечение, которое должно быть установлено на компьютер конечного пользователя. Плагин отвечает за взаимодействие между браузером пользователя и средством электронной подписи;
• Расширение – программное обеспечение, устанавливаемое конечным пользователем при использовании браузера Google Chrome и Mozilla Firefox версии 52 и выше. Расширение обеспечивает корректное взаимодействие этих браузеров с плагином: необходимость его установки связана тем, что эти браузеры блокируют работу плагинов на основе системы NPAPI.

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

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

1. Установите плагин для вашей операционной системы: Windows, macOS или Linux (RPM, DEB). Для работы с брендированными сборками плагина на основе Blitz Smart Card Plugin используйте дистрибутивы, предоставленные производителем.
2. Если вы используете браузер Chrome, то установите расширение и разрешите ему открывать файлы по ссылкам. При использовании Firefox версии 52 и выше также установите расширение.
3. Разместите на вашей веб-странице ссылку <script src="js/blitzsc.js"></script> на специальный JavaScript.
4. Добавьте в вашу страницу скрипт следующего содержания:

   <script language="JavaScript">
       var pFactory = Blitzsc.createFactory("Blitz Smart Card Plugin", "application/x-blitz-sc-plugin", "ru.reaxoft.firewyrmhost", "1.7.0.0");
       pFactory(function (plugin) {
           plugin.initPKCS11([])
               .then(function(p11){return p11.getCertsForSign(true);})
               .then(function (certs) {
                   certs.forEach(function(cert) {
                       cert.full_info.then(function(info) { console.log(info);});
                   });
               }, function(err) {
                   alert(err);
               });
       }, function (error) {
           alert(error);
       });
   </script>

   Для работы с брендированными сборками плагина на основе Blitz Smart Card Plugin используйте параметры для вызова createFactory, предоставленные производителем.

5. Запустите локально данную веб-страницу. В консоли браузера будут видны данные подключенных сертификатов. Например:

   

Далее в документации описываются использованные в данном скрипте функции, а также даются инструкции по дальнейшей работе со средством электронной подписи.

Перед тем, как веб-страница сможет работать с плагином, она должна его инстанцировать, то есть создать объект плагина на странице. Инстанцирование осуществляется в зависимости от используемого браузера. Для упрощения этого процесса рекомендуется использовать специальный JavaScript. Далее описываются функции этого скрипта.

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

• pluginName – имя плагина;
• mimeType – тип передаваемых данных;
• hostname – обратный домен нативного приложения, необходимый для корректного взаимодействия Chrome с плагином, например, ru.reaxoft.firewyrmhost;
• minVersion (опциональный параметр) – минимальная требуемая версия плагина в формате 1.0.0.0, например 1.7.0.0.

После приобретения плагина значения этих параметров предоставляются клиенту. Например, для использования плагина «Федресурс: ЭП Плагин» необходимо использовать следующие параметры:

• 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 – старая версия плагина, текущая версия плагина передается в качестве второго параметра.

Результатом успешного выполнения функции создания плагина будет java-объект plugin, описанный далее.

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

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

• onFulfilled – срабатывают, когда promise в состоянии «выполнен успешно»;
• onRejected – срабатывают, когда promise в состоянии «завершен с ошибкой».

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

promise.then(onFulfilled, onRejected)

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

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

capi:{prov1},{mode}:{prov2},{mode}

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

• prov1, prov2 – название криптопровайдера. В настоящее время поддерживаются следующие значения:
• Crypto-Pro GOST R 34.10-2001 Cryptographic Service Provider;
• Crypto-Pro GOST R 34.10-2012 Cryptographic Service Provider;
• Crypto-Pro GOST R 34.10-2012 Strong Cryptographic Service Provider;
• Signal-COM CPGOST Cryptographic Provider;
• Signal-COM GOST R 34.10-2012 (256) Cryptographic Provider;
• Signal-COM GOST R 34.10-2012 (512) Cryptographic Provider;
• Infotecs Cryptographic Service Provider.
• mode – режим отображения окна ввода пин-кода. Может принимать следующие значения:

• 0 – режим по умолчанию, предусмотренный криптопровайдером;
• 1 – отображение нативного окна криптопровайдера.
  Примечание: при работе с Crypto-Pro в Linux отображение нативного окна криптопровайдера недоступно.
• 2 – отображение окна в интерфейсе плагина.
  Примечание: при работе с Signal-COM отображение окна в интерфейсе плагина недоступно.

Для получения ключей из системного хранилища Windows следует в качестве провайдера указать <CERT_STORES>, а в качестве режима — My.
Пример инициирования всех модулей:

plugin.initPKCS11(["ISBC ESMART", "Aladdin R.D. Unified JaCarta", "Rutoken", "SafeNet", "capi:Crypto-Pro GOST R 34.10-2001 Cryptographic Service Provider,0:Crypto-Pro GOST R 34.10-2012 Cryptographic Service Provider,0:Crypto-Pro GOST R 34.10-2012 Strong Cryptographic Service Provider,0:Signal-COM CPGOST Cryptographic Provider,0:Signal-COM GOST R 34.10-2012 (256) Cryptographic Provider,0:Signal-COM GOST R 34.10-2012 (512) Cryptographic Provider,0:Infotecs Cryptographic Service Provider,0:<CERT_STORES>,My"])

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

plugin.initPKCS11(["capi:<CERT_STORES>,My"])

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

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

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

pkcs11.modules.then(onFulfilled, onRejected);

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

 [
   {
      "enable": true,
      "name": "Aladdin R.D. Unified JaCarta"
   },
   {
      "enable": true,
      "name": "Rutoken ECP"
   },
   {
      "enable": false,
      "error": "100:failed to load p11 module",
      "name": "ISBC ESMART"
   }
]

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

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

• true – параллельное обращение к модулям (рекомендуемый режим);
• false – последовательное обращение к модулям.

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

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

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

• sn – серийный номер сертификата;
• subject – данные о субъекте, которому выдан данный сертификат электронной подписи. Возвращается в виде json в формате «параметр: значение», где параметр – это название соответствующего объектного идентификатора (OID). Всем стандартным объектным идентификаторам даны общепринятые обозначения, например, CN (Common Name).
• issuer – данные об издателе сертификата ключа электронной подписи. Возвращается в виде json в формате «параметр: значение», где параметр – это название соответствующего объектного идентификатора (OID). Всем стандартным объектным идентификаторам даны общепринятые обозначения;
• not_before – время начала действия сертификата (тип данных – строка в формате ASN1_TIME);
• not_after – время окончания действия сертификата (тип данных – строка в формате ASN1_TIME);
• key_usage – информация о назначении ключа, возвращается в виде массива.

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

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

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

• label – имя ключевого контейнера средства электронной подписи;
• manufacturerID – идентификатор производителя средства электронной подписи;
• model – модель средства электронной подписи;
• serialNumber – серийный номер средства электронной подписи.

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

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

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

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

• строка для подписи;
• количество попыток ввода пин-кода (например, значение «1» означает, что у пользователя имеется только одна попытка, после чего функция возвращает ошибку).
• тип подписи — является ли подпись присоединенной (необходимо передавать значение true) или отсоединенной (false).

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

cms_sign_on_it("1234", 3, true).then(function(cms){console.log(cms)});

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

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

• подписывать данные большого объема, например, файлы;
• подписывать несколько файлов без повторного запроса пин-кода.

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

• тип подписи — является ли подпись присоединенной (необходимо передавать значение true) или отсоединенной (false);
• количество попыток ввода пин-кода (например, значение «1» означает, что у пользователя имеется только одна попытка, после чего функция возвращает ошибку).

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

• add_data_in_hex(hexDataString) — принимает на вход данные в виде hex строки;
• add_data_in_base64(base64DataString) — принимает на вход данные в виде base64 строки;
• add_data_in_string(stringData) — принимает на вход данные в виде utf-8 строки;
• free() — возвращает значение true/false, что позволяет проверить, что сертификат готов к подписанию. Требуется использовать для случая, когда несколько итераций подписи осуществляются на разных сертификатах. Иными словами, если осуществляется последовательное подписание на нескольких сертификатах, то перед подписанием необходимо вызвать этот метод и убедиться, что он вернул true;
• finish() — финализирует подпись и возвращает ее в формате CAdES-BES / PKCS#7.

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

Подписание строки

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

signer.add_data_in_string("1234").then(function(res){ return signer.finish();}).then(function(cms){console.log(cms)});

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

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

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

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

function sign(cert, info) {

     function successCms(signature) {
      alert(signature);
     }

     cert.start_signing(false, 3)
      .then(
       function(signer) {
        signer.add_data_in_base64("MTIzNDU2")
         .then(function() {
            var data = signer.finish();
                    var free = signer.free(); 
             return data; 
         }, e)
         .then(successCms, e);
       },
      e);
    }

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

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

   function readFileByChunk(file, cbToRead, cbToFinish) {
       var fileSize   = file.size;
       var chunkSize  = 1024*1024; // bytes
       var offset     = 0;
       var chunkReaderBlock = null;
       var self       = this;

       var readEventHandler = function(evt) {
           if (evt.target.error == null) {
               cbToRead(evt.target.result, offset, fileSize);
               offset += evt.target.result.byteLength;
           } else {
               console.error("Read error: " + evt.target.error);
               showError("Ошибка чтения файла: " + evt.target.error);
               return;
           }
           if (offset >= fileSize) {
               cbToFinish()
               return;
           }

           // to the next chunk
           chunkReaderBlock(offset, chunkSize, file);
       }

       chunkReaderBlock = function(_offset, _chunkSize, _file) {
         var r = new FileReader();
         if (_file.slice) {
           var blob = _file.slice(_offset, _chunkSize + _offset);
         } else if (_file.webkitSlice) {
           var blob = _file.webkitSlice(_offset, _chunkSize + _offset);
         } else if (_file.mozSlice) {
           var blob = _file.mozSlice(_offset, _chunkSize + _offset);
         }
         r.onload = readEventHandler;
         r.readAsArrayBuffer(blob);
       }

       // start reading the first block
       chunkReaderBlock(offset, chunkSize, file);
   }

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

Ниже приведены примеры типовых ошибок, возникающих у пользователей при установке Blitz Smart Card Plugin.

Ошибка при установке Blitz Smart Card Plugin. Код ошибки 2738
Рекомендация:
Ошибка 2738 связана с доступом к скрипту VBScript при работе установщика.
Возможные причины:

1. Недостаточно прав доступа. Необходимо проводить установку под учетной записью администратора.
2. VBScript не зарегистрирован в системе (актуально для Windows 7);
3. Некорректно работает или не запускается установщик Windows;
4. Конфликт с установленным антивирусом.

Для решения данной проблемы обратитесь к технической поддержке Microsoft Windows.

Ошибка пакета установщика Windows. Код ошибки 1720
Рекомендация:
При возникновении данной ошибки можно попробовать выполнить следующие действия:

1. Нажать «Пуск», ввести cmd, нажать правой клавишей и выбрать «Запуск от имени администратора».
2. Последовательно выполнить команды:

   msiexec /unreg
   msiexec /regserver

3. Перезапустить компьютер.

Также может помочь следующее:

1. Запустить «Диспетчер задач».
2. Найти процесс msiexec.exe
3. Выбрать его и принудительно завершить.

Ошибка непроверенного разработчика плагина при установке под macOS Catalina
Рекомендация:
Установить обновленную версию плагина под macOS Catalina с сайта разработчика.

Ошибка при установке плагина для работы в терминальной среде или на ПК под управлением серверной ОС
Рекомендация:
Blitz Smart Card Plugin не работает на ПК под управлением серверных ОС, например, под Windows Server.

Лог работы Blitz Smart Card Plugin в среде Windows записывается в директорию текущего пользователя:

C:\Users\<USERNAME>\AppData\Roaming\REAKSOFT\Blitz Smart Card Plugin\1.16.0.1\

Брендированные сборки плагина на основе Blitz Smart Card Plugin устанавливаются в директорию, соответствующую названию этого плагина. Например, плагин Fedresurs DS Plugin устанавливается в директорию:

C:\Users\<USERNAME>\AppData\Roaming\REAKSOFT\Fedresurs DS Plugin\1.16.0.1\

В среде macOS лог записывается в директорию:

/Users/<USERNAME>/Library/Logs/

В среде Linux лог записывается в директорию:

/tmp/

Журнал событий записывается в файл blitzScPlugin.log. При обнаружении проблем этот файл необходимо переслать в службу технической поддержки.