跳至主要内容

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 替換舊設定；直接按 Enter 或輸入其他值則保持原設定不變。

檢視與刪除設定​

檢視目前設定：

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 命令參考。

最後於 更新