CertFindCTLInStore 函数（wincrypt.h）

项目
07/16/2024

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。找到与 CRYPT_HASH_BLOB 结构中的哈希匹配的 CTL。
CTL_FIND_MD5_HASH	pvFindPara的数据类型：CRYPT_HASH_BLOB。找到与 CRYPT_HASH_BLOB 结构中的哈希匹配的 CTL。
CTL_FIND_USAGE	pvFindPara的数据类型：CTL_FIND_USAGE_PARA。发现任何 CTL 都具有与 CTL_FIND_USAGE_PARA 结构中的使用标识符、列表标识符或签名者匹配的使用标识符、列表标识符或签名者。如果 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。仅匹配具有相同使用标识符的 CCL。具有其他使用标识符的 CCL 不匹配。例如，如果在 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 的指针来检索后续 CCL。跳过任何不符合搜索条件或以前已被 CertDeleteCTLFromStore 删除的证书。此函数释放此参数的非NULL 值引用的 CTL_CONTEXT。

返回值

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

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

返回代码	描述
CRYPT_E_NOT_FOUND	在商店中未找到 CTL，也没有找到与搜索条件匹配的 CTL，或者该函数到达商店列表的末尾。
E_INVALIDARG	hCertStore 参数中的句柄与 pPrevCtlContext 参数所指向的 CTL 上下文中的句柄不同，或者 dwFindType 参数中指定的值无效。

言论

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

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

要求

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