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

Команда 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.

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

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

ПараметрФактическое значение 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.
Последнее обновление