signtool sign 命令参考

说明

本文中的 signtool 指锐安信远程代码签名客户端 CLI，不是 Microsoft Windows SDK 自带的 signtool.exe。使用 Windows SDK 工具时会明确写成 Microsoft signtool.exe。

signtool sign 直接对本地文件执行远程签名。CLI 在本地提取待签名数据，调用远程服务完成私钥签名，再把签名、时间戳和证书信息写回输出文件。

signtool sign [flags]

查看帮助与版本：

signtool --help
signtool --version

---

凭证配置

sign 命令通过以下方式读取访问凭证：

凭证项	参数	环境变量	说明
Access Key	--access-key / -k	ACCESS_KEY	参数为空时自动读取环境变量
Access Secret	--access-secret / -s	ACCESS_SECRET	参数为空时自动读取环境变量

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

远程服务地址由 --address 参数控制，支持以下值：

参数值	实际服务地址
nicsrs	https://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	-1	false	启用 SHA1 签名。
--sha2	-2	true	启用 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 实际值	用途
--timestamp	http://timestamp.sectigo.com	SHA1 Authenticode 时间戳
--timestamp-rfc3161	http://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。