crypto-pro-ne
v3.0.2
Published
API для взаимодействия с КриптоПро
Downloads
78
Maintainers
Readme
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 |
Зачем мне этот пакет?
КриптоПРО ЭЦП 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, в папке
- В 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