跳至主要内容

用戶端工具

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

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

SignTool CLI​

SignTool CLI 是 sslTrus 提供的遠端程式碼簽章命令列客戶端，安裝後的可執行檔名稱為 signtool。

它主要提供以下能力：

功能命令說明
檔案簽章signtool sign對本機檔案執行遠端程式碼簽章
簽章額度signtool quota查詢證書的剩餘和總簽章額度
客戶端更新signtool update查詢並安裝目前平台的最新客戶端
Windows KSPsigntool ksp安裝和管理 Windows Key Storage Provider
Windows CSPsigntool 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 或桌面用戶端。

公開儲存庫：ssltrus-official/homebrew-tap

安裝 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，並可以在構建流程中直接對指定檔案完成遠端程式碼簽名。

公開儲存庫：ssltrus-official/code-sign-action

完整配置請參閱 CI/CD 與構建工具。

如何選擇​

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

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

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

最後於 更新