Windows Provider

sslTrus предоставляет два способа интеграции с Windows Provider: KSP (Key Storage Provider) и CSP (Cryptographic Service Provider).

С помощью Windows Provider такие программы, как Microsoft SignTool, Visual Studio, MSBuild, средства создания установочных пакетов и другое программное обеспечение, поддерживающее криптографические интерфейсы Windows, могут использовать возможности облачной подписи кода sslTrus.

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

Установка, настройка и обслуживание KSP и CSP выполняются через sslTrus SignTool CLI, который можно загрузить со страницы выпусков клиента sslTrus.

KSP и CSP

KSP и CSP соответствуют двум поколениям криптографических интерфейсов Windows:

Provider	Интерфейс Windows	Подходящие сценарии
KSP	CNG (Cryptography API: Next Generation)	Современные приложения Windows и средства подписи, предпочтительный выбор
CSP	CryptoAPI	Традиционные приложения или программное обеспечение, явно требующее использования CSP

Для новых сценариев интеграции с Windows обычно предпочтительнее использовать KSP.

Используйте CSP только в том случае, если целевое программное обеспечение не поддерживает KSP или явно требует использования традиционного CryptoAPI Provider.

KSP

KSP — это Key Storage Provider на основе Windows CNG.

После установки sslTrus KSP приложения Windows, поддерживающие CNG, могут вызывать удалённый сервис подписи кода через стандартный интерфейс ключей Windows.

Локальный Provider отвечает за приём запросов на подпись от приложений и передачу дайджеста, который необходимо подписать, удалённому сервису подписи кода; фактические операции с закрытым ключом выполняются в облачном HSM.

Подходящие сценарии

KSP подходит для:

• Microsoft SignTool.
• Visual Studio.
• MSBuild.
• Программ сборки и подписи, поддерживающих Windows CNG.
• Приложений, которым требуется доступ к удалённому закрытому ключу через стандартный Windows Provider.

Установка KSP

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

signtool ksp install

Эта команда установит и зарегистрирует:

sslTrus Key Storage Provider

Установка KSP включает регистрацию системного провайдера и системные каталоги Windows, поэтому обычно требуются права администратора.

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

Выполните:

signtool ksp add

根据 подсказке введите:

Access Key
Access Secret
Certificate Code

Клиент получает соответствующий сертификат от удалённого сервиса подписи кода и сохраняет адрес удалённого сервиса, учётные данные доступа и конфигурацию сертификата.

Если используется среда NICSRS (www.nicsrs.com), необходимо добавить --address nicsrs:

signtool ksp add --address nicsrs

Регистрация сертификата

После завершения настройки KSP необходимо зарегистрировать сертификат для подписи кода в хранилище сертификатов Windows и связать его с KSP Provider.

Выполните:

signtool ksp register

По умолчанию регистрация выполняется в личное хранилище сертификатов текущего пользователя.

Если требуется регистрация в хранилище сертификатов LocalMachine:

signtool ksp register --store local-machine

После завершения регистрации Windows распознает соответствующий сертификат как имеющий доступный закрытый ключ, однако фактический закрытый ключ по-прежнему хранится в облачном HSM.

Использование Microsoft SignTool

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

Например:

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 ^
  ".\app.exe"

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

Параметр	Описание
/csp	Указывает провайдер sslTrus KSP
/kc	Указывает контейнер ключа, соответствующий номеру сертификата
/f	Указывает сертификат для подписи кода
/fd	Указывает алгоритм хеширования файла
/tr	Указывает сервер меток времени RFC 3161
/td	Указывает алгоритм хеширования для метки времени

Если необходимо добавить подпись SHA-1 поверх уже существующей, можно использовать параметр /as:

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 ^
  ".\app.exe"

Microsoft signtool.exe будет вызывать sslTrus KSP через Windows CNG, а затем KSP выполнит удалённую подпись закрытым ключом.

Управление KSP

Просмотр уже настроенных KSP:

signtool ksp list

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

signtool ksp del

Отменить привязку сертификата к KSP:

signtool ksp deregister

Удаление KSP:

signtool ksp uninstall

Перед удалением Provider убедитесь, что ни одно другое Windows-приложение больше не зависит от этого Provider.

CSP

CSP — это Cryptographic Service Provider, используемый традиционным Windows CryptoAPI.

Он в основном применяется в процессах подписи Windows, где требуется указать Provider и контейнер ключа через параметры /csp и /kc. Установку и обслуживание sslTrus CSP выполняет клиент, а фактическое подписание файла по-прежнему осуществляется с помощью Microsoft signtool.exe из Windows SDK.

Применимые сценарии

CSP подходит для:

• программ Windows, поддерживающих только традиционный CryptoAPI;
• инструментов подписи, которые явно требуют указания CSP Provider;
• сред, где необходимо выполнять подпись с помощью Microsoft SignTool с параметрами /csp и /kc;
• устаревших приложений, которые не могут использовать Windows CNG / KSP.

Для новых систем, которые могут нормально использовать KSP, обычно дополнительно использовать CSP не требуется.

Установка CSP

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

signtool csp install

В процессе установки будет зарегистрировано:

sslTrus Cryptographic Service Provider

и установите библиотеку Provider DLL в системе Windows.

Тип поставщика CSP:

PROV_RSA_AES

Локальная конфигурация по умолчанию сохраняется в:

%ProgramData%\sslTrusKSP

Файл конфигурации защищён с помощью Windows DPAPI.

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

signtool csp install --with-ksp

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

Выполните:

signtool csp add

Согласно подсказке введите:

Access Key
Access Secret
Certificate Code

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

%ProgramData%\sslTrusKSP\CERT_CODE.crt

При этом CERT_CODE одновременно используется как идентификатор удалённого сертификата и как имя контейнера ключа, которое в дальнейшем применяется в Microsoft SignTool.

Если используется среда NICSRS (www.nicsrs.com), необходимо добавить --address nicsrs:

signtool csp add --address nicsrs

Регистрация сертификата

По умолчанию сертификат регистрируется в личном хранилище сертификатов текущего пользователя:

signtool csp register

Если требуется регистрация в LocalMachine:

signtool csp register --store local-machine

Поддерживаемые хранилища сертификатов включают:

Параметр	Хранилище сертификатов Windows
current-user	CurrentUser\My
local-machine	LocalMachine\My

После завершения регистрации диспетчер сертификатов Windows покажет, что соответствующий сертификат связан с закрытым ключом, однако сам закрытый ключ по-прежнему находится в облачном HSM.

Использование Microsoft SignTool

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

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 CSP
/kc	Указание контейнера ключа, соответствующего номеру сертификата
/f	Указание сертификата для подписи кода
/fd	Указание алгоритма хеширования файла
/tr	Указание сервера меток времени RFC 3161
/td	Указание алгоритма хеширования метки времени

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

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

После завершения подписи её можно проверить с помощью Microsoft SignTool:

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

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

Управление CSP

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

signtool csp list

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

signtool csp del

Отмена привязки закрытого ключа между сертификатом и CSP:

signtool csp deregister

Удаление Provider:

signtool csp uninstall

Удаление конфигурации CSP не приводит к автоматическому удалению уже загруженных файлов сертификатов. Если соответствующие сертификаты и конфигурации больше не используются, их следует очистить только после подтверждения того, что от них не зависят другие Provider.

KSP или CSP

Если нет особых требований к совместимости, можно выбирать следующим образом:

Сценарий	Рекомендация
Новая среда подписи Windows	KSP
Поддержка Windows CNG	KSP
Современные инструменты Windows, такие как Microsoft SignTool	KSP
Программное обеспечение явно требует CSP	CSP
Традиционные приложения CryptoAPI	CSP
Инструменты требуют использования /csp и /kc	CSP

Основное различие между KSP и CSP заключается в разных интерфейсах криптографического Provider, используемых Windows; модель безопасности удалённого закрытого ключа остаётся одинаковой.

Независимо от того, используется ли KSP или CSP, закрытый ключ для подписи кода не сохраняется на локальном клиенте.

Количество подписей

Количество подписей Windows Provider рассчитывается по фактически выполненным удалённым действиям подписи на нижнем уровне.

Например:

SHA256 签名一次 = 1 次

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

В сценарии KSP двойная подпись SHA256 и SHA1 для одного файла обычно приводит к двум вызовам базовой операции подписи.

Конкретные правила см. в справочных материалах.

Отметка времени

Для подписи Windows Authenticode обычно рекомендуется добавлять доверенную отметку времени.

В современных сценариях подписи кода рекомендуется в первую очередь использовать отметку времени RFC 3161, например:

http://timestamp.acs.microsoft.com

В производственной среде следует выбирать подходящий TSA в зависимости от целевой версии Windows, политики сертификатов, сетевого окружения и требований поставщика службы отметок времени.

Конкретные серверы отметок времени и описание протоколов см. в справочных материалах.

Указания по безопасности

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

• Access Secret следует защищать как конфиденциальные учётные данные.
• Не записывайте учётные данные для доступа в общедоступные скрипты или журналы.
• Файл конфигурации Provider не подлежит публичному распространению.
• Локальный файл сертификата не содержит закрытый ключ для подписи кода.
• Закрытый ключ для подписи кода всегда хранится в облачном HSM.
• При инициировании подписи через KSP/CSP требуется доступ к удалённому сервису подписи кода.
• При использовании хранилища сертификатов LocalMachine следует обращать особое внимание на права пользователей Windows и область доступа к учётным данным.

config.dat в CSP защищается с помощью DPAPI профиля текущего пользователя Windows; регистрация сертификата в LocalMachine не изменяет автоматически область защиты DPAPI этой конфигурации.