[![License][license-image]][license-url]
[![NPM version][npm-version-image]][npm-url]
[![NPM downloads][npm-downloads-image]][downloads-url]
[![Build Status][actions-image]][actions-url]

cryptoPro

Асинхронный JavaScript API для работы с КриптоПРО ЭЦП Browser Plug-In

> Это форк проекта vgoma/crypto-pro
>
> API форка отличается от оригинала: внимательно читайте README

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

Ошибка Параметр задан неверно. (0x80070057)

Если при попытке подписать сообщение с использованием PKCS#7 подписи падает такая ошибка, то читайте этот issue

- cryptoPro
- Зачем мне этот пакет?
- Установка
- API
- Методы объекта cryptoPro
- Методы объекта сертификата
- Поддерживаемые СКЗИ
- Примеры
- Тэг script (UMD)
- Тем, кто хочет помочь
- Запуск режима разработки
- Запуск тестов
- Проверка пакета перед публикацией в NPM
- Лицензия

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

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

Установка

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

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

Для Bower:
`bash
bower install webmasterskaya/crypto-pro-js
`

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


`

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

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

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

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




API




$3

- getUserCertificates - возвращает список сертификатов, доступных пользователю в системе
- getAllUserCertificates - возвращает список сертификатов, доступных пользователю в системе, в том числе просроченные и без закрытого ключа
- getContainerCertificates - возвращает список сертификатов, из закрытых ключей и/или сертификаты не установленные всистеме*
- getAllContainerCertificates - возвращает список сертификатов, из закрытых ключей и/или сертификаты не установленные всистеме*, в том числе просроченные и без закрытого ключа
- getCertificate - возвращает сертификат по отпечатку
- createAttachedSignature - создает совмещенную (присоединенную) подпись сообщения
- createDetachedSignature - создает отсоединенную (открепленную) подпись сообщения
- addAttachedSignature - добавляет совмещенную (присоединенную) подпись к раннее подписанному документу (реализует метод coSign)
- addDetachedSignature - добавляет отсоединенную (открепленную) подпись к раннее подписанному документу (реализует метод coSign)
- createXMLSignature - создает XML подпись для документа в формате XML
- createHash - создает хеш сообщения по ГОСТ Р 34.11-2012 256 бит
- getSystemInfo - возвращает информацию о CSP и плагине
- isValidSystemSetup - возвращает флаг корректности настроек ЭП на машине

> *Методы getContainerCertificates и getAllContainerCertificates позволяют получить сертификаты из закрытых ключей, записанных на обыкновенную флэшку




$3

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

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

КриптоПРО CSP (v4.0+)

Примеры

Для их запуска необходим NodeJS LTS.

$3

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

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

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

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

Устанавливаем зависимости:
`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-js станет ярлыком,
> указывающим на папку содержащую локально собранный пакет.




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


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

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

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

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

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

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

Лицензия

MIT

[license-url]: /LICENSE
[license-image]: https://img.shields.io/github/license/webmasterskaya/crypto-pro-js
[npm-url]: https://npmjs.org/package/crypto-pro-js
[npm-version-image]: https://img.shields.io/npm/v/crypto-pro-js.svg?style=flat
[npm-downloads-image]: https://img.shields.io/npm/dm/crypto-pro-js.svg?style=flat
[downloads-url]: https://npmcharts.com/compare/crypto-pro-js?minimal=true
[actions-url]: https://github.com/webmasterskaya/crypto-pro-js/actions
[actions-image]: https://img.shields.io/github/workflow/status/webmasterskaya/crypto-pro-js/test?event=push