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

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

值 意義
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。 網際網路和內部網路不會搜尋 URL 型物件。

注意 此旗標不適用於撤銷檢查。 將CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY設定為只使用快取的 URL 來進行撤銷檢查。
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING
0x00000040
 基於效能考慮，第二次鏈結建置只會考慮品質大於或等於第一次通過期間決定的最高品質的潛在鏈結路徑。 第一個傳遞只會考慮有效的簽章、完整鏈結和受信任的根目錄，以計算鏈結品質。 此旗標可以設定為停用此優化，並在第二次傳遞期間考慮所有可能的鏈結路徑。
CERT_CHAIN_DISABLE_MY_PEER_TRUST
0x00000800
 不支援此旗標。 「我的」存放區中的憑證永遠不會被視為對等信任。
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 Update網頁伺服器自動更新協力廠商根目錄。
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 秒後逾時、5 秒後的第二秒、2.5 秒後的第三秒等，直到 URL 成功、20 秒通過，或沒有更多要測試的 URL。

如果您未設定CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT，鏈結中的每個撤銷 URL 都會指派等於 dwUrlRetrievalTimeout中所指定值的最大逾時。 如果您未指定 dwUrlRetrievalTimeout 成員的值，則會為每個撤銷 URL 指派最大預設逾時 15 秒。 如果沒有 URL 成功，累積逾時值上限為 15 秒乘以鏈結中的 URL 數目。

您可以使用 群組原則來設定預設值。
CERT_CHAIN_TIMESTAMP_TIME
0x00000200
 設定此旗標時， pTime 會當做時間戳記時間來判斷結束憑證是否有效。 目前時間也可以用來判斷結束憑證是否維持有效時間。 所有其他 憑證授權單位單位 (CA) 和鏈結中的根憑證，都會使用目前時間而非 pTime來檢查。
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_HAS_WEAK_SIGNATURE和CERT_TRUST_IS_NOT_SIGNATURE_VALID錯誤會在CERT_TRUST_STATUS結構的dwErrorStatus欄位中設定。 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
程式庫 Crypt32.lib
Dll Crypt32.dll

另請參閱

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

憑證鏈結驗證函式