CERT_CHAIN_FIND_ISSUER_PARA 结构 (wincrypt.h)

  • 项目

CERT_CHAIN_FIND_BY_ISSUER_PARA 结构包含 CertFindChainInStore 函数中用于生成证书链的信息。

语法

typedef struct _CERT_CHAIN_FIND_BY_ISSUER_PARA {
  DWORD                                  cbSize;
  LPCSTR                                 pszUsageIdentifier;
  DWORD                                  dwKeySpec;
  DWORD                                  dwAcquirePrivateKeyFlags;
  DWORD                                  cIssuer;
  CERT_NAME_BLOB                         *rgIssuer;
  PFN_CERT_CHAIN_FIND_BY_ISSUER_CALLBACK pfnFindCallback;
  void                                   *pvFindArg;
  DWORD                                  *pdwIssuerChainIndex;
  DWORD                                  *pdwIssuerElementIndex;
} CERT_CHAIN_FIND_ISSUER_PARA, *PCERT_CHAIN_FIND_ISSUER_PARA, CERT_CHAIN_FIND_BY_ISSUER_PARA, *PCERT_CHAIN_FIND_BY_ISSUER_PARA;

成员

cbSize

包含此结构的大小（以字节为单位）。 此大小不应进行硬编码。 应在编译时使用 sizeof 运算符对其进行设置，如以下示例所示。

CERT_CHAIN_FIND_BY_ISSUER_PARA findParams;
findParams.cbSize = sizeof(CERT_CHAIN_FIND_BY_ISSUER_PARA);

pszUsageIdentifier

指向包含要匹配的使用标识符的以 null 结尾的 ANSI 字符串的指针。 如果此成员为 NULL，则具有任何用法的证书可以是匹配项。

dwKeySpec

包含要匹配的键规范值。 这可以是以下值之一。 如果此参数为零，则任何证书都可以匹配。

值 含义
AT_KEYEXCHANGE
0x01
 密钥可用于加密或签名，具体取决于算法。
AT_SIGNATURE
0x02
 密钥可用于签名。

dwAcquirePrivateKeyFlags

当 CertFindChainInStore 函数的 dwFindFlags 参数包含CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG时，将调用 CryptAcquireCertificatePrivateKey 函数来执行公钥比较。 在这种情况下，此成员将作为 CryptAcquireCertificatePrivateKey 函数的 dwFlags 参数传递。 有关此成员的可能值及其含义，请参阅 CryptAcquireCertificatePrivateKey 函数的 dwFlags 参数。

cIssuer

包含 rgIssuer 数组中的元素数。 如果此成员为零，则任何颁发者都可以是匹配项。

rgIssuer

X.509 抽象语法表示法 One (ASN.1 的数组) 要匹配的编码颁发者名称 BLOB。 如果此成员为 NULL 或回调函数返回 TRUE，则会将一个新元素添加到具有具有指定 KeySpec 和 增强密钥用法的私钥的证书的链中。

pfnFindCallback

指向 CertChainFindByIssuerCallback 回调函数的指针，该回调函数允许应用程序筛选为其创建链的证书。 如果此成员为 NULL，则会为找到的每个证书生成一个链。 如果此成员不为 NULL，则会根据回调函数的返回值为找到的证书生成一个链。

pvFindArg

应用程序定义的值，将作为此结构的 pfnFindCallback 成员指向的 CertChainFindByIssuerCallback 回调函数的 pvFindArg 参数传递。

pdwIssuerChainIndex

指向 DWORD 值的指针，该值接收与颁发者匹配的链的从零开始的索引。 如果此成员为 NULL，则不使用它。

如果 cIssuer 为零，则不使用此成员。

仅当定义了 CERT_CHAIN_FIND_BY_ISSUER_PARA_HAS_EXTRA_FIELDS 宏时，才会定义此成员。

pdwIssuerElementIndex

指向 DWORD 值的指针，该值接收颁发者证书链中元素的从零开始的索引。 如果此成员为 NULL，则不使用它。

如果 cIssuer 为零，则不使用此成员。

此成员设置为找到的证书的索引和一个，以提供颁发者证书的索引。 因此，部分链或与名称 BLOB 匹配的自签名证书可能会导致 pdwIssuerElementIndex 指向链中的最后一个证书。 可以通过将 pdwIssuerElementIndex 的内容与 CERT_SIMPLE_CHAIN 结构的 cElement 成员进行比较来检测这种情况，以确保索引有效。

仅当定义了 CERT_CHAIN_FIND_BY_ISSUER_PARA_HAS_EXTRA_FIELDS 宏时，才会定义此成员。

注解

pdwIssuerChainIndex 和 pdwIssuerElementIndex 成员仅在定义了 CERT_CHAIN_FIND_BY_ISSUER_PARA_HAS_EXTRA_FIELDS 宏时才可用。 如果定义了 CERT_CHAIN_FIND_BY_ISSUER_PARA_HAS_EXTRA_FIELDS 宏，则应用程序必须将所有未使用的字段初始化为零。

示例

以下伪代码演示如何使用此结构的 pdwIssuerChainIndex 和 pdwIssuerElementIndex 成员来访问颁发者的证书。

CERT_CHAIN_FIND_BY_ISSUER_PARA findParams;
PCCERT_CHAIN_CONTEXT pChainContext = NULL;
DWORD dwChainIndex = 0;
DWORD dwElementIndex = 0;
findParams.pdwIssuerChainIndex = &dwChainIndex;
findParams.pdwIssuerElementIndex = &dwElementIndex;

pChainContext = CertFindChainInStore(
    hCertStore,
    X509_ASN_ENCODING,
    0,
    CERT_CHAIN_FIND_BY_ISSUER,
    (LPVOID)&findParams,
    NULL);
if(pChainContext)
{
    // Make sure the element index is valid.
    if(dwElementIndex < pChainContext->
        rgpChain[dwChainIndex]->cElement)
    {
        PCERT_CHAIN_ELEMENT pIssuerElement;
        pIssuerElement = pChainContext->
            rgpChain[dwChainIndex]->rgpElement[dwElementIndex];
       // ...
    }

    // Free the certificate chain.
    CertFreeCertificateChain(pChainContext);
}

要求

要求 值
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
标头 wincrypt.h

另请参阅

CertChainFindByIssuerCallback

CertFindChainInStore

CryptAcquireCertificatePrivateKey