跳至主要内容

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 設定檔和本機日誌均應按敏感資訊處理，不要寫入日誌或版本儲存庫。
最後於 更新