WinVerifyTrust 函式 (wintrust.h)

  • 發行項

WinVerifyTrust 函式會在指定的物件上執行信任驗證動作。 函式會將查詢傳遞給支援動作標識碼 的信任提供者 ，如果有的話。

針對憑證驗證，請使用 CertGetCertificateChain 和 CertVerifyCertificateChainPolicy 函式。

語法

LONG WinVerifyTrust(
  [in] HWND   hwnd,
  [in] GUID   *pgActionID,
  [in] LPVOID pWVTData
);

參數

[in] hwnd

呼叫端視窗的選擇性句柄。 信任提供者可以使用此值來判斷它是否可以與用戶互動。 不過，信任提供者通常會在沒有使用者輸入的情況下執行驗證動作。

此參數可以是下列其中一個值。

值 意義
INVALID_HANDLE_VALUE
 沒有互動式使用者。 信任提供者會執行驗證動作，而不需要用戶的協助。
Zero
 信任提供者可以使用互動式桌面來顯示其使用者介面。
有效的視窗句柄
 信任提供者可以將INVALID_HANDLE_VALUE或零以外的任何值視為可用來與用戶互動的有效視窗句柄。

[in] pgActionID

GUID 結構的指標，可識別動作和支援該動作的信任提供者。 這個值表示要對 pWinTrustData 所指向結構執行的驗證動作類型。

WinTrust 服務的設計目的是要與第三方實作的信任提供者搭配使用。 每個信任提供者都會提供自己的唯一動作標識碼集。 如需信任提供者所支援之動作標識符的相關信息，請參閱該信任提供者的檔。

例如，Microsoft 提供軟體發行者信任提供者，可建立從因特網或其他公用網路下載之軟體的信任度。 軟體發行者信任提供者支援下列動作標識碼。 這些常數定義於Softpub.h中。

值 意義
DRIVER_ACTION_VERIFY
 確認 Windows 硬體質量實驗室 (WHQL) 簽署驅動程式的真實性。 這是 Authenticode 附加元件原則提供者。
HTTPSPROV_ACTION
 透過 Internet Explorer 驗證 SSL/TLS 連線。
OFFICESIGN_ACTION_VERIFY
 不支援此動作識別碼。 使用 Microsoft Office Authenticode 附加元件原則提供者來驗證結構化記憶體檔案的真實性。

Windows Server 2003 和 Windows XP： 支援此動作識別碼。
WINTRUST_ACTION_GENERIC_CHAIN_VERIFY
 確認從任何物件類型建立的憑證鏈結。 系統會提供回呼，以針對每個簽署者和計數器簽署者使用鏈結內容來實作最終鏈結原則。
WINTRUST_ACTION_GENERIC_VERIFY_V2
 使用 Authenticode 原則提供者驗證檔案或物件。
WINTRUST_ACTION_TRUSTPROVIDER_TEST
 呼叫 Authenticode 原則提供者之後，將 CRYPT_PROVIDER_DATA 結構寫入檔案。

[in] pWVTData

當轉換成 WINTRUST_DATA 結構時，指標包含 信任提供者 需要處理指定動作標識子的資訊。 一般而言，結構包含可識別信任提供者必須評估之物件的資訊。

結構的格式取決於動作識別碼。 如需特定動作識別碼所需資料的資訊，請參閱支援該動作的信任提供者檔。

傳回值

如果信任提供者確認主體是針對指定的動作信任的，則傳回值為零。 除了零以外，沒有其他值應該視為成功傳回。

如果信任提供者未驗證主體是否信任指定的動作，函式會從 信任提供者傳回狀態代碼。

注意 傳回值是 LONG，而不是先前記載的 HRESULT 。 請勿使用 HRESULT 宏，例如 SUCCEEDED 來判斷函式是否成功。 相反地，請檢查傳回值是否等於零。

 

例如，信任提供者可能表示主體不受信任，或受到信任，但有限制或警告。 傳回值可以是個別信任提供者的檔中所述的信任提供者特定值，或者可以是下列其中一個錯誤碼。

傳回碼 Description
TRUST_E_SUBJECT_NOT_TRUSTED
 主體失敗了指定的驗證動作。 大部分的信任提供者會傳回更詳細的錯誤碼，以描述失敗的原因。
注意  

根據 HKLM\Software\Microsoft\Cryptography\Wintrust\Config 下的 EnableCertPaddingCheck 登錄機碼值，可能會傳回TRUST_E_SUBJECT_NOT_TRUSTED傳回碼。如果 EnableCertPaddingCheck 設定為 “1”，則會執行額外的檢查，以確認WIN_CERTIFICATE結構不包含多餘的資訊。 檢查會驗證 PKCS #7 結構以外沒有非零的數據。 如需詳細資訊，請參閱下列安全性諮詢： http://technet.microsoft.com/security/advisory/2915720#section1。

 
TRUST_E_PROVIDER_UNKNOWN
 此系統上無法辨識信任提供者。
TRUST_E_ACTION_UNKNOWN
 信任提供者不支援指定的動作。
TRUST_E_SUBJECT_FORM_UNKNOWN
 信任提供者不支援為主體指定的表單。

備註

WinVerifyTrust 函式可讓應用程式叫用信任提供者，以確認指定的物件是否符合指定驗證作業的準則。 pgActionID 參數會識別驗證作業，而 pWinTrustData 參數會識別要驗證其信任的物件。 信任提供者是向操作系統註冊的 DLL。 呼叫 WinVerifyTrust 會轉送呼叫已註冊的信任提供者，如果有支援該指定動作標識碼的呼叫。

例如，軟體發行者信任提供者可以驗證可執行檔是否來自受信任的軟體發行者，而且檔案在發佈后尚未修改。 在此情況下， pWinTrustData 參數會指定檔名和文件類型，例如 Microsoft 可攜式可執行檔 映像檔。

每個信任提供者都支援一組可評估的特定動作。 每個動作都有可識別它的 GUID。 信任提供者可以支援任意數目的動作標識碼，但兩個信任提供者不支援相同的動作標識碼。

如需示範如何使用此函式來驗證可攜式可執行檔的簽章 (PE) 檔案的範例，請參閱 範例 C 程式：驗證 PE 檔案的簽章。

規格需求

需求 值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平台 Windows
標頭 wintrust.h (包含 Softpub.h)
程式庫 Wintrust.lib
Dll Wintrust.dll