CertFindChainInStore 函数（wincrypt.h）

项目
07/16/2024

CertFindChainInStore 函数查找满足指定条件的存储中的第一个或下一个证书。然后，它会生成并验证该证书的证书链上下文。根据 dwFindFlags、dwFindType和 pvFindPara 参数建立的条件来选择找到并为其生成链的证书。此函数可用于在循环中查找与指定查找条件匹配的证书存储中的所有证书，并为找到的每个证书生成证书链上下文。

语法

PCCERT_CHAIN_CONTEXT CertFindChainInStore(
  [in] HCERTSTORE           hCertStore,
  [in] DWORD                dwCertEncodingType,
  [in] DWORD                dwFindFlags,
  [in] DWORD                dwFindType,
  [in] const void           *pvFindPara,
  [in] PCCERT_CHAIN_CONTEXT pPrevChainContext
);

参数

[in] hCertStore

要在其中生成链的证书的存储的句柄。此句柄作为附加存储传递给 CertGetCertificateChain 函数，因为生成链。

[in] dwCertEncodingType

用于对存储进行编码的证书编码类型。此函数忽略高 WORD 中包含的消息编码类型标识符。

此参数可以是以下当前定义的证书编码类型。

价值	意义
X509_ASN_ENCODING 1 （0x1）	指定 X.509 证书编码。

[in] dwFindFlags

包含搜索的其他选项。此参数的可能值取决于 dwFindType 参数的值。

当 dwFindType 包含 CERT_CHAIN_FIND_BY_ISSUER时，此参数可以包含以下一个或多个值的零或组合。

价值	意义
CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG	将证书中的公钥与加密服务提供商公钥进行比较。此比较是在生成链时进行的最后一次检查。由于颁发者 hCryptProv 成员包含私钥，因此可能需要在此过程中多次检查它;为便于进行此检查，可以在 CERT_CHAIN_FIND_BY_ISSUER_PARA 结构中设置 dwAcquirePrivateKeyFlags 成员，以启用该 hCryptProv的缓存。
CERT_CHAIN_FIND_BY_ISSUER_COMPLEX_CHAIN_FLAG	默认情况下，仅检查第一个简单链是否存在颁发者名称匹配项。设置此标志后，将重写默认值，并检查后续的简单链是否存在颁发者名称匹配项。
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_FLAG	通过仅搜索缓存的系统存储（Root、My、Ca、Trust）来查找颁发者证书，从而提高此函数的性能。如果未设置此标志，该函数将搜索缓存的系统存储和由 hCertStore 参数表示的存储。
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_URL_FLAG	仅搜索 URL 缓存。未搜索 Internet。
CERT_CHAIN_FIND_BY_ISSUER_LOCAL_MACHINE_FLAG	仅打开本地计算机证书存储。当前用户的证书存储未打开。
CERT_CHAIN_FIND_BY_ISSUER_NO_KEY_FLAG	不进行检查以确定证书是否具有关联的私钥。

[in] dwFindType

确定在存储区中查找证书时要使用的条件。

此参数可以是当前定义的以下值。

CERT_CHAIN_FIND_BY_ISSUER

根据颁发者的名称查找证书。 pvFindPara 参数是指向包含修改搜索的成员 CERT_CHAIN_FIND_BY_ISSUER_PARA 结构的指针。

证书链是为具有可用私钥的证书构建的。默认情况下，在颁发者名称匹配中仅比较第一个简单链中的颁发者。如果设置了此标志，则会检查与一组颁发者名称之一匹配的颁发者证书的所有链。

此函数会将在 pvFindPara 结构中传递的名称 BLOB 与链中任何证书颁发机构（CA）进行比较，而不仅仅是根证书中的证书颁发机构。

此函数不执行任何吊销检查。

如果 pPrevChainContext 未 NULL，则每次调用函数时，此函数都将返回不同证书的链。如果只有一个合适的证书，但有两个匹配的证书颁发机构，其中一个是吊销的，则此函数可以返回吊销的链。如果应用程序通过对 CertVerifyRevocation 函数的调用检查吊销本身，并且发现链不合适，则对 CertFindChainInStore 函数的附加调用不会返回包含有效证书颁发机构中相同证书的链。如果找不到此类链，它将返回具有不同证书的完全不同的链或 NULL。

[in] pvFindPara

包含其他搜索条件的指针。此参数指向的数据的类型和格式取决于 dwFindType 参数的值。

[in] pPrevChainContext

指向从上一次调用此函数返回的 CERT_CHAIN_CONTEXT 结构的指针。从此证书开始搜索。若要首次调用此函数，此参数必须 NULL。在后续调用中，它是上一次对函数的调用返回的指针。如果此参数未 NULL，此函数将释放此结构。

返回值

如果未生成第一个或下一个链上下文，则返回 null 。否则，将返回指向只读 CERT_CHAIN_CONTEXT 结构的指针。 CERT_CHAIN_CONTEXT 结构在后续调用此函数时作为 pPrevChainContext 参数传递时释放。否则，必须通过调用 CertFreeCertificateChain 函数显式释放 CERT_CHAIN_CONTEXT 结构。

言论

pPrevChainContext 参数必须在第一次调用生成链上下文时 NULL。若要生成下一个链上下文，pPrevChainContext 设置为上一调用返回的 CERT_CHAIN_CONTEXT 结构。如果 pPrevChainContext 未 NULL，则即使发生错误，此函数也始终使用 CertFreeCertificateChain 函数释放该结构。

要求

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