跳至主要内容

Windows Provider

sslTrus 提供 KSP（Key Storage Provider） 和 CSP（Cryptographic Service Provider） 兩種 Windows Provider 整合方式。

透過 Windows Provider，可以讓 Microsoft SignTool、Visual Studio、MSBuild、安裝套件工具以及其他支援 Windows 密碼學介面的軟體使用 sslTrus 雲端程式碼簽署能力。

簽署私密金鑰始終保存在雲端 HSM 中，不需要將私密金鑰檔案部署到本機電腦。

KSP 和 CSP 的安裝、設定和維護均透過 sslTrus SignTool CLI 完成，可從 sslTrus 用戶端發佈頁 下載。

KSP 與 CSP​

KSP 和 CSP 分別對應 Windows 的兩代密碼學介面：

ProviderWindows 介面適用情境
KSPCNG（Cryptography API: Next Generation）現代 Windows 應用和簽署工具，優先選擇
CSPCryptoAPI傳統應用或明確要求使用 CSP 的軟體

對於新的 Windows 整合情境，通常優先使用 KSP。

只有當目標軟體不支援 KSP，或者明確要求使用傳統 CryptoAPI Provider 時，再使用 CSP。

KSP​

KSP 是基於 Windows CNG 的 Key Storage Provider。

安裝 sslTrus KSP 後，支援 CNG 的 Windows 應用可以透過標準 Windows 金鑰介面呼叫遠端程式碼簽署服務。

本機 Provider 負責接收應用程式發起的簽署請求，並將需要簽署的摘要傳送到遠端程式碼簽署服務；實際私密金鑰操作在雲端 HSM 中完成。

適用情境​

KSP 適用於：

  • Microsoft SignTool。
  • Visual Studio。
  • MSBuild。
  • 支援 Windows CNG 的建置和簽署軟體。
  • 需要透過標準 Windows Provider 接入遠端私密金鑰的應用。

安裝 KSP​

在系統管理員終端機執行：

signtool ksp install

該命令會安裝並註冊：

sslTrus Key Storage Provider

KSP 安裝涉及系統 Provider 註冊以及 Windows 系統目錄，因此通常需要管理員權限。

新增證書設定​

執行：

signtool ksp add

根據提示輸入：

Access Key
Access Secret
Certificate Code

用戶端會從遠端程式碼簽章服務取得對應憑證，並儲存遠端服務位址、存取憑證和憑證設定。

如果使用 NICSRS（www.nicsrs.com）環境，需要新增 --address nicsrs：

signtool ksp add --address nicsrs

註冊證書​

完成 KSP 設定後，需要將程式碼簽章憑證註冊到 Windows 憑證庫，並關聯 KSP Provider。

執行：

signtool ksp register

預設註冊到目前使用者的個人憑證庫。

如果需要註冊到 LocalMachine 憑證庫：

signtool ksp register --store local-machine

註冊完成後，Windows 會將對應證書識別為具有可用私密金鑰，但實際私密金鑰仍然保存在雲端 HSM。

使用 Microsoft SignTool​

KSP 設定完成後，可以使用 Windows SDK 提供的 Microsoft signtool.exe 對檔案進行簽署。

例如：

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 ^
  ".\app.exe"

主要參數：

參數說明
/csp指定 sslTrus KSP Provider
/kc指定證書編號對應的金鑰容器
/f指定程式碼簽章憑證
/fd指定檔案摘要演算法
/tr指定 RFC 3161 時間戳記伺服器
/td指定時間戳記摘要演算法

如果需要在既有簽章基礎上追加 SHA-1 簽章，可以使用 /as 參數：

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 ^
  ".\app.exe"

Microsoft signtool.exe 會透過 Windows CNG 呼叫 sslTrus KSP，再由 KSP 完成遠端私密金鑰簽署。

管理 KSP​

查看已經設定的 KSP：

signtool ksp list

刪除設定：

signtool ksp del

解除證書與 KSP 的關聯：

signtool ksp deregister

卸載 KSP：

signtool ksp uninstall

卸載 Provider 前，應確認沒有其他 Windows 應用仍依賴該 Provider。

CSP​

CSP 是傳統 Windows CryptoAPI 使用的 Cryptographic Service Provider。

它主要用於需要透過 /csp 和 /kc 參數指定 Provider 與金鑰容器的 Windows 簽章流程。sslTrus CSP 由用戶端負責安裝和維護，實際檔案簽章仍由 Windows SDK 的 Microsoft signtool.exe 完成。

適用場景​

CSP 適用於：

  • 僅支援傳統 CryptoAPI 的 Windows 軟體。
  • 明確要求指定 CSP Provider 的簽章工具。
  • 需要透過 Microsoft SignTool /csp 和 /kc 參數執行簽章的環境。
  • 無法使用 Windows CNG / KSP 的舊版應用。

對於能夠正常使用 KSP 的新系統，一般不需要額外使用 CSP。

安裝 CSP​

在管理員終端執行：

signtool csp install

安裝過程中會註冊：

sslTrus Cryptographic Service Provider

並將 Provider DLL 安裝到 Windows 系統中。

CSP Provider 類型為：

PROV_RSA_AES

本機配置預設儲存在：

%ProgramData%\sslTrusKSP

配置檔案使用 Windows DPAPI 進行保護。

如果需要同時安裝 KSP，可以執行：

signtool csp install --with-ksp

新增憑證設定​

執行：

signtool csp add

根據提示輸入：

Access Key
Access Secret
Certificate Code

添加完成後，用戶端會下載對應憑證並儲存到：

%ProgramData%\sslTrusKSP\CERT_CODE.crt

其中 CERT_CODE 同時作為遠端憑證識別碼和後續 Microsoft SignTool 使用的金鑰容器名稱。

如果使用 NICSRS（www.nicsrs.com）環境，需要新增 --address nicsrs：

signtool csp add --address nicsrs

註冊證書​

預設會將憑證註冊到目前使用者的個人憑證庫：

signtool csp register

如果需要註冊到 LocalMachine：

signtool csp register --store local-machine

支援的憑證庫包括：

參數Windows 憑證庫
current-userCurrentUser\My
local-machineLocalMachine\My

註冊完成後，Windows 憑證管理員會顯示對應憑證具有私密金鑰關聯，但私密金鑰實際仍位於雲端 HSM。

使用 Microsoft SignTool​

CSP 簽署時，需要明確指定 Provider、金鑰容器和憑證檔案：

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 CSP Provider
/kc指定證書編號對應的金鑰容器
/f指定程式碼簽章憑證
/fd指定檔案摘要演算法
/tr指定 RFC 3161 時間戳記伺服器
/td指定時間戳記摘要演算法

sslTrus CSP 支援 SHA1、SHA256、SHA384 和 SHA512 摘要演算法，新簽章情境通常應使用 SHA-256 或更高強度演算法。

驗證簽章​

簽章完成後，可以使用 Microsoft SignTool 驗證：

signtool.exe verify /pa /v ".\app.exe"

驗簽不會重新呼叫遠端私密金鑰，也不會產生新的簽章次數。

管理 CSP​

檢視現有設定：

signtool csp list

刪除某個證書設定：

signtool csp del

解除證書與 CSP 的私鑰關聯：

signtool csp deregister

卸載 Provider：

signtool csp uninstall

刪除 CSP 設定不會自動刪除已經下載的憑證檔案。如果相關憑證和設定已經不再使用，應在確認沒有其他 Provider 依賴後再進行清理。

KSP 還是 CSP​

如果沒有特殊相容性要求，可以按照下面的方式選擇：

場景建議
新的 Windows 簽章環境KSP
支援 Windows CNGKSP
Microsoft SignTool 等現代 Windows 工具KSP
軟體明確要求 CSPCSP
傳統 CryptoAPI 應用CSP
工具要求使用 /csp 和 /kcCSP

KSP 和 CSP 的主要區別在於 Windows 使用的密碼學 Provider 介面不同，遠端私鑰安全模型保持一致。

無論使用 KSP 還是 CSP，程式碼簽章私鑰都不會儲存到本機用戶端。

簽章次數​

Windows Provider 的簽章次數按照底層實際完成的遠端簽章動作計算。

例如：

SHA256 签名一次 = 1 次

如果對同一個檔案先完成 SHA256 簽章，再追加另一次簽章，則會再次觸發遠端私密金鑰操作，因此需要分別計算。

KSP 情境下，同一個檔案執行 SHA256 和 SHA1 雙重簽章通常會產生兩次底層簽章呼叫。

具體規則請參閱 參考資料。

時間戳記​

Windows Authenticode 簽章通常建議新增可信時間戳記。

現代程式碼簽章情境建議優先使用 RFC 3161 時間戳記，例如：

http://timestamp.acs.microsoft.com

實際生產環境應根據目標 Windows 版本、憑證策略、網路環境以及時間戳服務商要求選擇合適的 TSA。

具體時間戳伺服器和協定說明請參閱 參考資料。

安全說明​

使用 Windows Provider 時需要注意：

  • Access Secret 應作為敏感憑證進行保護。
  • 不要將存取憑證寫入公開指令碼或日誌。
  • Provider 設定檔不應公開傳播。
  • 本機憑證檔不包含程式碼簽署私密金鑰。
  • 程式碼簽署私密金鑰始終保存在雲端 HSM。
  • KSP/CSP 發起簽署時需要能夠存取遠端程式碼簽署服務。
  • 使用 LocalMachine 憑證庫時，應特別注意 Windows 使用者權限和憑證存取範圍。

CSP 的 config.dat 使用目前 Windows 使用者 Profile 的 DPAPI 進行保護，將憑證註冊到 LocalMachine 並不會自動改變該設定的 DPAPI 保護範圍。

最後於 更新