CertVerifyCertificateChainPolicy (Compact 2013)

  • Article

3/28/2014

This function checks a certificate chain to verify its validity, including its compliance with any specified validity policy criteria.

Syntax

BOOL WINAPI CertVerifyCertificateChainPolicy(
    __in LPCSTR pszPolicyOID,
    __in PCCERT_CHAIN_CONTEXT pChainContext,
    __in PCERT_CHAIN_POLICY_PARA pPolicyPara,
    __inout PCERT_CHAIN_POLICY_STATUS pPolicyStatus
    );

Parameters

  • pszPolicyOID
    [in] Current predefined verify chain policy structures are listed in the following table.

    Value

    Description

    CERT_CHAIN_POLICY_BASE

    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

    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

    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

    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.

    CERT_CHAIN_POLICY_BASIC_CONSTRAINTS

    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 to determine whether it matches the expected CA_FLAG or END_ENTITY_FLAG specified in pPolicyPara->dwFlags. If neither or both flags are set, then the first element can be either a certificate authority or END_ENTITY. All other elements must be a certificate authority. 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 certificate trust list (CTL)) are checked to determine whether they are an END_ENTITY. If this verification fails, dwError will be set to TRUST_E_BASIC_CONSTRAINTS.

    CERT_CHAIN_POLICY_NT_AUTH

    Implements the Windows NT Authentication chain policy, which consists of three distinct chain verifications in the following order:

    1. 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.
    2. CERT_CHAIN_POLICY_BASIC_CONSTRAINTS - Implements the basic constraints chain policy. The HIWORD of dwFlags can be set to specify whether the first element must be either a certificate authority or END_ENTITY.
    3. Checks to determine whether the second element in the chain, the certificate authority that issued the end certificate, is a trusted certificate authority for Windows NT Authentication. A certificate authority 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 certificate authority 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 HKLM policy "ProtectedRoots" subkey, defined by CERT_PROT_ROOT_FLAGS_REGPATH and this check fails, the chain is checked to determine whether is CERT_TRUST_HAS_VALID_NAME_CONSTRAINTS set in dwInfoStatus. This is set if there was a valid name constraint for all namespaces, including user principal name (UPN). If the chain does not have this information status set, dwError is set to CERT_E_UNTRUSTEDCA.

    CERT_CHAIN_POLICY_MICROSOFT_ROOT

    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 to which the pPolicyStatus parameter points is set to CERT_E_UNTRUSTEDROOT.

    The dwFlags member of the CERT_CHAIN_POLICY_PARA structure to which the pPolicyStatus parameter points 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.
  • pChainContext
    [in] Pointer to a CERT_CHAIN_CONTEXT structure that contains a chain to be verified.

  • pPolicyPara
    [in] 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.

  • pPolicyStatus
    [in, out] Pointer to a CERT_CHAIN_POLICY_STATUS structure where status information on the chain is returned. Object identifier (OID)-specific extra status can be returned in the pvExtraPolicyStatus member of this structure.

Return Value

Returns true and the dwError member of the pPolicyStatus is updated if the chain can be verified for the specified policy. A dwError of 0 (ERROR_SUCCESS or S_OK) indicates the chain satisfies the specified policy.

Returns false if the chain cannot be validated.

Remarks

A dwError member of the CERT_CHAIN_POLICY_STATUS structure that pPolicyStatus points to 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. That certificate element is: pChainContext->rgpChain[lChainIndex]->rgpElement[lElementIndex].

Requirements

Header

wincrypt.h

Library

crypt32.lib

See Also

Reference

Certificates Functions