signtool sign 命令參考

說明

本文中的 signtool 指 sslTrus 遠端程式碼簽章用戶端 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。