[![NPM version][npm-version-image]][npm-url]
[![NPM downloads][npm-downloads-image]][downloads-url]
[![Coverage Status][coveralls-image]][coveralls-url]

CryptoPro CSP

Асинхронное API для работы с КриптоПРО ЭЦП Browser Plug-In, с поддержкой строгой (self) политики CSP (Content Security Policy).

Список поддерживаемых браузеров

Имеют встроенное расширение:
- Яндекс.Браузер для организаций;
- Chromium-Gost.

Необходимо самостоятельно включить расширение в браузере после установки плагина:

- Google Chrome (в том числе Chromium версии 104+);
- Microsoft Edge (на базе Chromium версии 104+);
- Яндекс Браузер (на базе Chromium версии 104+);
- Mozilla Firefox;
- Apple Safari;
- Opera.

Демо (на базе ./examples/script-tag)

CAdES — это расширенный стандарт электронной подписи, разработанный для обеспечения долгосрочной подлинности и целостности подписанных данных, с поддержкой таких возможностей, как отметка доверенного времени и хранение информации для долгосрочного подтверждения подписи.

В браузерах CAdES реализуется обычно через плагин или расширение, например, «КриптоПро ЭЦП Browser plug-in» (также известный как КриптоПро CADESCOM или Кадеском), который необходим для работы с электронной подписью на разных порталах и торговых площадках. Этот плагин/расширение позволяет пользователям создавать и проверять подписи непосредственно в браузере, используя криптографические сервисы, и применяется в таких браузерах как Microsoft Edge, Opera, Mozilla Firefox, Google Chrome и Яндекс.Браузер (не поддерживается в Internet Explorer). Для работы с этим плагином обязательно наличие установленного криптографического провайдера, например, КриптоПро CSP.


Навигация

- CryptoPro CSP
- Список поддерживаемых браузеров
- Демо (на базе ./examples/script-tag)
- Навигация
- Зачем мне этот пакет?
- Установка
- API
- Методы объекта cryptoPro
- Методы объекта сертификата
- Поддерживаемые СКЗИ
- Примеры
- Тэг script (UMD)
- Angular (ES Modules + Typescript)
- React (ES Modules + JavaScript)
- Тем, кто хочет помочь
- Запуск режима разработки
- Запуск тестов
- Проверка работы примеров с React и Angular
- Проверка пакета перед публикацией в NPM
- Лицензия

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

КриптоПРО ЭЦП Browser Plug-In доступен в разных браузерах в двух версиях:
асинхронной (в современных браузерах) и синхронной (в браузерах постарше). Синхронная версия для старых браузеров поддерживалась через функцию ``eval()`, которая является дырой в безопасности и несовместима с жесткой политикой CSP `script-src 'self'`. Так как требование к безопасности веб-приложений растут с каждым годом было принято решение пожертвовать поддержкой старых браузеров для успешной работы в новых с соблюдением политики CSP `script-src 'self'`. Подробнее о проблеме с реализацией синхронной версии при CSP можно почитать в этом issue. Для этого были удалены вызовы функций `eval()` и заменены на генераторы.




Установка


Для NPM:
`bash
npm install crypto-pro-csp-compatible --save-dev
`

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

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


`

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

(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 - возвращает флаг корректности настроек ЭП на машине

$3

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

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

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

КриптоПРО ЭЦП browser plug-in

Примеры

Для их запуска необходим 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
`




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

Буду благодарен за расширение/улучшение/доработку 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-csp-compatible станет ярлыком,
> указывающим на папку содержащую локально собранный пакет.




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


Тесты написаны с использованием 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 build
npm pack
mv package ..
`
> Важно переместить папку package куда-нибудь выше для избежания конфликтов при линковке с текущим package.json.

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

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

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

Лицензия

MIT

[npm-url]: https://npmjs.org/package/crypto-pro-csp-compatible
[npm-version-image]: http://img.shields.io/npm/v/crypto-pro-csp-compatible.svg?style=flat
[npm-downloads-image]: http://img.shields.io/npm/dm/crypto-pro-csp-compatible.svg?style=flat
[downloads-url]: https://npmcharts.com/compare/crypto-pro-csp-compatible?minimal=true
[coveralls-image]: https://coveralls.io/repos/github/pustart/crypto-pro-csp-compatible/badge.svg?branch=master
[coveralls-url]: https://coveralls.io/github/pustart/crypto-pro-csp-compatible?branch=master