跳至主要内容

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 自帶的工具，不是 sslTrus 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"指定 sslTrus 安裝的 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 配置檔案和本地日誌均應按敏感資訊處理，不要寫入日誌或版本倉庫。
最後於 更新