CertSelectCertificateChains 函数 (wincrypt.h)

CertSelectCertificateChains 函数根据指定的选择条件检索证书链。

语法

BOOL CertSelectCertificateChains(
  [in, optional] LPCGUID                  pSelectionContext,
  [in]           DWORD                    dwFlags,
  [in, optional] PCCERT_SELECT_CHAIN_PARA pChainParameters,
  [in]           DWORD                    cCriteria,
  [in, optional] PCCERT_SELECT_CRITERIA   rgpCriteria,
  [in]           HCERTSTORE               hStore,
  [out]          PDWORD                   pcSelection,
  [out]          PCCERT_CHAIN_CONTEXT     **pprgpSelection
);

参数

[in, optional] pSelectionContext

指向要用于此调用的证书选择方案的 GUID 的指针。

[in] dwFlags

用于控制证书选择过程的标志。 此参数可以是零个或多个以下标志的组合：

值	含义
CERT_SELECT_ALLOW_EXPIRED	选择满足选择条件的过期证书。 默认情况下，已过期的证书在选择时被拒绝。
CERT_SELECT_TRUSTED_ROOT	选择证书链信任状态中的错误位未设置为 CERT_TRUST_IS_UNTRUSTED_ROOT、 CERT_TRUST_IS_PARTIAL_CHAIN或 CERT_TRUST_IS_NOT_TIME_VALID的证书。 此外，不会选择具有以下无效约束错误之一的证书： CERT_TRUST_INVALID_POLICY_CONSTRAINTS CERT_TRUST_INVALID_BASIC_CONSTRAINTS CERT_TRUST_INVALID_NAME_CONSTRAINTS
CERT_SELECT_DISALLOW_SELFSIGNED	选择非自颁发和自签名的证书。
CERT_SELECT_HAS_PRIVATE_KEY	选择为证书的 CERT_KEY_PROV_INFO_PROP_ID 属性设置值的证书。
CERT_SELECT_HAS_KEY_FOR_SIGNATURE	选择CERT_KEY_PROV_INFO_PROP_ID属性的dwKeySpec 成员的值设置为AT_SIGNATURE的证书。 如果作为启用 CNG 的应用程序的一部分调用此函数，并且CERT_KEY_PROV_INFO_PROP_ID属性的 dwKeySpec 成员设置为 -1，请选择关联私钥的 NCRYPT_KEY_USAGE_PROPERTY 属性值具有NCRYPT_ALLOW_SIGNING_FLAG集的证书。
CERT_SELECT_HAS_KEY_FOR_KEY_EXCHANGE	选择CERT_KEY_PROV_INFO_PROP_ID属性的dwKeySpec 成员的值设置为AT_KEYEXCHANGE的证书。 如果作为启用 CNG 的应用程序的一部分调用此函数，并且CERT_KEY_PROV_INFO_PROP_ID属性的 dwKeySpec 成员设置为 -1，请选择设置NCRYPT_ALLOW_DECRYPT_FLAG或NCRYPT_ALLOW_KEY_AGREEMENT_FLAG的证书。
CERT_SELECT_HARDWARE_ONLY	选择关联私钥提供程序 的 PP_IMPTYPE 属性值设置为 CRYPT_IMPL_HARDWARE 或 CRYPT_IMPL_REMOVABLE的证书。 (对于 CNG 提供程序，NCRYPT_IMPL_TYPE_PROPERTY属性值必须设置NCRYPT_IMPL_HARDWARE_FLAG位或NCRYPT_IMPL_REMOVABLE_FLAG位) 。 如果作为启用 CNG 的应用程序的一部分调用此函数，请选择 NCRYPT_IMPL_TYPE_PROPERTY 属性设置为 NCRYPT_IMPL_HARDWARE_FLAG 或 NCRYPT_IMPL_REMOVABLE_FLAG的证书。
CERT_SELECT_ALLOW_DUPLICATES	允许选择使用者和使用者可选名称包含相同信息的证书，并且证书模板扩展值等效。 默认情况下，当证书与此条件匹配时，仅选择最新的证书。

[in, optional] pChainParameters

指向 CERT_SELECT_CHAIN_PARA 结构的指针，用于指定链式构建的参数。 如果 为 NULL，则使用默认参数。

CERT_SELECT_CHAIN_PARA 结构的 pChainPara 成员指向可用于启用强签名的 CERT_CHAIN_PARA 结构。

[in] cCriteria

rgpCriteria 数组指向的数组中的元素数。

[in, optional] rgpCriteria

指向定义选择条件 的CERT_SELECT_CRITERIA 结构的数组的指针。 如果此参数设置为 NULL，则 cCriteria 参数的值必须为零。

[in] hStore

要从中选择证书的存储的句柄。

[out] pcSelection

指向 DWORD 值的指针，用于接收 pprgpSelection 参数指向的数组中的元素数。

[out] pprgpSelection

指向要接收CERT_CHAIN_CONTEXT结构数组的位置的 指针的 指针。 CertSelectCertificateChains 函数仅返回与所有选择条件匹配的证书链。 数组中的条目按质量排序，即质量最高的链是第一个条目。

数组的存储由 CertSelectCertificateChains 函数分配。 若要释放分配的内存，必须先通过调用 CertFreeCertificateChain 函数释放数组中的每个单独的链上下文。 然后，必须通过调用 CertFreeCertificateChainList 函数来释放内存。

返回值

如果函数成功，则函数返回 TRUE。

如果函数失败，它将返回零 (FALSE) 。 有关扩展的错误信息，请调用 GetLastError 函数。

注意 如果所选内容未生成任何结果， CertSelectCertificateChains 函数将返回 TRUE，但 pcSelection 参数指向的值设置为零。

 

注解

可以通过 dwFlags 参数、 rgpCriteria 参数或两个参数指定选择条件。 如果未指定选择条件，该函数将成功，并返回 hStore 参数指定的存储区中所有证书的证书链。

所选证书链根据以下首选项逻辑进行排序：

• 首选智能卡证书，而不是基于智能卡的证书。
• 首选有效期较长的证书， (过期日期较晚。)
• 如果多个证书具有相同的到期日期，则首选最近颁发的证书。
• 如果有领带，更喜欢较短的链。

某些选择条件要求先生成证书链，然后才能选择该条件以供使用。 如果生成链所需的中间证书在本地不可用，则会对颁发者证书执行网络检索。 如果设置了 CERT_SELECT_TRUSTED_ROOT 标志或符合以下条件，则执行此网络检索：

• CERT_SELECT_BY_ISSUER_NAME
• CERT_SELECT_BY_ISSUER_ATTR
• CERT_SELECT_BY_POLICY_OID

执行以下操作以启用强签名检查：

• 创建CERT_STRONG_SIGN_PARA结构，指定所需的强签名参数，并设置指向CERT_CHAIN_PARA结构的 pStrongSignPara 成员中的结构的指针。
• 设置指向 CERT_SELECT_CHAIN_PARA 结构的 pChainPara 成员中的 CERT_CHAIN_PARA 结构的指针。
• 设置指向此 (CertSelectCertificateChains) 函数的 pChainParameters 参数中的 CERT_SELECT_CHAIN_PARA 结构的指针。

启用强签名检查时，将跳过在 CERT_TRUST_STATUS 结构的 dwErrorStatus 字段中返回 CERT_TRUST_IS_NOT_SIGNATURE_VALID 错误的任何证书链。 (pprgpSelection 参数指向 CERT_CHAIN_CONTEXT 结构，而该结构又指向 CERT_TRUST_STATUS 结构。) CERT_TRUST_HAS_WEAK_SIGNATURE 值也是 为弱签名设置的。

要求

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

另请参阅

CertGetCertificateContextProperty

CertSetCertificateContextProperty