CertGetIssuerCertificateFromStore

The CertGetIssuerCertificateFromStore function gets the certificate context from the certificate store for the first or next issuer of the specified subject certificate. The function also performs enabled verification checks on the subject certificate using the returned issuer certificate.

#include <wincrypt.h>
PCCERT_CONTEXT WINAPI CertGetIssuerCertificateFromStore(
  HCERTSTORE hCertStore,                  // in
  PCCERT_CONTEXT pSubjectContext,         // in
  PCCERT_CONTEXT pPrevIssuerContext,      // in, optional
  DWORD *pdwFlags                         // in/out
);
 

Parameters

hCertStore

Handle to the certificate store.

pSubjectContext

Pointer to a subject context. This parameter may be obtained from any certificate store or be created by the caller application using the CertCreateCertificateContext function.

pPrevIssuerContext

Pointer to an issuer context. An issuer may have multiple certificates especially when a validity period is about to change. This parameter must be NULL on the first call to get the first issuer certificate. To get the next certificate for the issuer, set pPrevIssuerContext to the CERT_CONTEXT returned by the previous call.

A pPrevIssuerContext that is not NULL is always freed by this function by using CertFreeCertificateContext, even for an error.

pdwFlags

The following flags can be set in dwFlags to enable verification checks on the returned certificate:

Flag name	Description
CERT_STORE_NO_CRL_FLAG	Value returned if no matching CRL was found.
CERT_STORE_NO_ISSUER_FLAG	Value returned if no issuer certificate was found.
CERT_STORE_REVOCATION_FLAG	Check whether the subject certificate is on the issuer's revocation list.
CERT_STORE_SIGNATURE_FLAG	Use the public key in the issuer's certificate to verify the signature on the subject certificate.
CERT_STORE_TIME_VALIDITY_FLAG	Get the current time and verify 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, its flag remains set upon return. For CERT_STORE_REVOCATION_FLAG, the verificantion succeeds if it does not find a CRL related to the subject certificate.

If CERT_STORE_REVOCATION_FLAG was enabled and the issuer does not have a CRL in the store, CERT_STORE_NO_CRL_FLAG is set in addition to setting CERT_STORE_REVOCATION_FLAG to zero.

If CERT_STORE_SIGNATURE_FLAG or CERT_STORE_REVOCATION_FLAG is set, CERT_STORE_NO_ISSUER_FLAG is set if it does not have an issuer certificate in the store. For more details see the Remarks section.

For a verification check failure, a pointer to the issuer's CERT_CONTEXT is still returned and SetLastError is not updated.

Return Values

If the first or next issuer certificate is not found, NULL is returned. Otherwise, a pointer to a read-only issuer CERT_CONTEXT is returned. The CERT_CONTEXT must be freed by calling CertFreeCertificateContext; however, when the returned CERT_CONTEXT is supplied for pPrevIssuerContext on a subsequent call, the function frees it.

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

Remarks

CertDuplicateCertificateContext can be called to make a duplicate of the issuer certificate.

The hexadecimal values of the dwFlags may be combined using a bitwise OR operation to enable multiple verifications. For example, to enable both signature and time validity, the value 0x00000003 would be placed in the double word dwFlags as the "in" parameter. If CERT_STORE_SIGNATURE_FLAG verification succeeded, but CERT_STORE_TIME_VALIDITY_FLAG verification failed, dwFlags would return set to 0x00000002, as an "out" parameter.

Example

//
// Find the first or next certificate for the issuer
// of a subject certificate using 
// CertGetIssuerCertificateFromStore 
//
#define MY_TYPE  (PKCS_7_ASN_ENCODING | X509_ASN_ENCODING)
//
// The handle_error function is defined in a separate file.
//
HCERTSTORE     hFileStore;     // Handle for the cert store where the
                               // subject certificate will be found.
HCERTSTORE     hCertStore;     // The store in which to find 
                               // the issuer certificate.
PCCERT_CONTEXT pSubjectContext;// The certificate with an issuer 
// to be matched.
PCCERT_CONTEXT pIssuerContext; // NULL for the first call. 
// For subsequent calls, 
// a pointer to the context 
// returned by the previous call.
DWORD dwFlags;                 // Flags to specific conditions 
                               // to be verified. A pointer to this 
                               // DWORD is passed to the function as
                               // an in/out parameter. 

// Open a file based certificate store to find a subject certificate.
// For details, see CertOpenStore.
if(hFileStore=CertOpenStore(
CERT_STORE_PROV_FILENAME,
MY_TYPE,
NULL,
0,
L"teststor.sto"))
printf("The file based store is open. Continue.\n");
else
handle_error("The file store did not open.");
// Get the first certificate from the file store.
if(pSubjectContext=CertEnumCertificateInStore(hFileStore,NULL))
printf("A certificate from the store is retrieved. Continue.\n"):
else
handle_error("No certificate retrieved. The store may be empty.");
// Open a second certificate store to find a subject certificate.
// For details, see CertOpenStore.
if(hCertStore=CertOpenStore(
CERT_STORE_PROV_SYSTEM,
0,
NULL,
CERT_SYSTEM_STORE_CURRENT_USER,
L"MY"))
printf("The second store is open. Continue. \n");
else
handle_error("The second store was not opened.");
// Set verification dwFlags
dwFlags = CERT_STORE_REVOCATION_FLAG;

// Call the CertGetIssuerCerticateFromStore function.
if(CertGetIssuerCertificateFromStore(
hCertStore, 
pSubjectContext,
NULL, 
&dwFlags))
printf("Issuer certificate found.\n");
else
handle_error("An issuer certificate was not found.");
// Check the verification results.
if( dwFlags > 0 )
{
printf("The flag was not re-set.\n");
printf("A CRL was found. This certificate has been revoked.\n");
}
else
{
printf("The flag was re-set.\n");
printf("The verification was successful.\n");
printf("No matching CRL was found. The certificate seems valid.\n");
}
 

QuickInfo

  Windows NT: Requires version 4.0 SP3 or later. Available also in IE 3.02 and later.
  Windows: Requires Windows 95 OSR2 or later.
  Windows CE: Unsupported.
  Header: Declared in wincrypt.h.
  Import Library: Use crypt32.lib.