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

Интеграция 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, а не sslTrus CLI. Если оба инструмента присутствуют в текущем каталоге или 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 и локальные журналы следует обрабатывать как конфиденциальную информацию, не записывать их в журналы или репозитории версий.
Последнее обновление