客户端工具

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。