CertFindCTLInStore 函数 (wincrypt.h)

项目
08/27/2023

CertFindCTLInStore 函数 (CTL) 上下文中查找第一个或下一个证书信任列表，该列表与 dwFindType 及其关联的 pvFindPara 建立的搜索条件匹配。此函数可用于在循环中查找证书存储中与指定查找条件匹配的所有 CTL 上下文。

语法

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

参数

[in] hCertStore

要搜索的证书存储的句柄。

[in] dwMsgAndCertEncodingType

指定 CTL 上使用的编码类型。始终可以接受将证书和消息编码类型与按位 OR 操作组合在一起，如以下示例所示：

X509_ASN_ENCODING |PKCS_7_ASN_ENCODING当前定义的编码类型为：

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

仅当 dwFindType 参数设置为 CTL_FIND_USAGE 时，才使用此参数。

[in] dwFindFlags

当 dwFindType 设置为 CTL_FIND_USAGE 时可以设置。有关详细信息，请参阅以下CTL_FIND_USAGE下的注释。

[in] dwFindType

指定要进行的搜索的类型。搜索类型确定 pvFindPara 的数据类型、内容和用法。此参数的取值可为下列值之一：

值	含义
CTL_FIND_ANY	pvFindPara 的数据类型：NULL。任何 CTL 都是匹配项。
CTL_FIND_SHA1_HASH	pvFindPara 的数据类型：CRYPT_HASH_BLOB。找到一个 CTL，该 CTL 的哈希与 CRYPT_HASH_BLOB 结构中的哈希匹配。
CTL_FIND_MD5_HASH	pvFindPara 的数据类型：CRYPT_HASH_BLOB。找到一个 CTL，该 CTL 的哈希与 CRYPT_HASH_BLOB 结构中的哈希匹配。
CTL_FIND_USAGE	pvFindPara 的数据类型：CTL_FIND_USAGE_PARA。在 CTL_FIND_USAGE_PARA 结构中，找到具有与用法标识符、列表标识符或登录者匹配的用法标识符、列表标识符或签名者的任何 CTL。如果 cUsageIdentifier 成员的大小为 SubjectUsage ，则任何 CTL 都是匹配项。如果 ListIdentifier 成员的 cbData 成员为零，则任何列表标识符都是匹配项。如果 listIdentifier 的 cbData 成员CTL_FIND_NO_LIST_ID_CBDATA，则只有没有列表标识符的 CTL 才匹配。如果CTL_FIND_USAGE_PARA结构中的 pSigner 成员为 NULL，则任何 CTL 签名者都是匹配项，并且仅使用 pSignerCERT_INFO 结构中的 Issuer 和 SerialNumber 成员。如果 pSigner CTL_FIND_NO_SIGNER_PTR，则只有没有签名者的 CTL 才匹配。
CTL_FIND_SAME_USAGE_FLAG	pvFindPara 的数据类型：CTL_FIND_USAGE_PARA。仅匹配使用标识符完全相同的 CTL。不匹配具有其他使用标识符的 CTL。例如，如果在 CTL_FIND_USAGE_PARA 结构中仅指定了“1.2.3”，则对于匹配，CTL 必须仅包含“1.2.3”，而不能包含其他用法标识符。
CTL_FIND_EXISTING	pvFindPara 的数据类型：PCCTL_CONTEXT。搜索与 CTL_CONTEXT完全匹配的下一个 CRL。
CTL_FIND_SUBJECT	pvFindPara 的数据类型：CTL_FIND_SUBJECT_PARA。找到具有指定主题的 CTL。可以调用 CertFindSubjectInCTL 以获取指向 CTL 中使用者条目的指针。可以选择将 CTL_FIND_SUBJECT_PARA 中的 pUsagePara 成员设置为启用前面CTL_FIND_USAGE中所述的匹配。

[in] pvFindPara

指向与 dwFindType 参数关联的搜索值的指针。

[in] pPrevCtlContext

指向此函数返回的最后一个CTL_CONTEXT 的指针。必须为 NULL 才能获取存储中的第一个 CTL。通过将 pPrevCtlContext 设置为指向上一个函数调用返回 的CTL_CONTEXT 的指针来检索连续的 CTL。将跳过不符合搜索条件或以前由 CertDeleteCTLFromStore 删除的任何证书。此函数释放此参数的非 NULL 值引用的CTL_CONTEXT。

返回值

如果函数成功，则返回值是指向只读 CTL 上下文的指针。

有关扩展的错误信息，请调用 GetLastError。下面是一些可能的错误代码。

返回代码	说明
CRYPT_E_NOT_FOUND	要么在存储中找不到 CTL，要么找不到与搜索条件匹配的 CTL，要么函数到达商店列表的末尾。
E_INVALIDARG	hCertStore 参数中的句柄与 pPrevCtlContext 参数指向的 CTL 上下文中的句柄不同，或者在 dwFindType 参数中指定了无效值。

注解

在对函数的后续调用中作为 pPrevCtlContext 传递时，将释放返回的指针。否则，必须通过调用 CertFreeCTLContext 来释放指针。传递给函数的非 NULLpPrevCtlContext 始终通过调用 CertFreeCTLContext 释放，即使该函数生成错误也是如此。

可以调用 CertDuplicateCTLContext 来复制返回的上下文。可以使用 CertAddCTLContextToStore 将返回的 CTL 上下文添加到不同的证书存储，或者可以使用 CertAddCTLLinkToStore 将指向该 CTL 上下文的链接添加到非集合存储。如果未找到与搜索条件匹配的 CTL，则返回 NULL 。

要求

要求	值
最低受支持的客户端	Windows XP [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	wincrypt.h
Library	Crypt32.lib
DLL	Crypt32.dll