CertFindCTLInStore function (wincrypt.h)

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

Syntax

PCCTL_CONTEXT CertFindCTLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwMsgAndCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCTL_CONTEXT pPrevCtlContext
);

Parameters

[in] hCertStore

Handle of the certificate store to be searched.

[in] dwMsgAndCertEncodingType

Specifies the type of encoding used on the CTL. It is always acceptable to specify both the certificate and message encoding types by combining them with a bitwise-OR operation as shown in the following example:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING Currently defined encoding types are:

  • X509_ASN_ENCODING
  • PKCS_7_ASN_ENCODING

This parameter is used only when the dwFindType parameter is set to CTL_FIND_USAGE.

[in] dwFindFlags

Can be set when dwFindType is set to CTL_FIND_USAGE. For details, see the comments under CTL_FIND_USAGE, following.

[in] dwFindType

Specifies the type of search being made. The search type determines the data type, contents, and the use of pvFindPara. This parameter can be one of the following values.

Value Meaning
CTL_FIND_ANY
Data type of pvFindPara: NULL.

Any CTL is a match.

CTL_FIND_SHA1_HASH
Data type of pvFindPara: CRYPT_HASH_BLOB.

A CTL with a hash matching the hash in the CRYPT_HASH_BLOB structure is found.

CTL_FIND_MD5_HASH
Data type of pvFindPara: CRYPT_HASH_BLOB.

A CTL with a hash matching the hash in the CRYPT_HASH_BLOB structure is found.

CTL_FIND_USAGE
Data type of pvFindPara: CTL_FIND_USAGE_PARA.

Any CTL is found that has a usage identifier, list identifier, or signer matching the usage identifier, list identifier, or signer in the CTL_FIND_USAGE_PARA structure.

If the cUsageIdentifier member is of SubjectUsage size, any CTL is a match.

If the cbData member of ListIdentifier member is zero, any list identifier is a match. If the cbData member of ListIdentifier is CTL_FIND_NO_LIST_ID_CBDATA, only a CTL without a list identifier is a match.

If the pSigner member in the CTL_FIND_USAGE_PARA structure is NULL, any CTL signer is a match, and only the Issuer and SerialNumber members in the pSigner CERT_INFO structure are used. If pSigner is CTL_FIND_NO_SIGNER_PTR, only a CTL without a signer is a match.

CTL_FIND_SAME_USAGE_FLAG
Data type of pvFindPara: CTL_FIND_USAGE_PARA.

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

CTL_FIND_EXISTING
Data type of pvFindPara: PCCTL_CONTEXT.

Searches for the next CRL that is an exact match of the CTL_CONTEXT.

CTL_FIND_SUBJECT
Data type of pvFindPara: CTL_FIND_SUBJECT_PARA.

A CTL having the specified subject is found. CertFindSubjectInCTL can be called to get a pointer to the subject's entry in the CTL. The pUsagePara member in CTL_FIND_SUBJECT_PARA can optionally be set to enable the matching described preceding under CTL_FIND_USAGE.

[in] pvFindPara

A pointer to the search value associated with the dwFindType parameter.

[in] pPrevCtlContext

A pointer to the last CTL_CONTEXT returned by this function. It must be NULL to get the first CTL in the store. Successive CTLs 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 search criteria or that have been previously deleted by CertDeleteCTLFromStore are skipped. This function frees the CTL_CONTEXT referenced by non-NULL values of this parameter.

Return value

If the function succeeds, the return value is a pointer to a read-only CTLcontext.

For extended error information, call GetLastError. Some possible error codes follow.

Return code Description
CRYPT_E_NOT_FOUND
Either no CTLs were found in the store, no CTL was found matching the search criteria, or the function reached the end of the store's list.
E_INVALIDARG
The handle in the hCertStore parameter is not the same as that in the CTL context pointed to by the pPrevCtlContext parameter, or a value that is not valid was specified in the dwFindType parameter.

Remarks

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-NULLpPrevCtlContext passed to the function is always freed with a call to CertFreeCTLContext, even if the function generates an error.

CertDuplicateCTLContext can be called to make a duplicate of the returned context. The returned CTL context can be added to a different certificate store using CertAddCTLContextToStore, or a link to that CTL context can be added to a noncollection store using CertAddCTLLinkToStore. If a CTL matching the search criteria is not found, NULL is returned.

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

See also

CTL_CONTEXT

CTL_FIND_USAGE_PARA

CertAddCTLContextToStore

CertAddCTLLinkToStore

CertDeleteCTLFromStore

CertDuplicateCTLContext

CertEnumCTLsInStore

CertFindSubjectInCTL

CertFreeCTLContext

Certificate Trust List Functions