CertVerifySubjectCertificateContext

The CertVerifySubjectCertificateContext function performs the enabled verification checks on the subject certificate by using the issuer.

#include <wincrypt.h>
BOOL WINAPI CertVerifySubjectCertificateContext(
  PCCERT_CONTEXT pSubject,  // in
  PCCERT_CONTEXT pIssuer,   // in, optional
  DWORD *pdwFlags           // in/out
);

Parameters

pSubject

Pointer to the subject context.

pIssuer

Pointer to an issuer context. When checking just the CERT_STORE_TIME_VALIDITY_FLAG, pIssuer may be NULL.

pdwFlags

The following flags can be set in *pdwFlags to enable verification checks on the subject certificate:

CERT_STORE_REVOCATION_FLAG (0x00000004): Checks whether the subject certificate is on the issuer's revocation list.
CERT_STORE_SIGNATURE_FLAG (0x00000001): Uses the public key in the issuer's certificate to verify the signature on the subject certificate.
CERT_STORE_TIME_VALIDITY_FLAG (0x00000002): Gets the current time and verifies that it is within the subject certificate's validity period.

If an enabled verification check succeeds, its flag is set to zero. If it fails, then its flag is set upon return.

If CERT_STORE_REVOCATION_FLAG was enabled and the issuer doesn't have a CRL in the store, then CERT_STORE_NO_CRL_FLAG is set in addition to the CERT_STORE_REVOCATION_FLAG.

Return Values

For a verification check failure, TRUE is still returned. FALSE is returned only when a bad parameter is passed in.

Call GetLastError to see the reason for any failures. This function has the following error code:

Error code	Description
E_INVALIDARG	Unsupported bit was set in *pdwFlags. Any combination of: CERT_STORE_SIGNATURE_FLAG, CERT_STORE_TIME_VALIDITY_FLAG, or CERT_STORE_REVOCATION_FLAG maybe set. If pIssuer argument is NULL, only CERT_STORE_TIME_VALIDITY_FLAG may be set.

Remarks

The hexadecimal value of the flags may be combined together with a bitwise OR operation in order to enable multiple verifications. For example, to enable both signature and time validity, the value CERT_STORE_SIGNATURE_FLAG | CERT_STORE_TIME_VALIDITY_FLAG ( which is equal to 0x00000003) would be placed in the double word *pdwFlags as an "in" parameter. If CERT_STORE_SIGNATURE_FLAG verification succeeded, but CERT_STORE_TIME_VALIDITY_FLAG verification failed, *pdwFlags would be set to the value of CERT_STORE_TIME_VALIDITY_FLAG (which is equal to 0x00000002), as an "out" parameter, when the function returns.

Example

// CertVerifySubjectCertificateContext 
// Check a certificate for all verification checks.
// handle_error() is a function defined in a separate file.
HCERTSTORE hSubjectStoreHandle;  // The store that is the source of
// the subject certificate.
HCERTSTORE hIssuerStoreHandle;   // The store that is the source of 
                                 // the issuer certificate.
PCCERT_CONTEXT pSubjectCert;
PCCERT_CONTEXT pIssuerCert;
DWORD dwFlags=0;
//
// Set dwFlags to check for three validity conditions.
dwFlags = CERT_STORE_REVOCATION_FLAG|
CERT_STORE_SIGNATURE_FLAG|
CERT_STORE_TIME_VALIDITY_FLAG;
//
// Open a store and get a subject cert.
if(hSubjectStoreHandle = CertOpenSystemStore(0,"MY"))
printf("The MY store is open. Continue.\n");
else
handle_error("The MY store did not open.");
//
// Open a second store and get an issuer cert.
if(hIssuerStoreHandle = CertOpenSystemStore(0,"CA"))
printf("The CA store is open. Continue. \n");
else
handle_error("The CA store did not open.");
//
// Get a subject cert from the MY store.
if(pSubjectCert=CertEnumCertificatesInStore(
hSubjectStoreHandle,NULL))
printf("A subject certificate is available. Continue.\n");
else
handle_error("A subject certificate was not retrieved.\n\
Perhaps the store is empty.");
if(pIssuerCert=CertEnumCertificatesInStore(
hIssuerStoreHandle,NULL))
printf("An issuer certificate is available. Continue.\n");
else
handle_error("The issuer certificate was not retrieved.\n\
perhaps the store is empty.");
//
// Verify the subject certificate.
if(CertVerifySubjectCertificateContext(
     pSubjectCert,     // Pointer to the subject certificate.
     pIssuerCert,      // Pointer to an issuer certificate.
     &dwFlags          // dwFlags indicating the validity 
                       // conditions to be checked.
    ))
printf("Verify functioned correctly. Continue.\n");
else
handle_error("CertVerify did not function correctly.");
//
// Check the returned flags to see if the certificate passed
// The verification checks.
if (dwFlags > 0)
{
// One or more checks did not pass. Determine which checks failed. 
printf("dwFlags value is %d \n",dwFlags);
if ((dwFlags & CERT_STORE_REVOCATION_FLAG) > 0)
printf("The revocation check failed.\n");
if ((dwFlags & CERT_STORE_SIGNATURE_FLAG) > 0 )
printf("The signature check failed.\n");
if ((dwFlags & CERT_STORE_TIME_VALIDITY_FLAG) > 0 )       
printf("The time validity check failed.\n");
}
else
printf("The certificate passed all validity checks.\n");
//
printf("The program ran to completion without error.\n");

QuickInfo