GitHub — vgoma/crypto-pro: API для взаимодействия с КриптоПро

/certificates — все установленные сертификаты пользователя

Если сертификатов нет:

Если сертификаты есть:

{
  "certificates": [
    {
      "privateKey": {
        "providerName": "Crypto-Pro GOST R 34.10-2022 KC1 CSP",
        "uniqueContainerName": "HDIMAGE\eb5f6857.000\D160",
        "containerName": "eb5f6857-a08a-4510-8a96-df2f75b6d65a"
      },
      "algorithm": {
        "name": "ГОСТ Р 34.10-2022",
        "val": "1.2.643.7.1.1.1.1"
      },
      "valid": {
        "to": "24.05.2022 08:13:16",
        "from": "24.02.2022 08:03:16"
      },
      "issuer": {
        "E": "support@cryptopro.ru",
        "C": "RU",
        "L": "Moscow",
        "O": "CRYPTO-PRO LLC",
        "CN": "CRYPTO-PRO Test Center 2",
        "raw": "CN=CRYPTO-PRO Test Center 2, O=CRYPTO-PRO LLC, L=Moscow, C=RU, E=support@cryptopro.ru"
      },
      "subject": {
        "C": "RU",
        "L": "Test",
        "O": "Test",
        "OU": "Test",
        "CN": "Test",
        "E": "test@test.ru",
        "raw": "E=test@test.ru, CN=Test, OU=Test, O=Test, L=Test, S=Test, C=RU"
      },
      "thumbprint": "982AA9E713A2F99B10DAA07DCDC94A4BC32A1027",
      "serialNumber": "120032C3567443029CC358FCDF00000032C356",
      "hasPrivateKey": true
    }
  ],
  "status": "ok"
}

/cosign — добавление еще одной подписи к документу

Не реализовано, столкнулся с проблемой: не получается заставить работать функцию CPSignedData::CoSignCades().

/sign — подписание документов

Для выбора сертификата для подписания нужно указать один критерии поиска find_type:

• sha1 — по SHA1 сертификата
• subject — по subject подписанта

В query — параметры поиска, в pin — пин-код (если он установлен):

Вернется JSON — документ, в signedContent будет содержаться подписанный файл.

/unsign — получение исходного файла без подписей

Исходный файл вернется в поле content.

/verify — проверка подписанного документа

Подпишем файл и проверим его:

Если файл прошел проверку, вернется список подписантов signers.

Angular (es modules typescript)

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

Запуск в продакшн режиме:

npm run build
npm run serve

Cryptopro

Единое, асинхронное API для взаимодействия с КриптоПРО ЭЦП Browser Plug-In

Аналоги

Существует аналогичный пакет CryptoProCSP, он классный, но:

• давно не обновлялся, используется версия PHP5.6
• для запуска пришлось подредактировать Dockerfile

Без скачивания на диск

Примечание: по какой-то причине иногда «заедает», но при повторном запуске — срабатывает.

Возможные проблемы

В Dockerfile содержатся названия пакетов, например lsb-cprocsp-devel-4.0.9921-5.noarch.rpm, которые могут заменить новой версией. Следует поправить названия пакетов в Dockerfile.

Запуск контейнера

Запустим контейнер под именем cryptopro, к которому будем обращаться в примерах:

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

Устанавливаем зависимости:

Во время работы с кодом необходим запущенный сборщик:

И пример, на котором можно тестировать изменения.
Удобнее всего тестировать на примере с тэгом script, тк он отвязан от фреймворков
и использует сборку в формате UMD из папки dist/, постоянно обновляемую пока работает
сборщик. Запускаем его таким образом:

После выполнения npm link ../../ в директории examples/script-tag/node_modules папка crypto-pro станет ярлыком,
указывающим на папку содержащую локально собранный пакет.

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

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

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

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

или это (ES Modules Typescript):

Использование контейнера на удаленной машине

В примерах выше команды выглядят так: cat … | docker … или curl … | docker …, то есть контейнер запущен на локальной машине. Если же докер контейнер запущен на удаленной машине, то команды нужно отправлять через ssh клиент. Например, команда подписания:

Опция -q отключает приветствие из файла /etc/banner (хотя оно все равно пишется в stderr). А /etc/motd при выполнении команды по ssh не выводится.

В качестве эксперимента можно отправить по ssh на свою же машину так:

Криптопро — alt linux — портал поддержки спо и импортозамещения

# создаем каталог для репозитория
mkdir -p /opt/repo/multiarch/RPMS.dir
# копируем все rpm из комплекта в папку (не забываем про плагин)
cp *.rpm /opt/repo/multiarch/RPMS.dir
# добавляем репозиторий
apt-repo add 'rpm-dir file:/opt/repo/ multiarch dir'
# устанавливаем необходимые пакеты в 2 прохода
apt-get update
apt-get install cryptopro-preinstall-full lsb-cprocsp-capilite-64 
apt-get install cprocsp-compat-altlinux-64 cprocsp-rdr-gui-gtk-64 cprocsp-rdr-jacarta-3.6.1 cprocsp-rdr-pcsc-64 cprocsp-rdr-rutoken-64 lsb-cprocsp-pkcs11-64 lsb-cprocsp-kc1-64 cprocsp-pki-cades cprocsp-pki-plugin 

Криптопро 4.0 в докер контейнере

Содержимое контейнера:

Лицензия

Установка серийного номера:

Просмотр:

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

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

Миграция с версии 1 на 2

Внесены следующие изменения:

• Пакет собран в форматах:
  • UMD, в папке dist/, для подключения через тэг script. Объект window.cryptoPro доступен глобально.
  • ES Modules, в папке lib/, для использования с разными системами сборки.
    Методы API импортируются напрямую из npm пакета.
• В UMD версии переименован глобальный объект с window.CryptoPro на window.cryptoPro
• Переименованы общие методы:
• Убран метод signDataXML
• Переименованы методы сертификата:
• Результат методов сертификата getOwnerInfo и getIssuerInfo
  изменился с { descr, title, translated } на { description, title, isTranslated }
• Принципиальная реализация методов, обращающихся к Крипто ПРО не изменилась.
  Получение сертификатов, создание подписи, проверка корректности настроек работают по-прежнему.
• Убрана поддержка IE8 (Крипто ПРО его больше не поддерживает)
• Убрана поддержка КриптоПРО CSP версий ниже 4.0
• Убрана поддержка КриптоПРО ЭЦП browser plug-in версий ниже 2.0
• Доработана обработка ошибок, выбрасываемых из Крипто ПРО
• При написании кода будут работать автодополнения и подсказки
• Исправлена проблема работы библиотеки с UglifyJs
• Методы API доступны напрямую:

В версии 1:

В версии 2 (UMD):

В версии 2 (ES Modules):

Настройка плагина для firefox (до версии 52)

После настройки плагина на страницах, запрашивающих работу с ЭП в панели навигации, рядом с url будет кнопка,
позволяющая «разрешить и запомнить» использование установленного плагина.

Перезапустите Firefox, и убедитесь в наличии CryptoPRO Cades plugin (см. Menu -> Addons).

Обработка ошибок

Успешные действия возвращают код 200 и «status»: «ok».

Действия с ошибками возвращают 4xx и 5xx коды и «status»: «fail», в полях errMsg содержится описание ошибки, в errCode — ее код.

Например, обращение с неправильным методом

выведет такую ошибку:

Поддерживаемые скзи

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

КриптоПРО ЭЦП browser plug-in (v2.0.12438 ).

Инструкция по установке плагина в Linux. В Windows и OSX следуйте указаниям программы-установщика.

Инструкция по установке сертификатов в систему для Linux / OSX.

Подписание документа

Для примера установим этот тестовый сертификат:

Его SHA1 Hash равен dd45247ab9db600dca42cc36c1141262fa60e3fe (узнать: certmgr -list), который будем использовать как указатель нужного сертификата.

Теперь передадим на stdin файл, в качестве команды — последовательность действий, и на stdout получим подписанный файл:

Получилось довольно неудобно. Скрипт scripts/sign делает то же самое, теперь команда подписания будет выглядеть так:

Об ошибке можно узнать через стандартный $?.

Получение исходного файла из sig-файла

Возьмем файл из примера выше:

То же самое, но с использованием скрипта:

Примеры

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

Проблемы

Если pin-код не подходит, то в терминал выводится:

И подписание останавливается.

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

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

npm run package
mv package ..

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

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

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

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

Проверка подписи

Подпишем файл из примера выше и сохраним его на диск:

Тогда проверка подписанного файла будет выглядеть так:

То же самое, но с использованием скрипта:

Проверка работы примеров с react и angular

React и Angular используют версию сборки пакета в формате ES модулей из директории lib/.
Для их запуска необходимо сначала собрать пакет выполнив:

После этого из папки examples/angular или examples/react залинковать пакет:

И запустить пример в одном из двух режимов. В режиме разработки:

или в режиме продакшн:

npm run build
npm run serve

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

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

Установка

Для NPM:

Для Yarn:

Для Bower:

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

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

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

• Promise
• Array.prototype.find

Установка корневых сертификатов

Для установки корневых сертификатов нужно на stdin скрипта /scripts/root передать файл с сертификатами. Если в файле несколько сертификатов, все они будут установлены.

Установка криптопро 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:

Установите дополнительно 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:

Установите пакеты:

dpkg -i cprocsp-pki-cades_2.0.0-2_amd64.deb
dpkg -i cprocsp-pki-plugin_2.0.0-2_amd64.deb

Проверьте наличие файлов плагина:

Установка сертификатов в linux

В OSX процесс схож с Linux.

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

Скопируйте ключевой контейнер \.FLASH.sidorov на жесткий диск:

Наличие [ErrorCode: 0x00000000] в завершении каждой команды КриптоПРО говорит о ее успешном выполнении.

Проверьте наличие нового контейнера \.HDIMAGEsidor:

Установите личный сертификат:

Возможно в выводе вы ссылку на сертификат УЦ

При необходимости загрузите сертификат удостоверяющего центра и установите его командой:

После чего, при проверке установленного личного сертификата вы увидите PrivateKey Link: Yes:

/opt/cprocsp/bin/amd64/certmgr -list -store uMy

Установка сертификатов пользователя для проверки и подписания

Необходимо специальным образом сформировать zip-архив bundle.zip и отправить его на stdin скрипта /scripts/my. Пример такого zip-файла:

Как получить сертификат КриптоПро.

Первый найденный файл в корне архива будет воспринят как сертификат, а первый найденный каталог — как связка файлов закрытого ключа. Пароль от контейнера, если есть, передается первым параметром командной строки.

В каталоге certificates/ содержатся различные комбинации тестового сертификата и закрытого ключа, с PIN кодом и без:

Примеры:

Формат данных

Для POST данные должны поступать в теле запроса в формате x-www-form-urlencoded.

Возвращаются данные в формате JSON.

Через скачивание на диск

Скачаем сертификат на диск с помощью curl и передадим полученный файл на stdin с запуском команды его установки: