CertFindCRLInStore function (wincrypt.h)

Article
10/13/2021

The CertFindCRLInStore function finds the first or next certificate revocation list (CRL) context in a certificate store that matches a search criterion established by the dwFindType parameter and the associated pvFindPara parameter. This function can be used in a loop to find all of the CRL contexts in a certificate store that match the specified find criteria.

Syntax

PCCRL_CONTEXT CertFindCRLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCRL_CONTEXT pPrevCrlContext
);

Parameters

[in] hCertStore

A handle of the certificate store to be searched.

[in] dwCertEncodingType

This parameter is not currently used. It must be set to zero.

[in] dwFindFlags

If dwFindType is CRL_FIND_ISSUED_BY, by default, only issuer name matching is done. The following flags can be used to do additional filtering.

Value	Meaning
CRL_FIND_ISSUED_BY_AKI_FLAG	Checks for a CRL that has an Authority Key Identifier (AKI) extension. If the CRL has an AKI, only a CRL whose AKI matches the issuer is returned. Note The AKI extension has the object identifier (OID) value szOID_AUTHORITY_KEY_IDENTIFIER2 and its corresponding data structure.
CRL_FIND_ISSUED_BY_SIGNATURE_FLAG	Use the public key in the issuer's certificate to verify the signature on the CRL. Only returns a CRL that has a valid signature.
CRL_FIND_ISSUED_BY_DELTA_FLAG	Finds and returns a delta CRL.
CRL_FIND_ISSUED_BY_BASE_FLAG	Finds and returns a base CRL.
CRL_FIND_ISSUED_FOR_SET_STRONG_PROPERTIES_FLAG	The signature is checked for strength after successful verification. This flag applies only when the dwFindType parameter is set to CRL_FIND_ISSUED_FOR. You must also set CRL_FIND_ISSUED_BY_SIGNATURE_FLAG. If successful, the following strong signature properties will be set on the CRL context: CERT_SIGN_HASH_CNG_ALG_PROP_ID CERT_ISSUER_PUB_KEY_BIT_LENGTH_PROP_ID Windows 8 and Windows Server 2012: Support for this flag begins.

[in] dwFindType

Specifies the type of search being made. The value of dwFindType determines the data type, contents, and use of the pvFindPara parameter. Currently defined search types and their pvFindPara requirements are as follows.

Value	Meaning
CRL_FIND_ANY The pvFindPara parameter is not used. It must be set to NULL.	No search criteria. The next CRL in the store is returned.
CRL_FIND_ISSUED_BY A pointer to a CERT_CONTEXT.	Searches for the next CRL in the store matching the issuer in the CERT_CONTEXT.
CRL_FIND_EXISTING A pointer to a CRL_CONTEXT.	Searches for the next CRL that matches the CRL_CONTEXT in the following ways: Both are base or delta CRLs. The issuer-name BLOBs for both are identical. If they exist, the Authority/KeyIdentifier and IssuingDistributionPoint encoded extension BLOBs match.
CRL_FIND_ISSUED_FOR A pointer to a CRL_FIND_ISSUED_FOR_PARA.	Searches for the next CRL in the store that matches the issuer of the subject certificate in the CRL_FIND_ISSUED_FOR_PARA structure. If no CRL is found, searches for the next CRL in the store that matches the issuer in the CRL_FIND_ISSUED_FOR_PARA structure. Note When using cross certificates, the subject name in the issuer's certificate might not match the issuer name in the subject certificate and its corresponding CRL.

[in] pvFindPara

This parameter is determined by the value of dwFindType. For details, see the table earlier in this topic.

[in] pPrevCrlContext

A pointer to the last CRL_CONTEXT returned by this function. Must be NULL to get the first CRL in the store meeting the search criteria. Successive CRLs meeting the search criteria can be found by setting pPrevCrlContext to the PCCRL_CONTEXT pointer returned by a previous call to the function. The search process skips any CRLs that do not match the search criteria or that have been previously deleted from the store by CertDeleteCRLFromStore. This function frees the CRL_CONTEXT referenced by values of this parameter that are not NULL.

Return value

If the function succeeds, the function returns a pointer to a read-only CRL context. When you have finished using the returned CRL context, free it by calling the CertFreeCRLContext function or implicitly free it by passing it as the pPrevCrlContext parameter on a subsequent call to the CertFindCRLInStore function.

If the function fails and a CRL that matches the search criteria is not found, the return value is NULL. For extended error information, call GetLastError. Some possible error codes follow.

Return code	Description
E_INVALIDARG	The handle in the hCertStore parameter is not the same as that in the CRL context pointed to by the pPrevCrlContext parameter, or a search type that is not valid was specified in the dwFindType parameter.
CRYPT_E_NOT_FOUND	No CRLs are in the store, no CRL was found that matched the search criteria, or the end of the store's list was reached.

Remarks

The returned pointer is freed when passed as the pPrevCrlContext parameter on a subsequent call to the function. Otherwise, the pointer must be explicitly freed by calling CertFreeCRLContext. A pPrevCrlContext that is not NULL is always freed by CertFindCRLInStore using a call to CertFreeCRLContext, even if there is an error in the function.

CertDuplicateCRLContext can be called to make a duplicate of the returned context. The returned CRL context can be added to a different certificate store by using CertAddCRLContextToStore, or a link to that CRL context can be added to a noncollection store by using CertAddCRLLinkToStore.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2003 [desktop apps \| UWP apps]
Target Platform	Windows
Header	wincrypt.h
Library	Crypt32.lib
DLL	Crypt32.dll