Перейти к основному содержимому

Интеграция signtool ksp с Windows KSP

signtool ksp управляет Windows sslTrus Key Storage Provider (KSP). После установки и настройки KSP Microsoft signtool.exe может вызывать удалённый сервис подписи через CNG Provider, без необходимости хранить закрытый ключ локально.

Примечание

Все подкоманды signtool ksp поддерживаются только на платформе Windows. При выполнении любой подкоманды ksp на платформе, отличной от Windows, будет возвращено: key storage provider is only supported on windows

Обзор подкоманд​

signtool ksp [command]
ПодкомандаНазначение
installУстановить и зарегистрировать KSP DLL
uninstallОтменить регистрацию KSP и удалить DLL
listВывести сохранённые конфигурации ключей KSP
addДобавить конфигурацию ключа KSP (интерактивно)
delУдалить указанную конфигурацию ключа KSP (интерактивно)
Примечание

Параметр --address действует только вместе с ksp add и используется для получения PEM сертификата и сохранения адреса удалённого сервиса.

Установка KSP​

signtool ksp install

После выполнения:

  1. Запишите встроенный sslTrusKSP.dll в ProgramData/sslTrusKSP/sslTrusKSP.dll.
  2. Если версия DLL в ProgramData отличается от версии в System32, скопируйте DLL в System32.
  3. Зарегистрируйте CNG Provider: sslTrus Key Storage Provider.
  4. Сохраните файл конфигурации KSP ProgramData/sslTrusKSP/config.dat (шифрование DPAPI).
Внимание

install изменяет системную регистрацию CNG Provider, рекомендуется выполнять в терминале администратора. Если обнаружено, что версия DLL совпадает, будет записано ksp is already installed и выполнен немедленный возврат.

Удаление KSP​

signtool ksp uninstall

После выполнения:

  1. Удалите регистрацию CNG Provider: sslTrus Key Storage Provider.
  2. Удалите ProgramData/sslTrusKSP/sslTrusKSP.dll.
  3. Удалите sslTrusKSP.dll из System32.
Примечание

uninstall не удалит весь каталог ProgramData/sslTrusKSP. Сохранённые config.dat, файлы сертификатов и журналы необходимо очистить вручную.

Просмотр конфигурации ключа​

signtool ksp list

Описание выходных полей:

ПолеЗначение
NoПорядковый номер
CertCodeНомер сертификата
ServerUrlОтображается как nicsrs или default
AccessKeyAccess Key
AccessSecretЗамаскированный Access Secret
Примечание
  • Если файл конфигурации отсутствует, возвращается no ksp configuration.
  • Если конфигурация существует, но список ключей пуст, зафиксируйте no ksp key.
  • AccessSecret отображается в маскированном виде, но сам файл конфигурации по-прежнему должен обрабатываться как конфиденциальный файл.

Добавление конфигурации ключа​

signtool ksp add

Укажите адрес NICSRS:

signtool ksp add --address nicsrs

Команда является интерактивной, вводите по очереди:

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

После выполнения:

  1. Вызов удалённого /v1/codesign/cert для получения PEM сертификата.
  2. Сохранение сертификата как ProgramData/sslTrusKSP/CERT_CODE.crt.
  3. Запись конфигурации ключа в ProgramData/sslTrusKSP/config.dat (шифрование DPAPI).

Если номер сертификата уже существует, появится提示:

The certificate code already exists, do you want to override it? [y/N]

Введите y для перезаписи; при вводе другого значения или нажатии Enter без ввода операция будет отменена.

Внимание

ksp add является интерактивной командой; в настоящее время неинтерактивные параметры, такие как --access-key, --cert-code, не поддерживаются. Добавление конфигурации обращается к удалённому API и записывает PEM сертификата в локальную папку ProgramData.

Удаление конфигурации ключа​

signtool ksp del

Введите номер сертификата в интерактивном режиме:

Please enter the certificate code: CERT_CODE

После выполнения удалите соответствующую конфигурацию ключа из config.dat и повторно сохраните зашифрованный файл конфигурации.

Примечание

Текущая реализация удаляет только элемент конфигурации и не удаляет файл сертификата ProgramData/sslTrusKSP/CERT_CODE.crt.

Использование Microsoft signtool.exe через KSP​

После завершения настройки KSP используйте Microsoft signtool.exe из Windows SDK для вызова провайдера.

Внимание

signtool.exe в приведённых ниже командах — это инструмент, входящий в состав Microsoft Windows SDK, а не CLI sslTrus. Если оба инструмента присутствуют в текущем каталоге или в PATH, используйте полный путь к signtool.exe из Windows SDK, чтобы избежать путаницы.

Пример подписи SHA256:

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

Пример добавления подписи SHA1:

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

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

ПараметрЗначение
/csp "sslTrus Key Storage Provider"Указывает KSP Provider, установленный sslTrus
/kc CERT_CODEУказывает имя ключа KSP, по соглашению это номер сертификата
/f C:\ProgramData\sslTrusKSP\CERT_CODE.crtУказывает файл сертификата, сохранённый ksp add
/fd SHA256 или /fd SHA1Алгоритм дайджеста файла
/tr <url>Служба меток времени RFC3161
/td SHA256Алгоритм дайджеста метки времени
/asДобавить подпись, не перезаписывая существующую

Справочник по устранению неполадок​

Сообщение об ошибкеВозможная причинаРекомендация
key storage provider is only supported on windowsКоманда ksp выполнена на платформе, отличной от Windows.Выполняйте операции KSP только в Windows.
no ksp configurationФайл конфигурации KSP ещё не создан.Сначала выполните signtool ksp install и signtool ksp add.
no such certificate codeУказанный номер удаляемого сертификата не существует.Проверьте номер сертификата с помощью signtool ksp list.

Меры безопасности​

  • signtool ksp install и signtool ksp uninstall изменяют системные каталоги Windows и регистрацию CNG Provider, обычно требуются права администратора.
  • signtool ksp add обращается к удалённому интерфейсу сертификатов и записывает файлы сертификатов и зашифрованную конфигурацию в ProgramData/sslTrusKSP.
  • Access Secret, файлы конфигурации KSP и локальные журналы следует обрабатывать как конфиденциальную информацию, не записывать их в журналы или репозитории версий.
Последнее обновление