CertFindCTLInStore

[This is preliminary documentation and subject to change.]

The CertFindCTLInStore function finds the first or next CTL that matches a search criteria. The search criteria is established by the dwFindType and its associated pvFindPara.

#include <wincrypt.h>
PCCTL_CONTEXT WINAPI CertFindCTLInStore(
  HCERTSTORE hCertStore,                  // in
  DWORD dwMsgAndCertEncodingType,         // in
  DWORD dwFindFlags,                      // in
  DWORD dwFindType,                       // in
  const void *pvFindPara,                 // in
  PCCTL_CONTEXT pPrevCtlContext           // in
);

Parameters

hCertStore

Handle to the certificate store to be searched.

dwMsgAndCertEncodingType

Type of encoding used on the CTL. This parameter is used only with the CTL_FIND_USAGE find type and only the LOWORD specifying the encoding type for a signer is needed. For that find type, the parameter should be set to X509_ASN_ENCODING.

dwFindFlags

dwfindFlags can be set for dwfindtype CTL_FIND_USAGE. See the comments under CTL_FIND_USAGE for details.

dwFindType

DWORD that establishes the search type. The value of dwFindType determines the data type, contents, and use of the pvFindPara parameter. Currently defined find types and their pvFindPara requirements are:

CTL_FIND_ANY

pvFindPara is not used. Any CTL is a match.

CTL_FIND_SHA1_HASH or CTL_FIND_MD5_HASH

pvFindPara points to a CRYPT_HASH_BLOB. A CTL with the a hash matching the hash in the CRYPT_HASH_BLOB is found.

CTL_FIND_USAGE

Finds a CTL having a usage identifier, list identifier, or signer matching the usage identifier, list identifier, or signer in the CTL_FIND_USAGE_PARA pointed to by pvFindPara.

If the SubjectUsage.cUsageIdentifier in the CTL_FIND_USAGE_PARA is 0, any CTL is a match.

If the ListIdentifier.cbData in the CTL_FIND_USAGE_PARA is 0, any list identifier is a match. If ListIdentifier.cbData is CTL_FIND_NO_LIST_ID_CBDATA, only a CTL without a list identifier is a match.

If pSigner in the CTL_FIND_USAGE_PARA is NULL, any CTL signer is a match and only the Issuer and SerialNumber fields in the pSigner's PCERT_INFO are used. If psigner is CTL_FIND_NO_SIGNER_PTR, only a CTL without a signer is a match.

CTL_FIND_SAME_USAGE_FLAG

Match only CTLs with the exact same usage identifiers. CTLs having additional usage identifiers are not matched. For example, if only "1.2.3" is specified in CTL_FIND_USAGE_PARA, then, for a match, the CTL must only contain "1.2.3" and no additional usage identifiers.

CTL_FIND_SUBJECT

pvFindPara points to a CTL_FIND_SUBJECT_PARA data structure. A CTL having the specified subject is found. CertFindSubjectInCTL can be called to get a pointer to the subject's entry in the CTL. pUsagePara in CTL_FIND_SUBJECT_PARA can optionally be set to enable the above CTL_FIND_USAGE matching.

pvFindPara

Points to the find parameter associated with the dwFindType.

pPrevCtlContext

Pointer to the last CTL_CONTEXT returned by this function. It must be NULL on the first call of the function. A pPrevCtlContext that is not NULL is always freed by this even if the function causes an error.

Return Values

A pointer to a read-only CTL context is returned. The CTL context must be freed by calling CertFreeCTLContext or it is implicitly freed when passed as the pPrevCtlContext on a subsequent call to CertFindCTLInStore. CertDuplicateCTLContext can be called to make a duplicate of the returned context. The returned CTL context may be added to a different certificate store using CertAddCTLContextToStore or a link to that CTL context can be added to a non-collection store using CertAddCTLLinkToStore. If a CTL matching the search criteria is not found, NULL is returned.

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

Error code	Description
E_INVALIDARG	The hCertStore argument isn't the same as the hCertStore in the CTL context pointed to by the pPrevCtlContext argument. Invalid find type specified by dwFindType argument.
CRYPT_E_NOT_FOUND	No CTLs in the store, or no CTL was found matching the find criteria, or reached the end of the store's list.

Remarks

The pPrevtrlContext parameter must be NULL to get the first CTL in the store. Successive CTLs that match the find criteria are retrieved by setting pPrevCTlContext to the pointer to the CTL_CONTEXT returned by a previous function call. Any certificates that do not meet the find criteria or that have been previously deleted by CertDeleteCTLFromStore. are skipped.

A returned pointer is freed when passed as the pPrevCtlContext on a subsequent call to the function. Otherwise, the pointer must be freed by calling CertFreeCTLContext. A non-NULL pPrevCtlContext passed to the function is always freed with a call to CertFreeCTLContext even if the function generates an error.

Example

See CertFindCertificateInStore. All references to "certificate" should be changed to "CTL."

QuickInfo