跳至主要内容

signtool ksp 與 Windows KSP 整合

signtool ksp 管理 Windows sslTrus Key Storage Provider（KSP）。KSP 安裝和設定完成後，Microsoft signtool.exe 可以透過 CNG Provider 呼叫遠端簽署服務，無需在本機持有私密金鑰。

注意

signtool ksp 全部子命令僅支援 Windows 平台。在非 Windows 平台執行任意 ksp 子命令會回傳： key storage provider is only supported on windows

子命令概覽​

signtool ksp [command]
子命令用途
install安裝並註冊 KSP DLL
uninstall註銷 KSP 並刪除 DLL
list列出已儲存的 KSP 金鑰設定
add新增 KSP 金鑰設定（互動式）
del刪除指定的 KSP 金鑰設定（互動式）
說明

--address 參數僅在 ksp add 時有效，用於取得憑證 PEM 並儲存遠端服務位址。

安裝 KSP​

signtool ksp install

執行後：

  1. 將內嵌的 sslTrusKSP.dll 寫入 ProgramData/sslTrusKSP/sslTrusKSP.dll。
  2. 若 ProgramData 中的 DLL 版本與 System32 中不同，則將 DLL 複製到 System32。
  3. 註冊 CNG Provider：sslTrus Key Storage Provider。
  4. 儲存 KSP 設定檔 ProgramData/sslTrusKSP/config.dat（DPAPI 加密）。
注意

install 會修改系統層級 CNG Provider 註冊，建議在系統管理員終端機執行。若偵測到 DLL 版本相同，會記錄 ksp is already installed 並直接返回。

解除安裝 KSP​

signtool ksp uninstall

執行後：

  1. 註銷 CNG Provider：sslTrus Key Storage Provider。
  2. 刪除 ProgramData/sslTrusKSP/sslTrusKSP.dll。
  3. 刪除 System32 中的 sslTrusKSP.dll。
說明

uninstall 不會刪除整個 ProgramData/sslTrusKSP 目錄。已儲存的 config.dat、憑證檔案和日誌需要手動清理。

檢視金鑰設定​

signtool ksp list

輸出欄位說明：

欄位含義
No序號
CertCode憑證編號
ServerUrl顯示為 nicsrs 或 default
AccessKeyAccess Key
AccessSecret去識別化後的 Access Secret
說明
  • 若沒有設定檔，回傳 no ksp configuration。
  • 若配置存在但密鑰列表為空，記錄 no ksp key。
  • AccessSecret 去識別化顯示，但設定檔本身仍應依敏感檔案管理。

新增密鑰設定​

signtool ksp add

指定 NICSRS 位址：

signtool ksp add --address nicsrs

指令為互動式，依序輸入：

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

執行後：

  1. 呼叫遠端 /v1/codesign/cert 取得憑證 PEM。
  2. 將憑證儲存為 ProgramData/sslTrusKSP/CERT_CODE.crt。
  3. 將金鑰設定寫入 ProgramData/sslTrusKSP/config.dat（DPAPI 加密）。

若憑證編號已存在，會提示：

The certificate code already exists, do you want to override it? [y/N]

輸入 y 覆蓋，其他值或直接 Enter 則放棄。

注意

ksp add 是互動式命令，目前不支援 --access-key、--cert-code 等非互動式參數。新增設定會存取遠端 API，並將憑證 PEM 寫入本機 ProgramData。

刪除金鑰設定​

signtool ksp del

互動輸入憑證編號：

Please enter the certificate code: CERT_CODE

执行后从 config.dat 中删除匹配的密钥配置，并重新保存加密后的配置文件。

说明

当前实现只删除配置项，不删除 ProgramData/sslTrusKSP/CERT_CODE.crt 证书文件。

通过 KSP 使用 Microsoft signtool.exe​

KSP 配置完成后，使用 Windows SDK 中的 Microsoft signtool.exe 调用 Provider。

注意

以下命令中的 signtool.exe 是 Microsoft Windows SDK 自带的工具，不是锐安信 CLI。如果当前目录或 PATH 中同时存在两者，请使用 Windows SDK 中 signtool.exe 的完整路径以避免混淆。

SHA256 签名示例：

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

追加 SHA1 簽章範例：

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

參數說明：

參數含義
/csp "sslTrus Key Storage Provider"指定銳安信安裝的 KSP Provider
/kc CERT_CODE指定 KSP 金鑰名稱，約定為證書編號
/f C:\ProgramData\sslTrusKSP\CERT_CODE.crt指定 ksp add 儲存的證書檔案
/fd SHA256 或 /fd SHA1檔案摘要演算法
/tr <url>RFC3161 時間戳記服務
/td SHA256時間戳記摘要演算法
/as附加簽名，不覆蓋既有簽名

排障參考​

錯誤訊息可能原因處理建議
key storage provider is only supported on windows在非 Windows 平台執行了 ksp 命令。只在 Windows 上執行 KSP 操作。
no ksp configuration尚未建立 KSP 設定檔。先執行 signtool ksp install 和 signtool ksp add。
no such certificate code刪除的憑證編號不存在。使用 signtool ksp list 確認憑證編號。

安全注意事項​

  • signtool ksp install 和 signtool ksp uninstall 會修改 Windows 系統目錄和 CNG Provider 註冊，通常需要系統管理員權限。
  • signtool ksp add 會存取遠端憑證介面，並將憑證檔案和加密設定寫入 ProgramData/sslTrusKSP。
  • Access Secret、KSP 設定檔和本機記錄均應視為敏感資訊處理，不要寫入記錄或版本儲存庫。
最後於 更新