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

搜尋支援憑證和 憑證信任清單 （CCL） 的任何其他存放區的句柄。 如果未搜尋其他存放區，則可以 NULL 此參數。

[in] pChainPara

包含鏈結建置參數之 CERT_CHAIN_PARA 結構的指標。

[in] dwFlags

指出特殊處理的旗標值。 此參數可以是下列一或多個旗標的組合。

您也可以設定下列撤銷旗標，但一次只能設定此群組中的一個旗標。

[in] pvReserved

這個參數是保留的，而且必須 NULL。

[out] ppChainContext

所建立鏈結內容的指標位址。 當您完成鏈結內容時，請呼叫 CertFreeCertificateChain 函式來釋放鏈結。

傳回值

如果函式成功，函式會傳回非零 （TRUE）。

如果函式失敗，則會傳回零 （FALSE）。 如需擴充錯誤資訊，請呼叫 getLastError。

言論

當應用程式要求憑證鏈結時，傳回的結構會以 CERT_CHAIN_CONTEXT的形式呈現。 此內容包含一個 CERT_SIMPLE_CHAIN 結構的陣列，其中每個簡單鏈結都會從結束憑證移至自我簽署憑證。 鏈結內容會透過信任清單連接簡單的鏈結。 每個簡單鏈結都包含憑證鏈結、鏈結的摘要信任資訊，以及鏈結中每個憑證元素的信任資訊。

下列備註適用於強式簽章檢查：

• 您可以藉由設定 pStrongSignParapChainPara 參數所指向之 CERT_CHAIN_PARA 結構的成員，來啟用此函式的強式簽章檢查。
• 如果在鏈結中找到沒有強簽章的憑證，則會在 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 錯誤。 若要停用檢查金鑰長度，請在 dwStrongSignFlagspChainPara 參數所指向之 CERT_CHAIN_PARA 結構的成員中設定 CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG 值。
• 如果 CERT_STRONG_SIGN_ENABLE_CRL_CHECK 或 CERT_STRONG_SIGN_ENABLE_OCSP_CHECK 旗標是在 CERT_STRONG_SIGN_SERIALIZED_INFO 結構中設定，且找不到沒有強簽章的 CRL 或 OCSP 回應，CRL 或 OCSP 回應就會被視為脫機。 也就是說，CERT_TRUST_STATUS 結構的 dwErrorStatus 欄位中會設定 CERT_TRUST_IS_OFFLINE_REVOCATION 和 CERT_TRUST_REVOCATION_STATUS_UNKNOWN 錯誤。 此外，dwRevocationResultCERT_REVOCATION_INFO 結構的成員會設定為 NTE_BAD_ALGID。

下列建議適用於呼叫這些 API 的任何 Windows 應用程式，以驗證 TLS 伺服器驗證憑證：

• 只啟用結束憑證的撤銷檢查。
  • 設定 CERT_CHAIN_REVOCATION_CHECK_END_CERT 旗標。
  • 大部分的 CA 憑證都有 CRL 的時間有效期為 1 到 6 個月。
    • 由於已下載的 CRL 已快取，因此這個有效性太長，沒有太多值。
  • 如果 CA 遭到入侵，則憑證也會新增至 Windows 不允許的 CTL
  • TLS 伺服器的建議做法是支援 OCSP 裝訂結束憑證。
    • 在此情況下，除非訂用 OCSP 回應已過期，否則不需要進行網路擷取。
• 啟用CRL、OCSP、AIA簽發者和 Windows 平臺 CTL cab 和第三方根的網路擷取。
  • 設定上述 CERT_CHAIN_REVOCATION_CHECK_END_CERT 時，這是預設值。
  • 請勿設定下列任何旗標，以防止網路擷取。 如需這些旗標的詳細資訊，請參閱上述 dwFlags 表格：
    • CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
    • CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
    • CERT_CHAIN_DISABLE_AIA
• 啟用CRL和 OCSP 網路擷取的累積逾時。
  • 設定傳遞至 CertGetCertificateChain的 CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT 旗標。
  • 提供CRL和 OCSP 網路擷取所允許的總時間上限。
• 將每個網路擷取所允許的時間上限從15縮短為10秒。
  • 將傳遞至 CertGetCertificateChain 到 10 * 1000 毫秒 CERT_CHAIN_PARA 中的 dwUrlRetrievalTimeout 字段設定為 10 * 1000 毫秒。
  • 這也會將累積逾時從 20 秒減少到 10 秒。
    • 只有 OCSP 回應應該下載以取得結束憑證。 5 秒應該足以下載該下載。
• 忽略離線撤銷錯誤。
  • 在傳遞至 CertVerifyCertificateChainPolicy（CERT_CHAIN_POLICY_SSL）的 CERT_CHAIN_POLICY_PARA 中設定 CERT_CHAIN_POLICY_IGNORE_ALL_REV_UNKNOWN_FLAGS。
  • OCSP 和 CRL 的網路擷取是最佳嘗試。 大部分的網路擷取應該會在幾秒鐘內成功，但保證不是 100%。
• 快取結束憑證驗證資訊。
  • 設定 CERT_CHAIN_CACHE_END_CERT。
    • 除了中繼憑證之外，還能夠對結束憑證的信息進行 LRU 快取。
  • 與同一部伺服器建立多個 TLS 連線很常見。

例子

如需使用此函式的範例，請參閱 範例 C 程式：建立憑證鏈結。

要求

另請參閱

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

憑證鏈結驗證函式