用戶端工具

sslTrus 提供命令列用戶端和桌面用戶端，用於連接遠端程式碼簽署服務並完成檔案簽署。

其中，SignTool CLI 適合命令列、指令碼和自動化情境；macOS 使用者也可以透過 Homebrew 安裝和更新 SignTool CLI 或桌面用戶端。

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

版本資訊中包含用戶端版本、建置 revision、執行平台和建置時間等資訊。

存取憑證

使用遠端程式碼簽署服務前，需要準備：

Access Key
Access Secret
憑證編號（Cert Code）

其中 Access Key 和 Access Secret 用於存取遠端程式碼簽署服務，憑證編號用於指定實際執行簽署的程式碼簽署憑證。

SignTool CLI 可以透過命令參數提供憑證，也可以透過環境變數讀取：

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

建議優先透過環境變數、CI/CD Secret 或其他安全的憑證管理方式提供 Access Secret。

不要將 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

SignTool CLI 會自動讀取對應的存取憑證。

預設使用 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：SHA-2 簽章使用的 RFC 3161 時間戳伺服器。
--timestamp：SHA-1 簽章使用的 Authenticode 時間戳伺服器。

指定 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=

有關時間戳記協定、伺服器位址及選擇建議，請參閱參考資料。

查詢簽章額度

使用：

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 使用者可以透過 sslTrus 官方 Homebrew Tap 安裝 SignTool CLI 或桌面用戶端。

安裝 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

如果你的情境不是直接呼叫 SignTool CLI，而是希望 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 自動簽署

如果需要在持續整合或自動建置過程中執行簽署，不一定需要手動安裝和呼叫 SignTool CLI。

例如 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 Runner，並可以在建置流程中直接對指定檔案完成遠端程式碼簽署。

完整設定請參閱 CI/CD 與建置工具。

如何選擇

可以根據實際使用方式選擇合適的用戶端或整合方式：

情境	建議方式
在終端機中手動簽署檔案	SignTool CLI
使用指令碼批次呼叫簽署	SignTool CLI
查詢程式碼簽署額度	SignTool CLI
macOS 安裝和更新 CLI	Homebrew
macOS 使用桌面用戶端	Homebrew
Microsoft SignTool 等 Windows 軟體直接呼叫遠端私密金鑰	KSP
傳統 CryptoAPI 軟體	CSP
GitHub Actions 自動簽署	GitHub Actions
自行開發簽署用戶端	遠端程式碼簽署 API

如果你的應用程式已經支援 Windows KSP、CSP 或其他標準 Provider，通常應優先使用對應的標準整合方式；如果需要直接控制簽署流程，則可以使用 SignTool CLI 或遠端程式碼簽署 API。

SignTool CLI​

下載用戶端​

檢視用戶端資訊​

存取憑證​

遠端服務位址​

檔案簽章​

指定輸出檔案​

覆寫原檔案​

指定程式描述​

SHA-1 和 SHA-2​

時間戳​

查詢簽章額度​

更新用戶端​

macOS Homebrew​

安裝 Homebrew Tap​

安裝 SignTool CLI​

安裝桌面用戶端​

更新客戶端​

Windows Provider​

CI/CD 自動簽署​

如何選擇​