CertVerifyCertificateChainPolicy 函式 (wincrypt.h)

發行項
08/27/2023

CertVerifyCertificateChainPolicy函式會檢查憑證鏈結以確認其有效性，包括其符合任何指定的有效原則準則。

語法

BOOL CertVerifyCertificateChainPolicy(
  [in]      LPCSTR                    pszPolicyOID,
  [in]      PCCERT_CHAIN_CONTEXT      pChainContext,
  [in]      PCERT_CHAIN_POLICY_PARA   pPolicyPara,
  [in, out] PCERT_CHAIN_POLICY_STATUS pPolicyStatus
);

參數

[in] pszPolicyOID

下表列出目前預先定義的驗證鏈結原則結構。

值	意義
CERT_CHAIN_POLICY_BASE (LPCSTR) 1	實作基底鏈結原則驗證檢查。 pPolicyPara所指向結構的dwFlags成員可以設定為改變預設原則檢查行為。
CERT_CHAIN_POLICY_AUTHENTICODE (LPCSTR) 2	實作 Authenticode 鏈結原則驗證檢查。 pPolicyPara所指向之結構的pvExtraPolicyPara成員可以設定為指向AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_PARA結構。 pPolicyStatus 所指向結構的 pvExtraPolicyStatus成員可以設定為指向AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_STATUS結構。
CERT_CHAIN_POLICY_AUTHENTICODE_TS (LPCSTR) 3	實作 Authenticode 時間戳記鏈結原則驗證檢查。 pPolicyPara所指向之資料結構之 pvExtraPolicyPara成員可以設定為指向AUTHENTICODE_TS_EXTRA_CERT_CHAIN_POLICY_PARA結構。不會使用pPolicyStatus所指向之資料結構之 pvExtraPolicyStatus成員，而且必須設定為Null
CERT_CHAIN_POLICY_SSL (LPCSTR) 4	實作 SSL 用戶端/伺服器鏈結原則驗證檢查。 pPolicyPara所指向之資料結構中的pvExtraPolicyPara成員可以設定為指向使用其他原則準則初始化的SSL_EXTRA_CERT_CHAIN_POLICY_PARA結構。注意若要區分伺服器和用戶端授權憑證，呼叫 CertGetCertificateChain 函式以取得鏈結內容時，應該藉由設定預期的使用量來指定憑證類型。藉由設定在CertGetCertificateChain函式的pChainPara輸入參數中傳遞之 CERT_CHAIN_PARA結構的RequestedUsage成員，來設定預期的使用量。
CERT_CHAIN_POLICY_BASIC_CONSTRAINTS (LPCSTR) 5	實作基本條件約束鏈結原則。逐一查看鏈結中的所有憑證，檢查szOID_BASIC_CONSTRAINTS或szOID_BASIC_CONSTRAINTS2延伸模組。如果兩個延伸模組都不存在，則會假設憑證具有有效的原則。否則，針對第一個憑證專案，會檢查它是否符合pPolicyPara參數所指向之 CERT_CHAIN_POLICY_PARA結構之 dwFlags成員中指定的預期CA_FLAG或END_ENTITY_FLAG。如果兩個旗標都未設定，則第一個元素可以是 CA 或END_ENTITY。所有其他元素都必須是 CA) (憑證授權單位單位。如果延伸模組中有 PathLenConstraint，則會加以檢查。其餘簡單鏈結中的第一個元素 (，也就是用來簽署 CTL) 的憑證會檢查為END_ENTITY。如果此驗證失敗， dwError 將會設定為 TRUST_E_BASIC_CONSTRAINTS。
CERT_CHAIN_POLICY_NT_AUTH (LPCSTR) 6	實作 Windows NT 驗證鏈結原則，此原則依下列順序包含三個不同的鏈結驗證： CERT_CHAIN_POLICY_BASE— 實作基底鏈結原則驗證檢查。 dwFlags的 LOWORD 可以在pPolicyPara中設定，以改變預設原則檢查行為。如需詳細資訊，請參閱CERT_CHAIN_POLICY_BASE。 CERT_CHAIN_POLICY_BASIC_CONSTRAINTS— 實作基本條件約束鏈結原則。 dwFlags的 HIWORD 可以設定為指定第一個專案是否必須是 CA 或END_ENTITY。如需詳細資訊，請參閱CERT_CHAIN_POLICY_BASIC_CONSTRAINTS。檢查鏈結中的第二個元素，發出結束憑證的 CA 是否為 Windows NT 驗證的信任 CA。如果 CA 存在於CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE存放區位置中找到的「NTAuth」系統登錄存放區中，則會將其視為受信任。如果此驗證失敗，則 CA 不受信任，且 dwError會設定為 CERT_E_UNTRUSTEDCA。如果CERT_PROT_ROOT_DISABLE_NT_AUTH_REQUIRED_FLAG是在HKEY_LOCAL_MACHINE原則ProtectedRoots子機碼的Flags值中設定，由CERT_PROT_ROOT_FLAGS_REGPATH所定義，且上述檢查失敗，則會檢查鏈結是否CERT_TRUST_HAS_VALID_NAME_CONSTRAINTS在 dwInfoStatus中設定。如果所有命名空間都有有效的名稱條件約束，包括 UPN，則會設定此條件約束。如果鏈結沒有這項資訊狀態設定， dwError 會設定為 CERT_E_UNTRUSTEDCA。
CERT_CHAIN_POLICY_MICROSOFT_ROOT (LPCSTR) 7	檢查 Microsoft 根公開金鑰之第一個簡單鏈結的最後一個專案。如果該元素不包含 Microsoft 根公開金鑰，pPolicyStatus參數所指向之CERT_CHAIN_POLICY_STATUS結構的dwError成員會設定為CERT_E_UNTRUSTEDROOT。 pPolicyStatus參數所指向之CERT_CHAIN_POLICY_PARA結構的dwFlags成員可以包含MICROSOFT_ROOT_CERT_CHAIN_POLICY_CHECK_APPLICATION_ROOT_FLAG旗標，這會導致此函式改為檢查 Microsoft 應用程式根目錄「Microsoft Root Certificate Authority 2011」。 pPolicyPara參數所指向之CERT_CHAIN_POLICY_PARA結構的dwFlags成員可以包含MICROSOFT_ROOT_CERT_CHAIN_POLICY_ENABLE_TEST_ROOT_FLAG旗標，這會導致此函式也會檢查 Microsoft 測試根目錄。注意此原則物件識別碼 (OID) 本身不會執行任何原則驗證檢查，其用途是與其他原則搭配使用。
CERT_CHAIN_POLICY_EV (LPCSTR) 8	指定執行憑證的延伸驗證。 Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP：不支援此值。
CERT_CHAIN_POLICY_SSL_F12 (LPCSTR) 9	檢查鏈結中的任何憑證是否有弱式密碼編譯，或協力廠商根憑證合規性，並提供錯誤字串。 pPolicyStatus參數所指向之CERT_CHAIN_POLICY_STATUS結構的pvExtraPolicyStatus成員必須指向SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS，這會隨著弱式密碼編譯和根程式合規性檢查的結果更新。呼叫之前，pPolicyStatus參數所指向之CERT_CHAIN_POLICY_STATUS結構的cbSize成員必須設定為大於或等於 sizeof (SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS) 的值。 pPolicyStatus參數所指向之CERT_CHAIN_POLICY_STATUS結構中的dwError成員將會設定為TRUST_E_CERT_SIGNATURE，以取得潛在的弱式密碼編譯，並將設定為不符合 Microsoft 根計畫的協力廠商根目錄CERT_E_UNTRUSTEDROOT。 Windows 10版本 1607、Windows Server 2016、Windows 10、版本 1511 與 KB3172985、Windows 10 RTM 搭配 KB3163912、Windows 8.1和 Windows Server 2012 R2 搭配 KB3163912，以及具有 SP1 和 Windows Server 2008 R2 SP1 的 Windows 7 與 KB3161029

[in] pChainContext

包含要驗證之鏈結之 CERT_CHAIN_CONTEXT 結構的指標。

[in] pPolicyPara

提供鏈結原則驗證準則之CERT_CHAIN_POLICY_PARA 結構的指標。該結構的 dwFlags 成員可以設定為變更預設原則檢查行為。

此外，您也可以在結構的 pvExtraPolicyPara 成員中傳遞原則特定參數。

[in, out] pPolicyStatus

傳回鏈結狀態資訊的 CERT_CHAIN_POLICY_STATUS 結構的指標。此結構的 pvExtraPolicyStatus 成員中可以傳回 OID 特定的額外狀態。

傳回值

傳回值表示函式是否能夠檢查原則，它不會指出原則檢查是否失敗或通過。

如果可以驗證指定原則的鏈結，則會傳回TRUE，並更新pPolicyStatus的dwError成員。 dwError 0 (ERROR_SUCCESS 或S_OK) 表示鏈結符合指定的原則。

如果鏈結無法驗證，傳回值為 TRUE ，而且您必須驗證 pPolicyStatus 參數以取得實際錯誤。

FALSE值表示函式無法檢查原則。

備註

pPolicyStatus所指向之CERT_CHAIN_POLICY_STATUS結構的dwError成員可以套用至單一鏈結專案、簡單鏈結或整個鏈結內容。如果dwError適用于整個鏈結內容，CERT_CHAIN_POLICY_STATUS結構的lChainIndex和lElementIndex成員都會設定為 –1。如果 dwError 套用至完整的簡單鏈結， lElementIndex 會設定為 –1， 而 lChainIndex 會設定為發生錯誤的第一個鏈結的索引。如果 dwError 套用至單一憑證專案， lChainIndex 和 lElementIndex 會編制錯誤的第一個憑證索引。

若要取得憑證專案，請使用下列語法：

pChainContext->rgpChain[lChainIndex]->rgpElement[lElementIndex];

使用 CertGetCertificateChain 函式來啟用和執行憑證撤銷檢查。 CertVerifyCertificateChainPolicy函式不會檢查憑證鏈結中的憑證是否已撤銷。

規格需求


最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	wincrypt.h
程式庫	Crypt32.lib
Dll	Crypt32.dll