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:

npm install crypto-pro-js

Для Yarn:

yarn add crypto-pro-js

Для Bower:

bower install webmasterskaya/crypto-pro-js

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

<script src="crypto-pro-js/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-js';

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

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

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

• Promise
• Array.prototype.find

API

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

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

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

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

Сертификат предоставляет следущее API:

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

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

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

Примеры

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

Тэг script (UMD)

cd examples/script-tag
npm i
npm start

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

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

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

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

npm test

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

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

npm run package
mv package ..

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

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

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

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

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

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

Лицензия

MIT