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:

npm install crypto-pro-csp-compatible --save-dev

Для Yarn:

yarn add crypto-pro-csp-compatible

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

<script src="crypto-pro-csp-compatible/dist/crypto-pro-csp-compatible.min.js"></script>
<script>
window.cryptoPro.getUserCertificates()
  .then(function (certificates) {
    //...
  })
  .catch(function (error) {
    //...
  });
</script>

Подключение пакета как ES модуля с Typescript или JavaScript:

import { getUserCertificates, Certificate } from 'crypto-pro-csp-compatible';

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

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

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

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

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

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

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

Примеры

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

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

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

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

Тесты написаны с использованием 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 build
npm pack
mv package ..

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

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

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

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

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

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

Лицензия

MIT