crypto-pro-js — npm

Angular (es modules typescript)

Запуск в режиме разработки:

Запуск в продакшн режиме:

npm run build
npm run serve

Cryptopro

Единое, асинхронное API для взаимодействия с КриптоПРО ЭЦП Browser Plug-In

Запуск режима разработки

Устанавливаем зависимости:

Во время работы с кодом необходим запущенный сборщик:

И пример, на котором можно тестировать изменения.
Удобнее всего тестировать на примере с тэгом script, тк он отвязан от фреймворков
и использует сборку в формате UMD из папки dist/, постоянно обновляемую пока работает
сборщик. Запускаем его таким образом:

После выполнения npm link ../../ в директории examples/script-tag/node_modules папка crypto-pro станет ярлыком,
указывающим на папку содержащую локально собранный пакет.

Запуск тестов

Тесты написаны с использованием Jest:

Зачем мне этот пакет?

КриптоПРО ЭЦП Browser Plug-In доступен в разных браузерах в двух версиях.
Асинхронной (в современных браузерах) и синхронной (в браузерах постарше).
С помощью этого пакета можно не писать реализацию под каждую версию плагина дважды.
И вместо этого
и этого
написать это (UMD):

или это (ES Modules Typescript):

Использование

Полный пример использования можно посмотреть на странице example.html.

Лицензия

MIT

Методы объекта cryptopro

*Методы getContainerCertificates и getAllContainerCertificates позволяют получить сертификаты из закрытых ключей, записанных на обыкновенную флэшку

Методы объекта сертификата

Сертификат предоставляет следущее API:

Миграция с версии 1 на 2

Внесены следующие изменения:

• Пакет собран в форматах:
  • UMD, в папке dist/, для подключения через тэг script. Объект window.cryptoPro доступен глобально.
  • ES Modules, в папке lib/, для использования с разными системами сборки.
    Методы API импортируются напрямую из npm пакета.
• В UMD версии переименован глобальный объект с window.CryptoPro на window.cryptoPro
• Переименованы общие методы:
• Убран метод signDataXML
• Переименованы методы сертификата:
• Результат методов сертификата getOwnerInfo и getIssuerInfo
  изменился с { descr, title, translated } на { description, title, isTranslated }
• Принципиальная реализация методов, обращающихся к Крипто ПРО не изменилась.
  Получение сертификатов, создание подписи, проверка корректности настроек работают по-прежнему.
• Убрана поддержка IE8 (Крипто ПРО его больше не поддерживает)
• Убрана поддержка КриптоПРО CSP версий ниже 4.0
• Убрана поддержка КриптоПРО ЭЦП browser plug-in версий ниже 2.0
• Доработана обработка ошибок, выбрасываемых из Крипто ПРО
• При написании кода будут работать автодополнения и подсказки
• Исправлена проблема работы библиотеки с UglifyJs
• Методы API доступны напрямую:

В версии 1:

В версии 2 (UMD):

В версии 2 (ES Modules):

Настройка плагина для firefox (до версии 52)

После настройки плагина на страницах, запрашивающих работу с ЭП в панели навигации, рядом с url будет кнопка,
позволяющая «разрешить и запомнить» использование установленного плагина.

Перезапустите Firefox, и убедитесь в наличии CryptoPRO Cades plugin (см. Menu -> Addons).

Необработанная подпись

Сервис Подписи DSS позволяет формировать необработанную подпись двумя способами:

Ошибка параметр задан неверно. (0x80070057)

Если при попытке подписать сообщение с использованием PKCS#7 подписи падает такая ошибка, то читайте этот issue

Перед использованием

Перед использованием Crypto-JS необходимо произвести установку КриптоПро CSP и КриптоПро ЭЦП Browser plug-in по инструкции ниже и запросить сертификат в удостоверяющем центре (например, в тестовом центре КриптоПро).

КриптоПро CSP

КриптоПро ЭЦП Browser plug-in

В результате установки КриптоПро ЭЦП Browser plug-in должен увидеть установленные в вашей системе сертификаты.

Проверить работу плагина можно на специальной странице

Подписание

Класс CryptoHelper содержит несколько методов подписания данных:

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

Подпись в формате cades-xlt1/cades-t

Сервис Подписи DSS позволяет создавать следующие виды подписи в формате CAdES-XLT1/CAdES-T:

Подпись в формате cms

Сервис Подписи DSS позволяет создавать следующие виды CMS-подписи:

Подпись в формате xmldsig

REST-интерфейс Сервиса Подписи позволяет формировать XML-подпись следующими способами:

Получение сертификатов

Их хранилища пользователя запрашиваются только активные и валидные сертификаты.

letcertificates=awaitcrypto.getCertificates();// => [{// 		$original: Object,// 		subject: Object { name, email, company, city, ...},// 		issuer: Object { name, email, company, ...},// 		version: 3,// 		serialNumber: "12003B1267D658852004813D6F0001003B1267",// 		thumbprint: "75C9AD57EEC3A3E914FE1EDB518BD817EDE81797",// 		validFrom: "2022-09-18T11:38:09.000Z",// 		validTo: "2022-12-18T11:48:09.000Z",// 		hasPrivate: true,// 		isValid: true// }, ...]

Пользовательский сертификат

При выполнении любой операции подписи Сервис должен располагать информацией о сертификате ключа подписи.
Это можно сделать двумя способами:

• передача идентификатора сертификата в запросе на формирование подписи
• использование сертификата по умолчанию

Для получения идентификтора сертификата можно воспользоваться методом GetCertificates.

Если необходимо использовать сертификат по умолчанию, то в качестве идентификатора сертификата в запросе следует передавать значение 0, предварительно назначив один из сертификатов пользователя сертификатом по умолчанию.

Примеры

Для их запуска необходим NodeJS LTS.

Примеры запросов

Запрос

Примечание

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

В поле OriginalDocument необходимо передавать исходный документ.

В запросе должен присутствовать параметр CmsSignatureType, имеющий значение countersign.

В запросе может присутствовать параметр SignatureIndex, указывающий индекс заверяемой подписи. В случае, если данный параметр отсутствует в запросе, Сервис Подписи будет заверять первую подпись в документе.

Проверка пакета перед публикацией в npm

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

npm run package
mv package ..

Важно переместить папку package куда-нибудь выше для избежания конфликтов при линковке с текущим package.json.

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

Проверяем работу примеров в режимах разработки и продакшн.

После завершения экспериментов можно удалить глобальную ссылку из директории ../../../package таким образом:

Проверка работы примеров с react и angular

React и Angular используют версию сборки пакета в формате ES модулей из директории lib/.
Для их запуска необходимо сначала собрать пакет выполнив:

После этого из папки examples/angular или examples/react залинковать пакет:

И запустить пример в одном из двух режимов. В режиме разработки:

или в режиме продакшн:

npm run build
npm run serve

Создание экземпляра

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

Тем, кто хочет помочь

Буду благодарен за расширение/улучшение/доработку API.
Вам будут полезны примеры,
предоставляемые Крипто ПРО.

Установка

Для NPM:

npm install crypto-pro-js

Для Yarn:

Для Bower:

bower install webmasterskaya/crypto-pro-js

Подключение пакета как UMD модуля через тэг script:

Подключение пакета как ES модуля с Typescript или JavaScript:

Список требуемых полифиллов (если необходимы, подключаются самостоятельно):

• Promise
• Array.prototype.find

Установка криптопро csp в linux / osx

Процесс установки в OSX незначительно отличается от Linux, поэтому описание приведено на примере дистрибутива семейства Debian (x64).

Некоторые команды могут потребовать запуска с sudo.
Названия файлов и директорий могут отличаться из-за различий в версиях.

После загрузки КриптоПРО CSP для нужной платформы, распакуйте архив:

tar -xzvf linux-amd64_deb.tgz
chmod 777 -R linux-amd64_deb/

Запустите скрипт установки:

linux-amd64_deb/install.sh

Проверьте отсутствиеcprocsp-rdr-gui:

Установите дополнительно cprocsp-rdr-gui-gtk:

dpkg -i linux-amd64_deb/cprocsp-rdr-gui-gtk-64_4.0.0-4_amd64.deb

Дополнительная информация по установке

Установка криптопро эцп browser plugin в linux

Загрузите КриптоПРО ЭЦП browser plug-in и распакуйте его:

mkdir cades_linux_amd64
tar -xzvf cades_linux_amd64.tar.gz -C cades_linux_amd64

Сконвертируйте rpm в deb пакеты при помощи утилиты alien:

Установите пакеты:

dpkg -i cprocsp-pki-cades_2.0.0-2_amd64.deb
dpkg -i cprocsp-pki-plugin_2.0.0-2_amd64.deb

Проверьте наличие файлов плагина:

Установка сертификатов в linux

В OSX процесс схож с Linux.

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

Скопируйте ключевой контейнер \.FLASH.sidorov на жесткий диск:

Наличие [ErrorCode: 0x00000000] в завершении каждой команды КриптоПРО говорит о ее успешном выполнении.

Проверьте наличие нового контейнера \.HDIMAGEsidor:

Установите личный сертификат:

Возможно в выводе вы ссылку на сертификат УЦ

При необходимости загрузите сертификат удостоверяющего центра и установите его командой:

После чего, при проверке установленного личного сертификата вы увидите PrivateKey Link: Yes:

/opt/cprocsp/bin/amd64/certmgr -list -store uMy

Форматы подписи

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

Типовые ошибки