CertVerifyRevocation function (wincrypt.h)

The CertVerifyRevocation function checks the revocation status of the certificates contained in the rgpvContext array. If a certificate in the list is found to be revoked, no further checking is done. This array can be a chain of certificates propagating upward from an end entity to the root authority, but this nature of the list of certificates is not required or assumed.

Syntax

BOOL CertVerifyRevocation(
  [in]           DWORD                   dwEncodingType,
  [in]           DWORD                   dwRevType,
  [in]           DWORD                   cContext,
  [in]           PVOID []                rgpvContext,
  [in]           DWORD                   dwFlags,
  [in, optional] PCERT_REVOCATION_PARA   pRevPara,
  [in, out]      PCERT_REVOCATION_STATUS pRevStatus
);

Parameters

[in] dwEncodingType

Specifies the encoding type used. Currently, only X509_ASN_ENCODING and PKCS_7_ASN_ENCODING are being used; however, additional encoding types may be added in the future. For either current encoding type, use X509_ASN_ENCODING | PKCS_7_ASN_ENCODING.

[in] dwRevType

Indicates the type of the context structure passed in rgpvContext. Currently only CERT_CONTEXT_REVOCATION_TYPE, the revocation of certificates, is defined.

[in] cContext

Count of elements in the rgpvContext array.

[in] rgpvContext

When the dwRevType is CERT_CONTEXT_REVOCATION_TYPE, rgpvContext is an array of pointers to CERT_CONTEXT structures. These contexts must contain sufficient information to allow the installable or registered revocation DLLs to find the revocation server. This information would normally be conveyed in an extension such as the CRLDistributionsPoints extension defined by the Internet Engineering Task Force (IETF) in PKIX Part 1.

For efficiency, the more contexts that are passed in at one time, the better.

[in] dwFlags

Indicates any special processing needs. This parameter can be one of the following flags.

[in, optional] pRevPara

Optionally set to assist in finding the issuer. For details, see the CERT_REVOCATION_PARA structure.

[in, out] pRevStatus

Only the cbSize member of the CERT_REVOCATION_STATUS pointed to by pRevStatus needs to be set before CertVerifyRevocation is called.

If the function returns FALSE, this structure's members will contain error status information. For more information, see CERT_REVOCATION_STATUS. For a description of how pRevStatus is updated when a revocation verification problem is encountered, see Remarks.

Return value

If the function successfully checks all of the contexts and none were revoked, the function returns TRUE. If the function fails, it returns FALSE and updates the CERT_REVOCATION_STATUS structure pointed to by pRevStatus as described in CERT_REVOCATION_STATUS.

When the revocation handler for any of the contexts returns FALSE due to an error, the dwError member in the structure pointed to by pRevStatus will be set by the handler to specify which error was encountered. GetLastError returns an error code equal to the error specified in the dwError member of the CERT_REVOCATION_STATUS structure. GetLastError can be one of the following values.

Remarks

The following example shows how pRevStatus is updated when a revocation verification problem is encountered:

Consider the case where cContext is four:

If CertVerifyRevocation can verify that rgpvContext[0] and rgpvContext[1] are not revoked, but cannot check rgpvContext[2], the pRevStatus member dwIndex is set to two, indicating that the context at index two has the problem, the dwError member of pRevStatus is set to CRYPT_E_NO_REVOCATION_CHECK, and FALSE is returned.

If rgpvContext[2] is found to be revoked, the dwIndex member of pRevStatus is set to two, and the dwError member of pRevStatus is set to CRYPT_E_REVOKED, dwReason is updated, and FALSE is returned.

In either case, both rgpvContext[0] and rgpvContext[1] are verified not to be revoked, rgpvContext[2] is the last array index checked, and rgpvContext[3] has not been checked at all.

Requirements

See also

CERT_CONTEXT

CERT_REVOCATION_PARA

CERT_REVOCATION_STATUS

CertVerifyCRLTimeValidity

CertVerifyTimeValidity

CertVerifyValidityNesting

Data Management Functions