CertFindChainInStore 函数 (wincrypt.h)

项目
08/27/2023

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	通过使函数仅搜索缓存的系统存储 (根、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 结构的指针。在后续调用此函数时，当作为 pPrevChainContext 参数传递时，将释放 CERT_CHAIN_CONTEXT 结构。否则，必须通过调用 CertFreeCertificateChain 函数显式释放 CERT_CHAIN_CONTEXT 结构。

注解

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

要求


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