CSP 使用说明

概览

本说明用于在 Windows 上配置 sslTrus Cryptographic Service Provider（CSP），并通过 Windows SDK 的 Microsoft signtool.exe 使用云端 HSM 完成代码签名。

本项目的 signtool csp 负责安装、配置和维护 Provider；实际签名时使用的是 Windows SDK 的 signtool.exe。两者不是同一个程序。

sslTrus Cryptographic Service Provider 是传统 CryptoAPI CSP，适合需要通过 /csp 和 /kc 接入的 Windows 签名流程。签名私钥始终保留在云端 HSM，本机只保存 CSP DLL、签名证书和经 Windows DPAPI 保护的访问配置。

使用前准备

• Windows x64 系统。
• 以管理员身份运行的终端，用于安装或卸载 Provider。
• 本项目的 signtool CLI，且其中包含 csp 子命令。
• 已安装 Windows SDK，并能使用 Microsoft signtool.exe。
• 有效的 Access Key、Access Secret 和证书编号（CERT_CODE）。
• 网络可访问代码签名服务与所选时间戳服务。

确认两个工具分别可用：

REM 本项目 CLI
signtool csp --help

REM Windows SDK 工具；必要时请使用其完整路径
signtool.exe sign /?

如果当前目录或 PATH 中同时存在两个同名程序，务必通过完整路径或 where 确认实际调用目标。

快速开始

在管理员终端依次执行：

signtool csp install
signtool csp add
signtool csp list

csp add 会交互式要求输入：

Please enter the access key: your-access-key
Please enter the access secret: your-access-secret
Please enter the certificate code: CERT_CODE

配置成功后，使用 Windows SDK 的 Microsoft signtool.exe 签名：

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

将示例中的 CERT_CODE 和 app.exe 替换为实际证书编号及待签名文件。

安装 Provider

执行：

signtool csp install

该命令会：

• 将 sslTrusCSP.dll 写入 %ProgramData%\sslTrusKSP 并复制到系统目录。
• 注册 sslTrus Cryptographic Service Provider（Provider 类型为 PROV_RSA_AES）。
• 安装配套 KSP DLL，并注册 sslTrus Key Storage Provider 与 CSP 同名的 CNG Provider alias。
• 创建或保存 %ProgramData%\sslTrusKSP\config.dat；文件使用本机 Windows DPAPI 加密。

安装会修改系统级 Provider 注册，通常必须在管理员终端执行。若系统目录内的 CSP DLL 版本与内嵌版本一致，CLI 会跳过 CSP DLL 复制，但仍会执行 Provider 注册流程。

添加证书配置

执行：

signtool csp add

如需使用 NICSRS 服务地址：

signtool csp add --address nicsrs

--address 不是 URL 透传参数。当前 nicsrs 会使用 NICSRS 服务；空值、racent 或其他值使用默认服务。

添加时，CLI 会从远程服务获取证书，并写入：

%ProgramData%\sslTrusKSP\CERT_CODE.crt

同时将服务地址、凭证、证书编号和证书路径写入加密配置文件。CERT_CODE 既是远程证书标识，也是后续 Microsoft signtool.exe 中 /kc 的值。

如添加已存在的证书编号，CLI 会询问是否覆盖：输入 y 替换旧配置；直接回车或输入其他值则保持原配置不变。

查看与删除配置

查看当前配置：

signtool csp list

输出包含证书编号、服务类型、Access Key 和脱敏后的 Access Secret。请不要将命令输出、配置文件或日志上传到公开位置。

删除某个配置：

signtool csp del

根据提示输入证书编号即可。此操作只删除加密配置中的对应条目，不会删除同名 .crt 证书文件；不再使用时请手动清理该文件。

使用 Microsoft signtool.exe 签名

SHA-256 签名

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA256 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  ".\app.exe"

参数说明：

参数	说明
/csp "sslTrus Cryptographic Service Provider"	指定 CSP Provider。
/kc CERT_CODE	指定证书编号对应的密钥容器。
/f <证书路径>	指定 csp add 下载的证书文件。
/fd SHA256	指定文件摘要算法。
/tr <URL>	指定 RFC 3161 时间戳服务。
/td SHA256	指定时间戳摘要算法。

当前 CSP 支持 SHA1、SHA256、SHA384 和 SHA512 文件摘要算法；新签名通常建议使用 SHA-256 或更高版本。时间戳地址应由你的证书策略和目标平台兼容性决定。

追加 SHA-1 签名

当确有旧系统兼容性要求时，可在已有签名上追加 SHA-1：

signtool.exe sign /v ^
  /csp "sslTrus Cryptographic Service Provider" ^
  /kc CERT_CODE ^
  /f "C:\ProgramData\sslTrusKSP\CERT_CODE.crt" ^
  /fd SHA1 ^
  /tr http://timestamp.acs.microsoft.com ^
  /td SHA256 ^
  /as ^
  ".\app.exe"

/as 表示追加签名，避免覆盖已有签名。是否需要 SHA-1 应遵循目标系统和证书策略；它不应作为新项目的默认选择。

验证签名

签名后可用 Microsoft signtool.exe 验证：

signtool.exe verify /pa /v ".\app.exe"

如需验证全部签名，可按 Windows SDK signtool.exe 的版本和参数说明选择相应验证选项。

卸载 Provider

在管理员终端执行：

signtool csp uninstall

该命令会注销 CSP，以及 CSP 同名的 CNG Provider alias，并删除 CSP DLL 的 ProgramData 与系统目录副本。它不会删除 %ProgramData%\sslTrusKSP 整个目录，也不会自动移除配套 sslTrus Key Storage Provider 的注册和 DLL；若该 KSP 仅由 CSP 安装流程使用，请结合实际部署状态审慎清理。

卸载后如需移除本地敏感资料，请在确认不再被 KSP 或其他签名流程使用后，手动删除 %ProgramData%\sslTrusKSP 中的配置、证书和日志。

常见问题

现象	处理建议
cryptographic service provider is only supported on windows	在 Windows 上执行 CSP 管理命令。
安装时报权限或系统目录写入失败	使用管理员终端执行 signtool csp install。
no csp configuration	先执行 signtool csp install，再执行 signtool csp add。
no such certificate code	先用 signtool csp list 核对证书编号。
Microsoft signtool.exe 找不到 Provider	确认安装命令成功、当前工具与 Provider 都是 x64，并重新打开终端后再试。
签名时找不到证书文件	确认 /f 路径与 csp add 下载的 CERT_CODE.crt 一致。
签名调用失败	检查证书编号、服务凭证和网络连通性；再查看 %ProgramData%\sslTrusKSP\sslTrusCSP.log。
使用自定义服务地址但请求异常	CSP 固定请求服务的 /v1/codesign/sign 路径；配置的服务地址应只提供 http(s)://host[:port]。

安全说明

• Access Secret、config.dat、证书文件和 CSP 日志均应按敏感资料处理。
• config.dat 受创建配置的当前 Windows 用户 profile 的 DPAPI 保护，不应直接复制到其他用户或机器复用。
• CSP 不保存私钥；不要尝试把私钥导入 %ProgramData%\sslTrusKSP。
• CSP 签名需要访问远程服务，网络超时、服务端拒绝或时间戳服务不可用都可能导致签名失败。

更多 CLI 参数与签名命令参考，请参阅 SignTool sign 命令参考。