The CertVerifyRevocation function verifies that a list of certificates (contained in the rgpvContext[] array) have not been revoked. Once a certificate in the list has been found to be revoked, no further checking is done. This list may be a chain of certificates propagating upwards from an end entity to the root CA. However, it is not required or assumed that the list is a chain of related certificates.
#include <wincrypt.h>
BOOL WINAPI CertVerifyRevocation(
DWORD dwCertEncodingType, // in
DWORD dwRevType, // in
DWORD cContext, // in
PVOID rgpvContext[], // in
DWORD dwFlags, // in
PCERT_REVOCATION_PARA pRevPara, // in/optional
PCERT_REVOCATION_STATUS pRevStatus // in/out
);
| Encoding type | Value |
|---|---|
| X509_ASN_ENCODING | 0x00000001 |
| Revocation type | Value |
|---|---|
| CERT_CONTEXT_REVOCATION_TYPE | 0x00000001 |
For efficiency, the more contexts that are passed in at one time, the better.
If FALSE is returned from CertVerifyRevocation, this structure's members will contain error status. See CERT_REVOCATION_STATUS for additional detail. See the "Remarks" section below for an example describing how pRevStatus is updated when a revocation verification problem is encountered.
CertVerifyRevocation returns TRUE if all of the contexts were successfully checked and none were revoked. Otherwise, it returns FALSE and updates the returned pRevStatus data structure 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 pRevStatus will be set by the handler to specify which error was encountered. CertVerifyRevocation will then set LastError equal to the error specified in dwError. For more information, see Handler Return Value Requirements.
For a return value of FALSE, pRevStatus -> dwError should be examined or GetLastError should be called to determine the exact reason for failure.
| Error code | Description |
|---|---|
| CRYPT_E_NO_REVOCATION_CHECK | An installed or registered revocation function wasn't able to do a revocation check on the context. |
| CRYPT_E_NO_REVOCATION_DLL | No installed or registered Dll was found that was able to verify revocation. |
| CRYPT_E_NOT_IN_REVOCATION_DATABASE | The context to be checked was not found in the revocation server's database. |
| CRYPT_E_REVOCATION_OFFLINE | It was not possible to connect to the revocation server. |
| CRYPT_E_REVOKED | The context was revoked. dwReason in pRevStatus contains the reason for revocation. |
| ERROR_SUCCESS | The context was good. |
| E_INVALIDARG | cbSize in pRevStatus is less than sizeof(CERT_REVOCATION_STATUS). Note that dwError in pRevStatus is not updated for this error. |
The following example shows how pRevStatus is updated when a revocation verification problem is encountered:
Consider the case where cContext = 4. If CertVerifyRevocation was able to verify that rgpvContext[0] and rgpvContext[1] were not revoked, but it was not able to check rgpvContext[2], then the pRevStatus member dwIndex is set equal to 2, indicating that the context at index two had the problem, pRevStatus member dwError is set equal to CRYPT_E_NO_REVOCATION_CHECK, and FALSE is returned. If rgpvContext[2] was determined to be revoked, then pRevStatus member dwIndex is set equal to 2, pRevStatus member dwError is set equal to CRYPT_E_REVOKED, dwReason would be updated, and FALSE is returned. In either case, both rgpvContext[0] and rgpvContext[1] were verified not to be revoked, rgpvContext[2] was the last array index checked, and rgpvContext[3] wasn't checked at all.
For information about extending the CertVerifyRevocation functionality by using installable revocation handlers, see Extending CertVerifyRevocation Functionality.
// EXAMPLE CODE FOR USING CertVerifyRevocation().
// This function verifies that a list of certificates
// have not been revoked.
// Assume that the application has a pointer to both
// the PCERT_REVOCATION_PARA (pRevPara) and
// PCERT_REVOCATION_STATUS (pRevStatus).
// Set up the variables.
DWORD dwCertEncodingType = X509_ASN_ENCODING;
// Type of encoding
DWORD dwRevType = CERT_CONTEXT_REVOCATION_TYPE;
// Type of context data
DWORD cContext =128; // # of elements in rgpvContext
PVOID rgpvContext[128];// Array of pointers to CERT_CONTEXT
// elements. These elements must contain
// information to find the revocation server.
DWORD dwFlags = NULL; // flag values
PCERT_REVOCATION_PARA pRevPara;
// Initialized elsewhere
PCERT_REVOCATION_STATUS pRevStatus;
// Initialized elsewhere
BOOL fResult; // Return TRUE if all contexts are OK
// FALSE if any context revoked
pRevStatus->cbSize= sizeof(CERT_REVOCATION_STATUS);
// cbSize member of CERT_REVOCATION_STATUS
// needs to be set
fResult= CertVerifyRevocation(
dwCertEncodingType, // in - X509_ASN_ENCODING
dwRevType, // in - CERT_CONTEXT-REVOCATION-TYPE
cContext, // in - # of elements in the rgpvContext
// array
rgpvContext, // in - array of pointers
dwFlags, // in - Flag Values
pRevPara, // in/optional
pRevStatus); // in/out
fResult= FALSE;
if (!fResult) { // FALSE
cout<< "Certificate revoked"<< endl
<< "revokation status = "<< pRevStatus->dwError<< endl;
}
else { // TRUE
cout<< "No certificates revoked"<< endl;
}
Windows NT: Requires version 4.0 SP3 or later. Available also in IE 3.02 and later.
Windows: Requires Windows 98 (or Windows 95 with IE 3.02 or later).
Windows CE: Unsupported.
Header: Declared in wincrypt.h.
Import Library: Use crypt32.lib.
CertVerifyCRLTimeValidity, CertVerifyTimeValidity, CertVerifyValidityNesting