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 的兩代密碼學介面：

Provider	Windows 介面	適用場景
KSP	CNG（Cryptography API: Next Generation）	現代 Windows 應用程式與簽章工具，優先選擇
CSP	CryptoAPI	傳統應用程式或明確要求使用 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-user	CurrentUser\My
local-machine	LocalMachine\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	指定時間戳摘要演算法

目前遠端簽章介面支援 SHA1 與 SHA256 摘要演算法。新的簽章場景應優先使用 SHA256；僅在相容舊系統時使用 SHA1。

驗證簽章

簽章完成後，可以使用 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 CNG	KSP
Microsoft SignTool 等現代 Windows 工具	KSP
軟體明確要求 CSP	CSP
傳統 CryptoAPI 應用	CSP
工具要求使用 /csp 和 /kc	CSP

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 保護範圍。