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

Обзор

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

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

sslTrus Cryptographic Service Provider — это традиционный CryptoAPI CSP, подходящий для процессов подписи в Windows, которым требуется интеграция через /csp и /kc. Закрытый ключ подписи всегда остаётся в облачном HSM; локально сохраняются только CSP DLL, сертификат подписи и конфигурация доступа, защищённая 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（Provider 类型为 PROV_RSA_AES）。
• 安装配套 KSP DLL，并注册 sslTrus Key Storage Provider 与 CSP 同名的 CNG Provider alias。
• 创建或保存 %ProgramData%\sslTrusKSP\config.dat；文件使用本机 Windows DPAPI 加密。

安装会修改系统级 Provider 注册，通常必须在管理员终端执行。若系统目录内的 CSP DLL 版本与内嵌版本一致，CLI 会跳过 CSP DLL 复制，但仍会执行 Provider 注册流程。

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

Выполните:

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>	Указывает службу меток времени RFC 3161.
/td SHA256	Указывает алгоритм хеширования для метки времени.

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

Добавление подписи 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 совпадает со скачанным CERT_CODE.crt из csp add.
Сбой вызова подписания	Проверьте номер сертификата, учётные данные службы и сетевое соединение; затем просмотрите %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 и командах подписи см. в справочнике по команде sign в SignTool.