CertGetCertificateChain 函数 (wincrypt.h)

  • 项目

CertGetCertificateChain 函数生成一个证书链上下文，该上下文从结束证书开始，并在可能的情况下返回到受信任的根证书。

语法

BOOL CertGetCertificateChain(
  [in, optional] HCERTCHAINENGINE     hChainEngine,
  [in]           PCCERT_CONTEXT       pCertContext,
  [in, optional] LPFILETIME           pTime,
  [in]           HCERTSTORE           hAdditionalStore,
  [in]           PCERT_CHAIN_PARA     pChainPara,
  [in]           DWORD                dwFlags,
  [in]           LPVOID               pvReserved,
  [out]          PCCERT_CHAIN_CONTEXT *ppChainContext
);

参数

[in, optional] hChainEngine

链引擎的句柄 (要使用的命名空间和缓存) 。 如果 hChainEngine 为 NULL，则使用默认链引擎HCCE_CURRENT_USER。 此参数可以设置为 HCCE_LOCAL_MACHINE。

[in] pCertContext

指向结束证书（为其生成链的证书 ）CERT_CONTEXT 的指针。 此证书上下文将是第一个简单链中的零索引元素。

[in, optional] pTime

指向 FILETIME 变量的指针，该变量指示要验证链的时间。 请注意，该时间不会影响信任列表、吊销或根存储检查。 如果将 NULL 传递给此参数，则使用当前系统时间。 对作为受信任根的特定证书的信任基于根存储的当前 状态 ，而不是此参数传入的时间根存储的状态。 对于吊销，证书 吊销列表 (CRL) 本身在当前时间必须有效。 此参数的值用于确定是否吊销 CRL 中列出的证书。

[in] hAdditionalStore

任何其他存储的句柄，用于搜索支持证书和 证书信任列表 (CTL) 。 如果不搜索其他存储，此参数可以为 NULL 。

[in] pChainPara

指向包含链构建参数 的CERT_CHAIN_PARA 结构的指针。

[in] dwFlags

标记指示特殊处理的值。 此参数可以是以下一个或多个标志的组合。

值 含义
CERT_CHAIN_CACHE_END_CERT
0x00000001
 设置此标志后，将缓存结束证书，这可能会加快链构建过程。 默认情况下，不会缓存结束证书，每次为其生成链时，都需要对其进行验证。
CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
0x80000000
 吊销检查仅访问缓存的 URL。
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT
0x04000000
 此标志在链生成过程中用于 联机证书状态协议 (OCSP) 签名者证书，以防止循环吊销检查。 在链生成期间，如果 OCSP 响应由独立的 OCSP 签名者签名，则除了原始链生成之外，还有另一个链是为 OCSP 签名者证书本身构建的。 此标志在第二个链生成期间用于禁止递归独立 OCSP 签名者证书。 如果签名者证书包含 szOID_PKIX_OCSP_NOCHECK 扩展，则会跳过叶签名者证书的吊销检查。 允许 OCSP 和 CRL 检查。

Windows Server 2003 和 Windows XP： 不支持此值。
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
0x00000004
 在生成证书链时仅使用缓存的 URL。 不会在 Internet 和 Intranet 中搜索基于 URL 的对象。

注意 此标志不适用于吊销检查。 将CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY设置为仅使用缓存的 URL 进行吊销检查。
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING
0x00000040
 出于性能原因，链构建的第二个通道仅考虑质量高于或等于第一次传递期间确定的最高质量的潜在链路径。 第一个传递仅考虑有效的签名、完整的链和受信任的根来计算链质量。 可以将此标志设置为禁用此优化，并在第二次传递期间考虑所有可能的链路径。
CERT_CHAIN_DISABLE_MY_PEER_TRUST
0x00000800
 不支持此标志。 “My”存储中的证书永远不会被视为对等信任。
CERT_CHAIN_ENABLE_PEER_TRUST
0x00000400
 信任“TrustedPeople”存储中的最终实体证书，无需执行任何链构建。 此函数不设置 ppChainContext 参数CERT_TRUST_IS_PARTIAL_CHAIN或CERT_TRUST_IS_UNTRUSTED_ROOTdwErrorStatus 成员位。 Windows Server 2003 Windows XP ： 不支持此标志。
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE
0x00010000
 设置此标志表示调用方希望选择进行弱签名检查。

此标志在从 Windows 7 和 Windows Server 2008 R2 开始的每个 OS 的汇总更新中可用。
CERT_CHAIN_RETURN_LOWER_QUALITY_CONTEXTS
0x00000080
 默认值是仅返回最高质量的链路径。 设置此标志将返回质量较低的链。 这些值在链上下文的 cLowerQualityChainContext 和 rgpLowerQualityChainContext 字段中返回。
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE
0x00000100
 设置此标志会禁止从Windows 更新 Web 服务器自动更新第三方根。
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT
0x08000000
 设置CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT并为CERT_CHAIN_PARA结构的 dwUrlRetrievalTimeout 成员指定值时，在 dwUrlRetrievalTimeout 中指定的值表示所有吊销 URL 检索中的累积超时。

如果设置CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT但没有指定 dwUrlRetrievalTimeout 值，则默认将最大累积超时设置为 20 秒。 测试的每个 URL 将在剩余累积余额的一半通过后超时。 也就是说，第一个 URL 在 10 秒后超时，第二个 URL 在 5 秒后超时，第三个 URL 在 2.5 秒后超时，依此以类比，直到 URL 成功、20 秒已通过，或者没有更多要测试的 URL。

如果未设置CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT，则会为链中的每个吊销 URL 分配等于 dwUrlRetrievalTimeout 中指定的值的最大超时值。 如果未为 dwUrlRetrievalTimeout 成员指定值，则会为每个吊销 URL 分配最大默认超时 15 秒。 如果没有成功 URL，则最大累积超时值是 15 秒乘以链中的 URL 数。

可以使用 组策略 设置默认值。
CERT_CHAIN_TIMESTAMP_TIME
0x00000200
 设置此标志后， pTime 将用作时间戳时间，以确定结束证书的时间是否有效。 当前时间还可用于确定结束证书的时间是否保持有效。 使用当前时间而不是 pTime 检查链中 (CA) 和根证书的所有其他证书颁发机构。
CERT_CHAIN_DISABLE_AIA
0x00002000
 设置此标志会显式关闭机构信息访问 (AIA) 检索。
 

还可以设置以下吊销标志，但一次只能设置此组中的一个标志。

值 含义
CERT_CHAIN_REVOCATION_CHECK_END_CERT
0x10000000
 吊销检查是在结束证书上完成的，并且仅对结束证书执行。
CERT_CHAIN_REVOCATION_CHECK_CHAIN
0x20000000
 吊销检查是在每个链中的所有证书上完成的。
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT
0x40000000
 吊销检查对所有链中的所有证书执行，根证书除外。

[in] pvReserved

此参数是保留的，必须为 NULL。

[out] ppChainContext

指向所创建的链上下文的指针的地址。 使用完链上下文后，通过调用 CertFreeCertificateChain 函数释放链。

返回值

如果函数成功，则函数) 返回非零 (TRUE 。

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

注解

当应用程序请求证书链时，返回的结构采用 CERT_CHAIN_CONTEXT的形式。 此上下文包含 CERT_SIMPLE_CHAIN 结构数组，其中每个简单链从结束证书到自签名证书。 链上下文通过信任列表连接简单链。 每个简单链都包含证书链、有关链的摘要信任信息，以及有关链中每个证书元素的信任信息。

以下备注适用于强签名检查：

  • 可以通过设置 pChainPara 参数指向的 CERT_CHAIN_PARA 结构的 pStrongSignPara 成员来为此函数启用强签名检查。
  • 如果在链中找到没有强签名的证书，则会在CERT_TRUST_STATUS结构的 dwErrorStatus 字段中设置CERT_TRUST_HAS_WEAK_SIGNATURE和CERT_TRUST_IS_NOT_SIGNATURE_VALID错误。 ppChainContext 参数指向CERT_CHAIN_CONTEXT结构，该结构又指向CERT_TRUST_STATUS结构。
  • 如果链是强签名的，则会检查最终证书中的公钥，以确定它是否满足强签名的最小公钥长度要求。 如果不满足条件，则会在CERT_TRUST_STATUS结构的 dwErrorStatus 字段中设置CERT_TRUST_HAS_WEAK_SIGNATURE和CERT_TRUST_IS_NOT_SIGNATURE_VALID错误。 若要禁用检查密钥长度，请在 pChainPara 参数指向的CERT_CHAIN_PARA结构的 dwStrongSignFlags 成员中设置CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG值。
  • 如果在CERT_STRONG_SIGN_SERIALIZED_INFO结构中设置了CERT_STRONG_SIGN_ENABLE_CRL_CHECK或CERT_STRONG_SIGN_ENABLE_OCSP_CHECK标志，并且找到没有强签名的 CRL 或 OCSP 响应，则 CRL 或 OCSP 响应将被视为脱机。 也就是说，CERT_TRUST_IS_OFFLINE_REVOCATION和CERT_TRUST_REVOCATION_STATUS_UNKNOWN错误在CERT_TRUST_STATUS结构的 dwErrorStatus 字段中设置。 此外，CERT_REVOCATION_INFO 结构的 dwRevocationResult 成员设置为 NTE_BAD_ALGID。

示例

有关使用此函数的示例，请参阅 示例 C 程序：创建证书链。

要求

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

另请参阅

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

证书链验证函数