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
Тем, кто хочет помочь
Полезная информация
Лицензия

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

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

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

Установка

Для NPM:

npm install crypto-pro

Для Yarn:

yarn add crypto-pro

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

<script src="crypto-pro/dist/crypto-pro.min.js"></script>
<script>
window.cryptoPro.getUserCertificates()
  .then(function (certificates) {
    //...
  })
  .catch(function (error) {
    //...
  });
</script>

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

import { getUserCertificates, Certificate } from 'crypto-pro';

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

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

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

Promise
Array.prototype.find

API

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

getUserCertificates - возвращает список сертификатов, доступных пользователю в системе
getCertificate - возвращает сертификат по отпечатку
createAttachedSignature - создает совмещенную (присоединенную) подпись сообщения
createDetachedSignature - создает отсоединенную (открепленную) подпись сообщения
createXMLSignature - создает XML подпись для документа в формате XML
createHash - создает хеш сообщения по ГОСТ Р 34.11-2012 256 бит
createSignature - создает подпись сообщения

Является устаревшим и будет убран из будущих версий. Используйте "createAttachedSignature" и "createDetachedSignature".
getSystemInfo - возвращает информацию о CSP и плагине
isValidSystemSetup - возвращает флаг корректности настроек ЭП на машине
execute - компилирует и выполняет переданную функцию для доступной браузерной среды (синхронной/асинхронной)

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

Сертификат предоставляет следущее 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.

Тэг script (UMD)

cd examples/script-tag
npm i
npm start

Angular (ES Modules + Typescript)

cd examples/angular
npm i

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

npm start

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

npm run build
npm run serve

React (ES Modules + JavaScript)

cd examples/react
npm i

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

npm start

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

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:

window.CryptoPro.call('getSystemInfo');

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

window.cryptoPro.getSystemInfo();

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

import { getSystemInfo } from 'crypto-pro';

getSystemInfo();

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

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

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

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

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

npm i

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

npm start

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

cd examples/script-tag
npm i
npm link ../../
npm start

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

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

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

npm test

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

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

npm run build

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

cd examples/angular
npm i
npm link ../../

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

npm start

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

npm run build
npm run serve

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

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

npm run package
mv package ..

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

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

cd examples/script-tag
npm link ../../../package

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

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

cd ../../../package
npm unlink

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

Установка КриптоПРО 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:

dpkg -l | grep cprocsp-rdr

Установите дополнительно 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:

apt-get update && apt-get install alien
cd cades_linux_amd64
alien *

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

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

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

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

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

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

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 носитель с ключевыми контейнерами и проверьте результат команды:

/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 на жесткий диск:

/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:

/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]

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

/opt/cprocsp/bin/amd64/certmgr -inst -cont '\\.\HDIMAGE\sidor'

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

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

/opt/cprocsp/bin/amd64/certmgr -inst -store uroot -file <файл сертификата>.crt

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

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

Лицензия

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 144 Commits
examples		examples
resources		resources
src		src
types/cadesplugin		types/cadesplugin
.editorconfig		.editorconfig
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierrc.js		.prettierrc.js
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
definition-header.js		definition-header.js
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig-es5.json		tsconfig-es5.json
tsconfig-esm.json		tsconfig-esm.json
tsconfig.json		tsconfig.json
webpack.config.js		webpack.config.js

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

cryptoPro

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

Установка

API

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

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

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

Примеры

Тэг script (UMD)

Angular (ES Modules + Typescript)

React (ES Modules + JavaScript)

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

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

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

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

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

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

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

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

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

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

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

Лицензия

About

Releases 14

Packages

Contributors 5

Languages

License

vgoma/crypto-pro

Folders and files

Latest commit

History

Repository files navigation

cryptoPro

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

Установка

API

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

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

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

Примеры

Тэг script (UMD)

Angular (ES Modules + Typescript)

React (ES Modules + JavaScript)

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

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

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

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

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

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

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

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

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

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

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

Лицензия

About

Resources

License

Stars

Watchers

Forks

Releases 14

Packages 0

Contributors 5

Languages

Packages