[![NPM version][npm-version-image]][npm-url]
[![NPM downloads][npm-downloads-image]][downloads-url]
[![Build Status][travis-image]][travis-url]
[![Coverage Status][coveralls-image]][coveralls-url]
[![Examples][examples-image]][examples-url]
[![Donate][donate-image]][donate-url]

cryptoPro

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

|  |  |  |  |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| __v45+__ с расширением CryptoPro Extension for CAdES Browser Plug-in | __v43+__. Начиная с версии 52, с расширением | __v9+__ с установленным КриптоПро ЭЦП Browser plug-in | __v40+__ с расширением CryptoPro Extension for CAdES Browser Plug-in |


- cryptoPro
- Зачем мне этот пакет?
- Установка
- API
- Методы объекта cryptoPro
- Методы объекта сертификата
- Поддерживаемые СКЗИ
- Примеры
- Тэг script (UMD)
- Angular (ES Modules + Typescript)
- React (ES Modules + JavaScript)
- Миграция с версии 1 на 2
- Тем, кто хочет помочь
- Запуск режима разработки
- Запуск тестов
- Проверка работы примеров с React и Angular
- Проверка пакета перед публикацией в NPM
- Полезная информация
- Установка КриптоПРО CSP в Linux / OSX
- Установка КриптоПРО ЭЦП browser plug-in в Linux
- Настройка плагина для Firefox (до версии 52)
- Установка сертификатов в Linux
- Лицензия

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

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

!example-umd.gif

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

!example-esm.gif

Установка

Для NPM:
``bash
npm install crypto-pro
`

Для Yarn:
`bash
yarn add crypto-pro
`

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


`

Подключение пакета как ES модуля с Typescript или JavaScript:
`typescript
import { getUserCertificates, Certificate } from 'crypto-pro';

(async () => {
let certificates: Certificate[];

try {
certificates = await getUserCertificates();
} catch(error) {
// ...
}
})();
`

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




API




$3

- getUserCertificates - возвращает список сертификатов, доступных пользователю в системе
- getCertificate - возвращает сертификат по отпечатку
- createAttachedSignature - создает совмещенную (присоединенную) подпись сообщения
- createDetachedSignature - создает отсоединенную (открепленную) подпись сообщения
- createXMLSignature - создает XML подпись для документа в формате XML
- createHash - создает хеш сообщения по ГОСТ Р 34.11-2012 256 бит
- createSignature - создает подпись сообщения
> Является устаревшим и будет убран из будущих версий.
Используйте "createAttachedSignature" и "createDetachedSignature".
- getSystemInfo - возвращает информацию о CSP и плагине
- isValidSystemSetup - возвращает флаг корректности настроек ЭП на машине
- execute - компилирует и выполняет переданную функцию для доступной браузерной среды (синхронной/асинхронной)

$3

Сертификат предоставляет следущее API:
- isValid - возвращает флаг действительности сертификата
- getCadesProp - возвращает указанное внутренее свойство у сертификата в формате Cades
- exportBase64 - возвращает сертификат в формате base64
- getAlgorithm - возвращает информацию об алгоритме сертификата
- getOwnerInfo - возвращает расшифрованную информацию о владельце сертификата
- getIssuerInfo - возвращает расшифрованную информацию об издателе сертификата
- getExtendedKeyUsage - возвращает ОИД'ы сертификата
- getDecodedExtendedKeyUsage - возвращает расшифрованные ОИД'ы
- hasExtendedKeyUsage - проверяет наличие ОИД'а (ОИД'ов) у сертификата

Поддерживаемые СКЗИ

КриптоПРО CSP (v4.0+) рекомендуется использование только сертифицированных версий. Инструкция по установке:
- Linux / OSX
- (в Windows следуйте указаниям программы-установщика)

КриптоПРО ЭЦП browser plug-in (v2.0.12438+).

Инструкция по установке плагина в Linux. В Windows и OSX следуйте указаниям программы-установщика.

Инструкция по установке сертификатов в систему для Linux / OSX.

Примеры

Для их запуска необходим NodeJS версии, указанной в .nvmrc.

$3

`bash
cd examples/script-tag
npm i
npm start
`

$3

`bash
cd examples/angular
npm i
`

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

Запуск в продакшн режиме:
`bash
npm run build
npm run serve
`




$3


`bash
cd examples/react
npm i
`

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

Запуск в продакшн режиме:
`bash
npm run build
npm run serve
`




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


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

В версии 1:
`javascript
window.CryptoPro.call('getSystemInfo');
`

В версии 2 (UMD):
`javascript
window.cryptoPro.getSystemInfo();
`

В версии 2 (ES Modules):
`javascript
import { getSystemInfo } from 'crypto-pro';

getSystemInfo();
`




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

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

Необходима NodeJS версии, указанной в .nvmrc.
На машине должен быть установлен Python 2.7.18.

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

Устанавливаем зависимости:
`bash
npm i
`

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

И пример, на котором можно тестировать изменения.
Удобнее всего тестировать на примере с тэгом script, тк он отвязан от фреймворков
и использует сборку в формате UMD из папки dist/, постоянно обновляемую пока работает
сборщик. Запускаем его таким образом:
`bash
cd examples/script-tag
npm i
npm link ../../
npm start
`
> После выполнения npm link ../../ в директории examples/script-tag/node_modules папка crypto-pro станет ярлыком,
> указывающим на папку содержащую локально собранный пакет.




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


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

Проверка работы примеров с React и Angular

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

После этого из папки examples/angular или examples/react залинковать пакет:
`bash
cd examples/angular
npm i
npm link ../../
`

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

или в режиме продакшн:
`bash
npm run build
npm run serve
`




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


Необходимо протестировать работу в заявленных браузерах, сделав это на локально запакованной версии пакета.
Для этого собираем пакет:
`bash
npm run package
mv package ..
`
> Важно переместить папку package куда-нибудь выше для избежания конфликтов при линковке с текущим package.json.

Переходим в любую директорию с примером и создаем там ссылку на только что собранный пакет:
`bash
cd examples/script-tag
npm link ../../../package
`

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

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




Полезная информация




Установка КриптоПРО CSP в Linux / OSX

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

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

После загрузки КриптоПРО CSP для нужной платформы, распакуйте архив:
`bash
tar -xzvf linux-amd64_deb.tgz
chmod 777 -R linux-amd64_deb/
`

Запустите скрипт установки:
`bash
linux-amd64_deb/install.sh
`

Проверьте отсутствие cprocsp-rdr-gui:
`bash
dpkg -l | grep cprocsp-rdr
`

Установите дополнительно cprocsp-rdr-gui-gtk:
`bash
dpkg -i linux-amd64_deb/cprocsp-rdr-gui-gtk-64_4.0.0-4_amd64.deb
`

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




Установка КриптоПРО ЭЦП browser plugin в Linux


Загрузите КриптоПРО ЭЦП browser plug-in и распакуйте его:
`bash
mkdir cades_linux_amd64
tar -xzvf cades_linux_amd64.tar.gz -C cades_linux_amd64
`

Сконвертируйте rpm в deb пакеты при помощи утилиты alien:
`bash
apt-get update && apt-get install alien
cd cades_linux_amd64
alien *
`

Установите пакеты:
`bash
dpkg -i cprocsp-pki-cades_2.0.0-2_amd64.deb
dpkg -i cprocsp-pki-plugin_2.0.0-2_amd64.deb
`

Проверьте наличие файлов плагина:
`bash
ls -la /opt/cprocsp/lib/amd64 | grep libnpcades

lrwxrwxrwx 1 root root 19 Окт 21 12:33 libnpcades.so -> libnpcades.so.2.0.0
lrwxrwxrwx 1 root root 19 Окт 21 12:33 libnpcades.so.2 -> libnpcades.so.2.0.0
-rwxr-xr-x 1 root root 2727236 Июн 8 14:33 libnpcades.so.2.0.0
`




$3

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

`bash
cd /usr/lib/mozilla/plugins

cp /opt/cprocsp/lib/amd64/libnpcades.so.2.0.0 ./
ldd libnpcades.so.2.0.0

cp /opt/cprocsp/lib/amd64/libnpcades.so.2.0.0 ./libnpcades.so
ldd libnpcades.so
`
Перезапустите Firefox, и убедитесь в наличии CryptoPRO Cades plugin (см. Menu -> Addons).




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

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

Подключите USB носитель с ключевыми контейнерами и проверьте результат команды:
`bash
/opt/cprocsp/bin/amd64/csptest -keyset -enum_cont -fqcn -verifyc

CSP (Type:80) v4.0.9009 KC1 Release Ver:4.0.9797 OS:Linux CPU:AMD64 FastCode:READY:AVX.
AcquireContext: OK. HCRYPTPROV: 16188003
\\.\FLASH\ivanov
\\.\FLASH\petrov
\\.\FLASH\sidorov
\\.\FLASH\vasiliev
\\.\FLASH\smirnov
OK.
Total: SYS: 0,020 sec USR: 0,060 sec UTC: 0,180 sec
`

Скопируйте ключевой контейнер \\.\FLASH\.\sidorov на жесткий диск:
`bash
/opt/cprocsp/bin/amd64/csptest -keycopy -contsrc '\\.\FLASH\sidorov' -contdest '\\.\HDIMAGE\sidor'

CSP (Type:80) v4.0.9009 KC1 Release Ver:4.0.9797 OS:Linux CPU:AMD64 FastCode:READY:AVX.
CryptAcquireContext succeeded.HCRYPTPROV: 38556259
CryptAcquireContext succeeded.HCRYPTPROV: 38770755
Total: SYS: 0,000 sec USR: 0,100 sec UTC: 14,920 sec
[ErrorCode: 0x00000000]
`
> Наличие [ErrorCode: 0x00000000] в завершении каждой команды КриптоПРО говорит о ее успешном выполнении.

Проверьте наличие нового контейнера \\.\HDIMAGE\sidor:
`bash
/opt/cprocsp/bin/amd64/csptest -keyset -enum_cont -fqcn -verifyc

CSP (Type:80) v4.0.9009 KC1 Release Ver:4.0.9797 OS:Linux CPU:AMD64 FastCode:READY:AVX.
AcquireContext: OK. HCRYPTPROV: 34554467
\\.\FLASH\ivanov
\\.\FLASH\petrov
\\.\FLASH\sidorov
\\.\FLASH\vasiliev
\\.\FLASH\smirnov
\\.\HDIMAGE\sidor
OK.
Total: SYS: 0,010 sec USR: 0,050 sec UTC: 0,130 sec
[ErrorCode: 0x00000000]
`

Установите личный сертификат:
`bash
/opt/cprocsp/bin/amd64/certmgr -inst -cont '\\.\HDIMAGE\sidor'
`
> Возможно в выводе вы ссылку на сертификат УЦ

При необходимости загрузите сертификат удостоверяющего центра и установите его командой:
`bash
/opt/cprocsp/bin/amd64/certmgr -inst -store uroot -file <файл сертификата>.crt
`

После чего, при проверке установленного личного сертификата вы увидите PrivateKey Link: Yes:
`bash
/opt/cprocsp/bin/amd64/certmgr -list -store uMy
``

Лицензия

MIT

[npm-url]: https://npmjs.org/package/crypto-pro
[npm-version-image]: http://img.shields.io/npm/v/crypto-pro.svg?style=flat
[npm-downloads-image]: http://img.shields.io/npm/dm/crypto-pro.svg?style=flat
[downloads-url]: https://npmcharts.com/compare/crypto-pro?minimal=true
[travis-url]: https://travis-ci.org/vgoma/crypto-pro
[travis-image]: http://img.shields.io/travis/vgoma/crypto-pro/master.svg?style=flat
[coveralls-image]: https://coveralls.io/repos/github/vgoma/crypto-pro/badge.svg?branch=master
[coveralls-url]: https://coveralls.io/github/vgoma/crypto-pro?branch=master
[donate-image]: https://img.shields.io/badge/%D1%81%D0%BF%D0%B0%D1%81%D0%B8%D0%B1%D0%BE-%E2%82%BD-yellow
[donate-url]: https://money.yandex.ru/to/410011609769902
[examples-image]: https://img.shields.io/badge/examples-folder-pink
[examples-url]: examples