Инструкция по использованию CSP

Обзор

Данная инструкция предназначена для настройки sslTrus Cryptographic Service Provider (CSP) в Windows и использования облачного HSM для подписи кода с помощью Microsoft signtool.exe из Windows SDK.

signtool csp данного проекта отвечает за установку, настройку и обслуживание провайдера; при фактической подписи используется signtool.exe из Windows SDK. Это не одна и та же программа.

sslTrus Cryptographic Service Provider — это традиционный CryptoAPI CSP, подходящий для процессов подписи Windows, которым требуется интеграция через /csp и /kc. Закрытый ключ подписи всегда хранится в облачном HSM; на локальной машине сохраняются только DLL CSP, сертификат подписи и конфигурация доступа, защищённая Windows DPAPI.

Подготовка перед использованием

• Система Windows x64.
• Терминал, запущенный от имени администратора, для установки или удаления провайдера.
• CLI signtool этого проекта, включая подкоманду csp.
• Установлен Windows SDK, и доступен Microsoft signtool.exe.
• Действительные Access Key, Access Secret и номер сертификата (CERT_CODE).
• Сеть имеет доступ к службе подписи кода и выбранной службе отметок времени.

Убедитесь, что оба инструмента работают по отдельности:

REM 本项目 CLI
signtool csp --help

REM Windows SDK 工具；必要时请使用其完整路径
signtool.exe sign /?

Если в текущем каталоге или в PATH одновременно присутствуют две программы с одинаковым именем, обязательно проверьте фактическую цель вызова с помощью полного пути или where.

Быстрый старт

В терминале администратора выполните по порядку:

signtool csp install
signtool csp add
signtool csp list

csp add будет в интерактивном режиме запрашивать ввод:

Please enter the access key: your-access-key
Please enter the access secret: your-access-secret
Please enter the certificate code: CERT_CODE

После успешной настройки используйте Microsoft signtool.exe для подписи с помощью Windows SDK:

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

Замените в примере CERT_CODE и app.exe на фактические номер сертификата и файл для подписи.

Установка Provider

Выполните:

signtool csp install

Эта команда:

• Запишет sslTrusCSP.dll в %ProgramData%\sslTrusKSP и скопирует его в системный каталог.
• Зарегистрирует sslTrus Cryptographic Service Provider (тип провайдера — PROV_RSA_AES).
• Установит сопутствующий KSP DLL и зарегистрирует sslTrus Key Storage Provider — псевдоним CNG-провайдера с тем же именем, что и CSP.
• Создаст или сохранит %ProgramData%\sslTrusKSP\config.dat; файл шифруется локальным Windows DPAPI.

Установка изменяет регистрацию провайдеров на уровне системы, поэтому обычно её нужно выполнять в терминале администратора. Если версия CSP DLL в системном каталоге совпадает со встроенной версией, CLI пропустит копирование CSP DLL, но всё равно выполнит регистрацию провайдера.

Добавление конфигурации сертификата

Выполните:

signtool csp add

Если необходимо использовать адрес службы NICSRS:

signtool csp add --address nicsrs

--address не является сквозным параметром URL. В настоящее время nicsrs использует службу NICSRS; пустое значение, racent или другие значения используют службу по умолчанию.

При добавлении CLI получает сертификат от удалённой службы и записывает:

%ProgramData%\sslTrusKSP\CERT_CODE.crt

Одновременно запишите адрес службы, учётные данные, номер сертификата и путь к сертификату в зашифрованный файл конфигурации. CERT_CODE является как идентификатором удалённого сертификата, так и значением /kc в последующем Microsoft signtool.exe.

Если добавляется уже существующий номер сертификата, CLI спросит, нужно ли перезаписать: введите y, чтобы заменить старую конфигурацию; если просто нажать Enter или ввести другое значение, исходная конфигурация останется без изменений.

Просмотр и удаление конфигурации

Просмотр текущей конфигурации:

signtool csp list

Выходные данные включают номер сертификата, тип услуги, Access Key и частично скрытый Access Secret. Пожалуйста, не загружайте вывод команд, файлы конфигурации или журналы в общедоступные места.

Удалить определённую конфигурацию:

signtool csp del

Введите номер сертификата согласно подсказке. Эта операция удаляет только соответствующую запись из конфигурации шифрования и не удаляет файл сертификата .crt с тем же именем; если он больше не используется, удалите этот файл вручную.

Подпись с помощью Microsoft signtool.exe

Подпись SHA-256

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

Описание параметров:

Параметр	Описание
/csp "sslTrus Cryptographic Service Provider"	Указывает поставщика CSP.
/kc CERT_CODE	Указывает контейнер ключа, соответствующий номеру сертификата.
/f <证书路径>	Указывает файл сертификата, загруженный с помощью csp add.
/fd SHA256	Указывает алгоритм вычисления дайджеста файла.
/tr <URL>	Указывает службу timestamping RFC 3161.
/td SHA256	Указывает алгоритм дайджеста для timestamp.

В настоящее время CSP поддерживает алгоритмы дайджеста файлов SHA1, SHA256, SHA384 и SHA512; для новых подписей обычно рекомендуется использовать SHA-256 или более поздние версии. Адрес службы штампов времени следует определять исходя из вашей политики сертификатов и совместимости с целевой платформой.

Добавление подписи SHA-1

Когда действительно требуется совместимость со старыми системами, поверх существующей подписи можно добавить SHA-1:

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA1 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  /as ^
  ".\app.exe"

/as означает добавление подписи без перезаписи существующей. Нужен ли SHA-1, следует определять исходя из целевой системы и политики сертификатов; его не следует выбирать по умолчанию для новых проектов.

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

После подписания можно выполнить проверку с помощью Microsoft signtool.exe:

signtool.exe verify /pa /v ".\app.exe"

Чтобы проверить все подписи, выберите соответствующие параметры проверки в соответствии с описанием версии и параметров Windows SDK signtool.exe.

Удаление Provider

Выполните в терминале администратора:

signtool csp uninstall

Эта команда отменяет регистрацию CSP, а также псевдонима CNG Provider с тем же именем, что и у CSP, и удаляет копии DLL CSP из ProgramData и системного каталога. Она не удаляет весь каталог %ProgramData%\sslTrusKSP и не удаляет автоматически сопутствующую регистрацию и DLL sslTrus Key Storage Provider; если этот KSP используется только в процессе установки CSP, выполняйте очистку осмотрительно с учётом фактического состояния развёртывания.

Если после удаления требуется удалить локальные конфиденциальные данные, сначала убедитесь, что они больше не используются KSP или другими процессами подписи, а затем вручную удалите конфигурацию, сертификаты и журналы из %ProgramData%\sslTrusKSP.

Часто задаваемые вопросы

Симптом	Рекомендация по устранению
cryptographic service provider is only supported on windows	Выполните команду управления CSP в Windows.
Ошибка прав доступа или сбой записи в системный каталог при установке	Используйте терминал администратора и выполните signtool csp install.
no csp configuration	Сначала выполните signtool csp install, затем выполните signtool csp add.
no such certificate code	Сначала проверьте номер сертификата с помощью signtool csp list.
Microsoft signtool.exe не может найти Provider	Убедитесь, что команда установки выполнена успешно, текущий инструмент и Provider — оба x64, затем снова откройте терминал и повторите попытку.
При подписании не найден файл сертификата	Убедитесь, что путь /f совпадает с csp add, загруженным в CERT_CODE.crt.
Ошибка вызова подписи	Проверьте номер сертификата, учетные данные службы и сетевое соединение; затем просмотрите %ProgramData%\sslTrusKSP\sslTrusCSP.log.
Использование пользовательского адреса службы, но запрос завершается ошибкой	CSP фиксированно запрашивает путь службы /v1/codesign/sign; в настраиваемом адресе службы следует указывать только http(s)://host[:port].

Примечания по безопасности

• Access Secret, config.dat, файлы сертификатов и журналы CSP следует обрабатывать как конфиденциальные материалы.
• config.dat защищён DPAPI профиля текущего пользователя Windows, при котором была создана конфигурация, поэтому его не следует напрямую копировать для повторного использования другим пользователям или на другие машины.
• CSP не сохраняет закрытый ключ; не пытайтесь импортировать закрытый ключ в %ProgramData%\sslTrusKSP.
• Для подписи CSP требуется доступ к удалённой службе; тайм-аут сети, отказ сервера или недоступность службы меток времени могут привести к сбою подписи.

Дополнительные сведения о параметрах CLI и командах подписи см. в справочнике по команде SignTool sign.