CertVerifyCertificateChainPolicy function (wincrypt.h)
The CertVerifyCertificateChainPolicy function checks a certificate chain to verify its validity, including its compliance with any specified validity policy criteria.
Syntax
BOOL CertVerifyCertificateChainPolicy(
[in] LPCSTR pszPolicyOID,
[in] PCCERT_CHAIN_CONTEXT pChainContext,
[in] PCERT_CHAIN_POLICY_PARA pPolicyPara,
[in, out] PCERT_CHAIN_POLICY_STATUS pPolicyStatus
);
Parameters
[in] pszPolicyOID
Current predefined verify chain policy structures are listed in the following table.
| Value | Meaning |
|---|---|
| CERT_CHAIN_POLICY_BASE (LPCSTR) 1 |
Implements the base chain policy verification checks. The dwFlags member of the structure pointed to by pPolicyPara can be set to alter the default policy checking behavior. |
| CERT_CHAIN_POLICY_AUTHENTICODE (LPCSTR) 2 |
Implements the Authenticode chain policy verification checks. The pvExtraPolicyPara member of the structure pointed to by pPolicyPara can be set to point to an AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_PARA structure. The pvExtraPolicyStatus member of the structure pointed to by pPolicyStatus can be set to point to an AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_STATUS structure. |
| CERT_CHAIN_POLICY_AUTHENTICODE_TS (LPCSTR) 3 |
Implements Authenticode Time Stamp chain policy verification checks. The pvExtraPolicyPara member of the data structure pointed to by pPolicyPara can be set to point to an AUTHENTICODE_TS_EXTRA_CERT_CHAIN_POLICY_PARA structure. The pvExtraPolicyStatus member of the data structure pointed to by pPolicyStatus is not used and must be set to NULL. |
| CERT_CHAIN_POLICY_SSL (LPCSTR) 4 |
Implements the SSL client/server chain policy verification checks. The pvExtraPolicyPara member in the data structure pointed to by pPolicyPara can be set to point to an SSL_EXTRA_CERT_CHAIN_POLICY_PARA structure initialized with additional policy criteria. Note: To differentiate between server and client authorization certificates, the call to the CertGetCertificateChain function to get the chain context should specify the certificate type by setting the expected usage. Set the expected usage by setting the RequestedUsage member of the CERT_CHAIN_PARA structure passed in the pChainPara input parameter of the CertGetCertificateChain function. |
| CERT_CHAIN_POLICY_BASIC_CONSTRAINTS (LPCSTR) 5 |
Implements the basic constraints chain policy. Iterates through all the certificates in the chain checking for either a szOID_BASIC_CONSTRAINTS or a szOID_BASIC_CONSTRAINTS2 extension. If neither extension is present, the certificate is assumed to have valid policy. Otherwise, for the first certificate element, checks if it matches the expected CA_FLAG or END_ENTITY_FLAG specified in the dwFlags member of the CERT_CHAIN_POLICY_PARA structure pointed to by the pPolicyPara parameter. If neither or both flags are set, then, the first element can be either a CA or END_ENTITY. All other elements must be a certification authority (CA). If the PathLenConstraint is present in the extension, it is checked. The first elements in the remaining simple chains (that is, the certificates used to sign the CTL) are checked to be an END_ENTITY. If this verification fails, dwError will be set to TRUST_E_BASIC_CONSTRAINTS. |
| CERT_CHAIN_POLICY_NT_AUTH (LPCSTR) 6 |
Implements the Windows NT Authentication chain policy, which consists of three distinct chain verifications in the following order: - CERT_CHAIN_POLICY_BASE: Implements the base chain policy verification checks. The LOWORD of dwFlags can be set in pPolicyPara to alter the default policy checking behavior. For more information, see CERT_CHAIN_POLICY_BASE. - CERT_CHAIN_POLICY_BASIC_CONSTRAINTS: Implements the basic constraints chain policy. The HIWORD of dwFlags can be set to specify if the first element must be either a CA or END_ENTITY. For more information, see CERT_CHAIN_POLICY_BASIC_CONSTRAINTS. - Checks if the second element in the chain, the CA that issued the end certificate, is a trusted CA for Windows NT Authentication. A CA is considered to be trusted if it exists in the "NTAuth" system registry store found in the CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE store location. If this verification fails, the CA is untrusted, and dwError is set to CERT_E_UNTRUSTEDCA. If CERT_PROT_ROOT_DISABLE_NT_AUTH_REQUIRED_FLAG is set in the Flags value of the HKEY_LOCAL_MACHINE policy ProtectedRoots subkey, defined by CERT_PROT_ROOT_FLAGS_REGPATH and the above check fails, the chain is checked for CERT_TRUST_HAS_VALID_NAME_CONSTRAINTS set in dwInfoStatus. This is set if there was a valid name constraint for all namespaces including UPN. If the chain does not have this info status set, dwError is set to CERT_E_UNTRUSTEDCA. |
| CERT_CHAIN_POLICY_MICROSOFT_ROOT (LPCSTR) 7 |
Checks the last element of the first simple chain for a Microsoft root public key. If that element does not contain a Microsoft root public key, the dwError member of the CERT_CHAIN_POLICY_STATUS structure pointed to by the pPolicyStatus parameter is set to CERT_E_UNTRUSTEDROOT. The dwFlags member of the CERT_CHAIN_POLICY_PARA structure pointed to by the pPolicyStatus parameter can contain the MICROSOFT_ROOT_CERT_CHAIN_POLICY_CHECK_APPLICATION_ROOT_FLAG flag, which causes this function to instead check for the Microsoft application root "Microsoft Root Certificate Authority 2011". The dwFlags member of the CERT_CHAIN_POLICY_PARA structure pointed to by the pPolicyPara parameter can contain the MICROSOFT_ROOT_CERT_CHAIN_POLICY_ENABLE_TEST_ROOT_FLAG flag, which causes this function to also check for the Microsoft test roots. Note: This policy object identifier (OID) does not perform any policy verification checks by itself, it is meant to be used in conjunction with other policies. |
| CERT_CHAIN_POLICY_EV (LPCSTR) 8 |
Specifies that extended validation of certificates is performed. Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This value is not supported. |
| CERT_CHAIN_POLICY_SSL_F12 (LPCSTR) 9 |
Checks if any certificates in the chain have weak crypto or if third party root certificate compliance and provide an error string. The pvExtraPolicyStatus member of the CERT_CHAIN_POLICY_STATUS structure pointed to by the pPolicyStatus parameter must point to SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS, which is updated with the results of the weak crypto and root program compliance checks. Before calling, the cbSize member of the CERT_CHAIN_POLICY_STATUS structure pointed to by the pPolicyStatus parameter must be set to a value greater than or equal to sizeof(SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS). The dwError member in CERT_CHAIN_POLICY_STATUS structure pointed to by the pPolicyStatus parameter will be set to TRUST_E_CERT_SIGNATURE for potential weak crypto and set to CERT_E_UNTRUSTEDROOT for Third Party Roots not in compliance with the Microsoft Root Program. Windows 10, version 1607, Windows Server 2016, Windows 10, version 1511 with KB3172985, Windows 10 RTM with KB3163912, Windows 8.1 and Windows Server 2012 R2 with KB3163912, and Windows 7 with SP1 and Windows Server 2008 R2 SP1 with KB3161029 |
[in] pChainContext
A pointer to a CERT_CHAIN_CONTEXT structure that contains a chain to be verified.
[in] pPolicyPara
A pointer to a CERT_CHAIN_POLICY_PARA structure that provides the policy verification criteria for the chain. The dwFlags member of that structure can be set to change the default policy checking behavior.
In addition, policy-specific parameters can also be passed in the pvExtraPolicyPara member of the structure.
[in, out] pPolicyStatus
A pointer to a CERT_CHAIN_POLICY_STATUS structure where status information on the chain is returned. OID-specific extra status can be returned in the pvExtraPolicyStatus member of this structure.
Return value
The return value indicates whether the function was able to check for the policy, it does not indicate whether the policy check failed or passed.
If the chain can be verified for the specified policy, TRUE is returned and the dwError member of the pPolicyStatus is updated. A dwError of 0 (ERROR_SUCCESS or S_OK) indicates the chain satisfies the specified policy.
If the chain cannot be validated, the return value is TRUE and you need to verify the pPolicyStatus parameter for the actual error.
A value of FALSE indicates that the function wasn't able to check for the policy.
Remarks
A dwError member of the CERT_CHAIN_POLICY_STATUS structure pointed to by pPolicyStatus can apply to a single chain element, to a simple chain, or to an entire chain context. If dwError applies to the entire chain context, both the lChainIndex and the lElementIndex members of the CERT_CHAIN_POLICY_STATUS structure are set to –1. If dwError applies to a complete simple chain, lElementIndex is set to –1 and lChainIndex is set to the index of the first chain that has an error. If dwError applies to a single certificate element, lChainIndex and lElementIndex index the first certificate that has the error.
To get the certificate element use this syntax:
pChainContext->rgpChain[lChainIndex]->rgpElement[lElementIndex];
Use the CertGetCertificateChain function to enable and perform certificate revocation checking. The CertVerifyCertificateChainPolicy function does not check if certificates in the certificate chain are revoked.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | wincrypt.h |
| Library | Crypt32.lib |
| DLL | Crypt32.dll |
See also
AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_PARA
AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_STATUS