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 |
|---|---|
|
Data type of pvFindPara: NULL.
Any CTL is a match. |
|
Data type of pvFindPara: CRYPT_HASH_BLOB.
A CTL with a hash matching the hash in the CRYPT_HASH_BLOB structure is found. |
|
Data type of pvFindPara: CRYPT_HASH_BLOB.
A CTL with a hash matching the hash in the CRYPT_HASH_BLOB structure is found. |
|
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. |
|
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. |
|
Data type of pvFindPara: PCCTL_CONTEXT.
Searches for the next CRL that is an exact match of the CTL_CONTEXT. |
|
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 |
|---|---|
|
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. |
|
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 |