Клиентские инструменты

sslTrus предоставляет клиент командной строки и настольный клиент для подключения к удалённому сервису подписи кода и выполнения подписи файлов.

При этом SignTool CLI подходит для сценариев командной строки, скриптов и автоматизации; пользователи macOS также могут устанавливать и обновлять SignTool CLI или настольный клиент через Homebrew.

SignTool CLI

SignTool CLI — это клиент командной строки для удалённой подписи кода, предоставляемый sslTrus. После установки имя исполняемого файла — signtool.

Он предоставляет следующие основные возможности:

Функция	Команда	Описание
Подпись файла	signtool sign	Выполняет удалённую подпись локального файла
Квота подписи	signtool quota	Запрашивает оставшуюся и общую квоту подписи сертификата
Обновление клиента	signtool update	Запрашивает и устанавливает последнюю версию клиента для текущей платформы
Windows KSP	signtool ksp	Устанавливает и управляет Windows Key Storage Provider
Windows CSP	signtool csp	Устанавливает и управляет Windows Cryptographic Service Provider

KSP и CSP относятся к способам интеграции Windows Provider. Подробнее о порядке использования см. в разделе Windows Provider.

Загрузка клиента

SignTool CLI можно загрузить со страницы выпусков клиента sslTrus:

Страница выпусков клиента sslTrus

Страница выпусков предоставляет最新 установочные пакеты клиента для каждой платформы. В сценариях автоматизации также можно запрашивать информацию о последней версии через индекс версий latest.json.

Пользователи macOS также могут установить клиент напрямую через Homebrew, см. ниже macOS Homebrew.

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

После завершения установки можно выполнить:

signtool --help

Просмотр справки по команде.

Просмотр текущей версии клиента:

signtool --version

Информация о версии содержит сведения о версии клиента, ревизии сборки, платформе выполнения и времени сборки.

Учётные данные доступа

Перед использованием службы удалённого подписания кода необходимо подготовить:

• Access Key
• Access Secret
• Номер сертификата (Cert Code)

Access Key и Access Secret используются для доступа к службе удалённого подписания кода, а номер сертификата — для указания сертификата подписания кода, которым фактически выполняется подпись.

SignTool CLI может получать учётные данные через параметры команды или считывать их из переменных окружения:

export ACCESS_KEY="your-access-key"
export ACCESS_SECRET="your-access-secret"

Рекомендуется предоставлять Access Secret через переменные окружения, секреты CI/CD или другие безопасные способы управления учетными данными.

Не следует:

• Добавлять Access Secret в репозиторий Git.
• Вписывать его в общедоступные скрипты.
• Выводить его в логи сборки.
• Отправлять его в недоверенные сторонние системы.

Адрес удаленного сервиса

По умолчанию SignTool CLI использует производственный адрес сервиса sslTrus, дополнительная настройка не требуется.

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

signtool sign \
  --address nicsrs \
  --cert-code CERT_CODE \
  --file app.exe

signtool quota и signtool update также поддерживают --address nicsrs.

Подпись файла

С помощью signtool sign можно выполнять удалённую подпись кода непосредственно для локальных файлов.

Основная команда подписи:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe

Если уже настроено:

ACCESS_KEY
ACCESS_SECRET

CLI SignTool 会自动读取相应的访问凭证。

默认使用 SHA-2 进行签名。

指定输出文件

默认情况下，客户端不会直接覆盖原文件。

可以通过 --out 指定签名后的输出文件：

signtool sign \
  --cert-code CERT_CODE \
  --file app-unsigned.exe \
  --out app-signed.exe

Перезапись исходного файла

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

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --override=true

После включения --override результат подписи будет записан непосредственно обратно во входной файл.

При использовании в среде автоматизированной сборки следует убедиться, требуется ли на последующих этапах исходный файл или уже подписанный файл.

Указание описания программы

Описание программы и URL можно включить в подпись Authenticode:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --desc "Example Application" \
  --url "https://example.com"

SHA-1 и SHA-2

SHA-2 включён по умолчанию:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe

Использовать только SHA-1:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=false

Одновременно включите SHA-1 и SHA-2:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --sha1=true \
  --sha2=true

SHA-1 в основном используется для совместимости со старыми системами, в новых проектах обычно следует отдавать приоритет SHA-2.

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

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

SignTool CLI по умолчанию автоматически настраивает службу меток времени для подписи, также можно указать сервер меток времени через параметры:

• --timestamp-rfc3161: RFC 3161 сервер меток времени, используемый для подписи SHA-2.
• --timestamp: Authenticode сервер меток времени, используемый для подписи SHA-1.

Указание RFC 3161 сервера меток времени:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp-rfc3161=http://timestamp.acs.microsoft.com

Укажите сервер меток времени Authenticode:

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp=http://timestamp.sectigo.com

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

signtool sign \
  --cert-code CERT_CODE \
  --file app.exe \
  --timestamp-rfc3161= \
  --timestamp=

Сведения о протоколе штампов времени, адресах серверов и рекомендациях по выбору см. в справочных материалах.

Запрос квоты на подпись

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

signtool quota

Можно запросить квоту сертификатов подписи кода, доступную текущему токену доступа.

Выходные данные включают:

• Номер сертификата.
• Информация о сертификате.
• Оставшееся количество подписей.
• Общее количество подписей.

Если требуется вывод в формате JSON:

signtool quota --json

Также можно использовать сокращённую запись:

signtool quota -j

Конкретный способ подсчета количества подписей может различаться в зависимости от способа вызова CLI, KSP, Jarsigner или инструмента сборки. Подробные правила см. в Описание расчета количества подписей.

Обновление клиента

SignTool CLI поддерживает проверку и установку последней версии для текущей платформы:

signtool update

В процессе обновления проверяются размер загруженного файла и SHA-256, чтобы подтвердить целостность файлов клиента.

Если SignTool CLI был установлен через Homebrew, рекомендуется и дальше управлять версиями через Homebrew, а не смешивать два способа обновления.

macOS Homebrew

Пользователи macOS могут установить SignTool CLI или настольный клиент через официальный Homebrew Tap от sslTrus.

Установка Homebrew Tap

Выполните:

brew tap ssltrus-official/tap
brew trust ssltrus-official/tap

После завершения можно установить соответствующий клиент.

Установка SignTool CLI

Выполните:

brew install ssltrus-official/tap/code-sign-cli

После завершения установки можно выполнить:

signtool --version

Проверьте, корректно ли установлен клиент.

Название пакета в Homebrew:

code-sign-cli

Фактическое имя программы командной строки для установки:

signtool

Установка настольного клиента

Установите настольный клиент для подписи кода sslTrus:

brew install --cask ssltrus-official/tap/code-sign-gui

Соответствующее имя Homebrew Cask:

code-sign-gui

Обновление клиента

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

Сначала обновите информацию о пакетах Homebrew:

brew update

Обновите SignTool CLI:

brew upgrade ssltrus-official/tap/code-sign-cli

Обновите настольный клиент:

brew upgrade --cask ssltrus-official/tap/code-sign-gui

Это позволяет локальной установке соответствовать метаданным пакета Homebrew.

Windows Provider

Если ваш сценарий не предполагает прямого вызова SignTool CLI, а требует, чтобы Microsoft SignTool, Visual Studio, MSBuild, Advanced Installer или другое программное обеспечение Windows напрямую использовало закрытый ключ удалённого подписания кода, следует использовать Windows Provider.

sslTrus предоставляет:

• KSP (Key Storage Provider)：для Windows CNG.
• CSP (Cryptographic Service Provider)：для традиционного Windows CryptoAPI.

См. Windows Provider.

Автоматическое подписание в CI/CD

Если необходимо выполнять подписание в процессе непрерывной интеграции или автоматической сборки, не всегда требуется вручную устанавливать и вызывать SignTool CLI.

Например, GitHub Actions может напрямую использовать sslTrus Code Sign Action:

- name: Sign files
  uses: ssltrus-official/code-sign-action@v1
  with:
    access-key: ${{ secrets.SSLTRUS_ACCESS_KEY }}
    access-secret: ${{ secrets.SSLTRUS_ACCESS_SECRET }}
    cert-code: ${{ secrets.SSLTRUS_CERT_CODE }}
    files: build/app.exe

GitHub Action поддерживает раннеры Linux, macOS и Windows и позволяет выполнять удалённое подписание указанных файлов непосредственно в процессе сборки.

Полную конфигурацию см. в разделе CI/CD и средства сборки.

Как выбрать

Вы можете выбрать подходящий клиент или способ интеграции в зависимости от фактического способа использования:

Сценарий	Рекомендуемый способ
Ручное подписание файлов в терминале	SignTool CLI
Массовый вызов подписания с помощью скриптов	SignTool CLI
Проверка квоты подписания кода	SignTool CLI
Установка и обновление CLI в macOS	Homebrew
Использование настольного клиента в macOS	Homebrew
Прямой вызов удалённого закрытого ключа программами Windows, такими как Microsoft SignTool	KSP
Программы с традиционным CryptoAPI	CSP
Автоматическое подписание в GitHub Actions	GitHub Actions
Самостоятельная разработка клиента подписания	API удалённого подписания кода

Если ваше приложение уже поддерживает Windows KSP, CSP или других стандартных провайдеров, обычно следует в первую очередь использовать соответствующий стандартный способ интеграции; если же требуется напрямую управлять процессом подписания, можно использовать SignTool CLI или API удалённого подписания кода.