Skip to content

API для взаимодействия с КриптоПро

License

Notifications You must be signed in to change notification settings

cybermerlin/crypto-pro

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

NPM version NPM downloads Build Status Coverage Status Donate

cryptoPro

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

Chrome Firefox IE Opera
v45+ с расширением CryptoPro Extension for CAdES Browser Plug-in v43+. Начиная с версии 52, с расширением v9+ с установленным КриптоПро ЭЦП Browser plug-in v40+ с расширением CryptoPro Extension for CAdES Browser Plug-in

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

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

crypto-pro-umd.gif

или это (ES Modules):

crypto-pro-esm.gif

Установка

Для NPM:

npm install crypto-pro

Для Yarn:

yarn add crypto-pro

Для Bower:

bower install 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

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

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

Тэг 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. Вам будут полезны примеры, предоставляемые Крипто ПРО.

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

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

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

About

API для взаимодействия с КриптоПро

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 82.6%
  • TypeScript 17.4%