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

Справочник по команде signtool sign

Примечание

В этой статье signtool означает CLI удаленного код-подписания sslTrus, а не signtool.exe, входящий в Microsoft Windows SDK. При использовании инструмента Windows SDK это будет явно указано как Microsoft signtool.exe.

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

signtool sign [flags]

Просмотр справки и версии:

signtool --help
signtool --version

Настройка учетных данных​

Команда sign считывает учетные данные доступа следующими способами:

Элемент учетных данныхПараметрПеременная окруженияОписание
Access Key--access-key / -kACCESS_KEYЕсли параметр пуст, значение автоматически считывается из переменной окружения
Access Secret--access-secret / -sACCESS_SECRETЕсли параметр пуст, значение автоматически считывается из переменной окружения
export ACCESS_KEY="your-access-key"
export ACCESS_SECRET="your-access-secret"

Адрес удалённого сервиса управляется параметром --address и поддерживает следующие значения:

Значение параметраФактический адрес сервиса
nicsrshttps://ssl.face.nicsrs.com
Пустое значение, racent или любое другое значениеhttps://ssl.face.racent.com
Внимание
  • ACCESS_KEY и ACCESS_SECRET — это фактические имена переменных окружения, которые считываются, а SIGNTOOL_ACCESS_KEY / SIGNTOOL_ACCESS_SECRET не будут автоматически считываться текущим CLI.
  • Не рекомендуется записывать Access Secret в историю shell или в репозиторий скриптов; предпочтительно использовать переменные окружения, внедряемые во время выполнения, или безопасные переменные CI.

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

ПараметрСокращениеЗначение по умолчаниюОписание
--address-aпустоИдентификатор адреса удалённого сервиса, не является параметром прямой передачи URL.
--access-key-kпустоЕсли пусто, читается ACCESS_KEY.
--access-secret-sпустоЕсли пусто, читается ACCESS_SECRET.
--cert-code-cпустоОбязательно. Номер сертификата.
--file-f空Обязательно. Путь к файлу для подписания, не может быть каталогом.
--out-o空Путь к выходному файлу; если пусто и перезапись не включена, автоматически создаётся имя файла по умолчанию.
--override—falseПерезаписать исходный файл выходным файлом.
--sha1-1falseВключить подпись SHA1.
--sha2-2trueВключить подпись SHA2.
--timestamp—autoАдрес отметки времени SHA1 Authenticode. auto использует адрес по умолчанию, пустая строка отключает.
--timestamp-rfc3161—autoАдрес отметки времени SHA2 RFC3161. auto использует адрес по умолчанию, пустая строка отключает.
--desc-nпустоТекст описания программы, записываемый в подпись.
--url-uпустоURL информации о программе, записываемой в подпись.
--nest—trueСохранить существующую подпись и добавить вложенную подпись; при false очистить существующую подпись.
--verify—falseПри добавлении подписи вернуть ошибку, если сертификат не является доверенным.
--dry-run—falseИспользуйте локальный тестовый сертификат для создания подписи, без вызова удалённого интерфейса подписи.
Формат булевых параметров

Булевы параметры должны использовать формат 参数=值, формат с разделением пробелами не поддерживается:

  • Правильно: --sha1=true --sha2=false
  • Неправильно: --sha1 true --sha2 false

Обязательные правила​

Перед выполнением проверяются следующие условия, при невыполнении любого из них выводится ошибка и выполнение прекращается:

  • --access-key или ACCESS_KEY должен существовать.
  • --access-secret или ACCESS_SECRET должен существовать.
  • --cert-code должен существовать.
  • --file должен существовать и не может быть каталогом.
  • --sha1 и --sha2 — по крайней мере один должен быть включён.

Правила для выходных файлов​

Когда --out не указан:

--overrideПоведение вывода
false (по умолчанию)Вывод в ту же директорию, что и входной файл, с именем файла ${name}.signed.${yyyyMMdd.HHmmss}${ext}
trueПерезаписать входной файл напрямую

Пример:

app.exe    → app.signed.20260611.153000.exe
driver.sys → driver.signed.20260611.153000.sys
Внимание

--override=true перезапишет исходный файл, перед выполнением убедитесь, что сделана резервная копия. При сбое подписи CLI постарается удалить незавершённые выходные файлы.

Выбор алгоритма​

По умолчанию включён только SHA2:

signtool sign -c CERT_CODE -f app.exe

Только подпись SHA1:

signtool sign -c CERT_CODE -f app.exe --sha1=true --sha2=false

Одновременная подпись SHA1 и SHA2:

signtool sign -c CERT_CODE -f app.exe --sha1=true --sha2=true
Примечание

При одновременном включении SHA1 и SHA2 процесс сначала обрабатывает SHA1, затем SHA2. SHA1 в настоящее время по-прежнему поддерживается, но в новых сценариях подписи приоритет отдаётся SHA2.

Настройка метки времени​

Значения auto для --timestamp и --timestamp-rfc3161 на этапе проверки заменяются адресами по умолчанию:

ПараметрФактическое значение autoНазначение
--timestamphttp://timestamp.sectigo.comМетка времени SHA1 Authenticode
--timestamp-rfc3161http://timestamp.sectigo.comМетка времени SHA2 RFC3161

Пользовательская служба меток времени SHA2:

signtool sign \
  -c CERT_CODE \
  -f app.exe \
  --timestamp-rfc3161=http://timestamp.acs.microsoft.com

Отключить временную метку SHA2:

signtool sign -c CERT_CODE -f app.exe --timestamp-rfc3161=

Отключить все временные метки:

signtool sign -c CERT_CODE -f app.exe --timestamp= --timestamp-rfc3161=
Примечание
  • Используются только адреса временных меток, начинающиеся с http.
  • Для SHA1 приоритетно используется --timestamp; если это не HTTP-адрес, предпринимается попытка использовать --timestamp-rfc3161.
  • Для SHA2 используется --timestamp-rfc3161.
  • Если добавление временной метки для SHA2 не удалось, автоматически выполняется одна повторная попытка с адресами Microsoft и Sectigo по умолчанию.
  • Сбой временной метки не обязательно приводит к ошибке подписи: CLI зафиксирует ошибку и сохранит результат подписи без временной метки.

Часто используемые примеры​

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

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

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

Передача учётных данных напрямую через параметры:

signtool sign \
  --access-key "your-access-key" \
  --access-secret "your-access-secret" \
  --cert-code CERT_CODE \
  --file app-unsigned.exe \
  --out app-signed.exe

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

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

Введите описание программы и URL официального сайта:

signtool sign \
  -c CERT_CODE \
  -f app-unsigned.exe \
  -o app-signed.exe \
  --desc "Example Application" \
  --url "https://example.com"

Добавление вложенной подписи (с сохранением существующей подписи):

signtool sign -c CERT_CODE -f app.exe --nest=true

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

signtool sign -c CERT_CODE -f app.exe --override=true

dry-run локальное тестовое подписание (без вызова удалённого интерфейса):

signtool sign \
  -k dummy \
  -s dummy \
  -c CERT_CODE \
  -f app.exe \
  --dry-run=true
Примечание

--dry-run не вызывает удалённый интерфейс подписи, но по-прежнему читает и записывает локальные файлы и вызывает локально самоподписанный сертификат. В настоящее время по-прежнему выполняется проверка непустых значений учётных данных и номера сертификата, поэтому в примере используются заполнители учётных данных.

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

Сообщение об ошибкеВозможная причинаРекомендация по устранению
access key is required...Не передан --access-key, и не задан ACCESS_KEY.Задайте переменную окружения или используйте -k.
access secret is required...Не передан --access-secret и не задан ACCESS_SECRET.Задайте переменную окружения или используйте -s.
cert code is required...Не передан номер сертификата.Используйте -c CERT_CODE.
sha1 or sha2 is required...Одновременно отключены SHA1 и SHA2.Включите хотя бы один алгоритм.
file <path> is a directory--file указывает на каталог, а не на файл.Укажите путь к файлу, который нужно подписать.
Не удалось поставить метку времени, но файл подписи созданСлужба меток времени недоступна или не прошла проверка цепочки сертификатов.Проверьте URL метки времени, при необходимости замените --timestamp-rfc3161.
Последнее обновление