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

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=

О протоколе 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.

Публичный репозиторий: ssltrus-official/homebrew-tap

Установка 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

Если ваш сценарий не предполагает прямого вызова CLI SignTool, а вместо этого требуется, чтобы 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

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

Например, 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 и позволяет выполнять удалённую подпись указанных файлов непосредственно в процессе сборки.

Публичный репозиторий: ssltrus-official/code-sign-action

Полную конфигурацию см. в разделе 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 удалённой подписи кода.