跳至主要内容

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

最後於 更新