CertFindChainInStore 函式（wincrypt.h）

發行項
07/16/2024

CertFindChainInStore 函式會在符合指定準則的存放區中尋找第一個或下一個憑證。然後，它會建置並驗證該憑證的憑證鏈結內容。找到並建置鏈結的憑證會根據 dwFindFlags、dwFindType和 pvFindPara 參數所建立的準則來選取。此函式可用於迴圈，以在證書存儲中尋找符合指定尋找準則的所有憑證，並針對找到的每個憑證建置憑證鏈結內容。

語法

PCCERT_CHAIN_CONTEXT CertFindChainInStore(
  [in] HCERTSTORE           hCertStore,
  [in] DWORD                dwCertEncodingType,
  [in] DWORD                dwFindFlags,
  [in] DWORD                dwFindType,
  [in] const void           *pvFindPara,
  [in] PCCERT_CHAIN_CONTEXT pPrevChainContext
);

參數

[in] hCertStore

要搜尋鏈結所依據之憑證的存放區句柄。此句柄會當做額外的存放區傳遞至建置鏈結時 CertGetCertificateChain 函式。

[in] dwCertEncodingType

用來編碼存放區的憑證編碼類型。此函式會忽略訊息編碼類型標識碼，包含在此值的高 WORD 中。

此參數可以是下列目前定義的憑證編碼類型。

價值	意義
X509_ASN_ENCODING 1 （0x1）	指定 X.509 憑證編碼。

[in] dwFindFlags

包含搜尋的其他選項。此參數的可能值取決於 dwFindType 參數的值。

當 dwFindType 包含 CERT_CHAIN_FIND_BY_ISSUER時，此參數可以包含下列一或多個值的零或組合。

價值	意義
CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG	比較憑證中的公鑰與密碼編譯服務提供者公鑰。此比較是在建置鏈結時進行的最後一次檢查。因為 hCryptProv 簽發者的成員包含私鑰，所以可能需要在此程式期間檢查數次;為了方便進行這項檢查，dwAcquirePrivateKeyFlags 成員可以在 CERT_CHAIN_FIND_BY_ISSUER_PARA 結構中設定，以啟用該 hCryptProv的快取。
CERT_CHAIN_FIND_BY_ISSUER_COMPLEX_CHAIN_FLAG	根據預設，只會檢查第一個簡單鏈結是否有簽發者名稱相符專案。設定此旗標時，會覆寫預設值，並檢查後續的簡單鏈結是否有簽發者名稱相符專案。
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_FLAG	藉由讓函式只搜尋快取的系統存放區（Root、My、Ca、Trust）來尋找簽發者憑證，藉此改善此函式的效能。如果未設定此旗標，函式會搜尋快取的系統存放區，以及以 hCertStore 參數表示的存放區。
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_URL_FLAG	只會搜尋 URL 快取。未搜尋因特網。
CERT_CHAIN_FIND_BY_ISSUER_LOCAL_MACHINE_FLAG	只會開啟本機計算機證書存儲。目前使用者的證書存儲不會開啟。
CERT_CHAIN_FIND_BY_ISSUER_NO_KEY_FLAG	不會進行任何檢查，以判斷憑證是否有相關聯的私鑰。

[in] dwFindType

決定在存放區中尋找憑證時要使用的準則。

此參數可以是下列目前定義的值。

CERT_CHAIN_FIND_BY_ISSUER

根據簽發者的名稱尋找憑證。 pvFindPara 參數是包含修改搜尋之成員之 CERT_CHAIN_FIND_BY_ISSUER_PARA 結構的指標。

憑證鏈結是針對具有可用私鑰的憑證所建置。根據預設，只有第一個簡單鏈結中的簽發者會比對簽發者名稱相符。如果設定此旗標，則會檢查所有鏈結是否有符合其中一組簽發者名稱的簽發者憑證。

此函式會比較鏈結中傳遞 pvFindPara 結構中 BLOB 的名稱 BLOB，而不只是跟證書中的證書頒發機構單位。

此函式不會執行任何撤銷檢查。

如果 pPrevChainContext 未 NULL，則每次呼叫函式時，此函式都會傳回不同憑證的鏈結。如果只有一個合適的憑證，但有兩個相符的頒發證書授權單位，其中一個已撤銷，則此函式可能會傳回撤銷的鏈結。如果應用程式接著透過呼叫 CertVerifyRevocation 函式來檢查撤銷本身，並發現鏈結不適合，則對 CertFindChainInStore 函式的額外呼叫將不會從有效的證書頒發機構單位傳回包含相同憑證的鏈結。如果找不到這類鏈結，則會改為傳回具有不同憑證或 NULL的完全不同鏈結。

[in] pvFindPara

包含其他搜尋準則的指標。此參數所指向的數據類型和格式，取決於 dwFindType 參數的值。

[in] pPrevChainContext

從先前呼叫這個函式傳回之 CERT_CHAIN_CONTEXT 結構的指標。搜尋會從此憑證開始。對於此函式的第一次呼叫，此參數必須 NULL。在後續呼叫中，它是上一個呼叫函式所傳回的指標。如果此參數未 NULL，則此函式會釋放此結構。

傳回值

如果未建置第一個或下一個鏈結內容，則會傳回 NULL。否則，會傳回只讀 CERT_CHAIN_CONTEXT 結構的指標。在後續呼叫此函式時，CERT_CHAIN_CONTEXT 結構會以 pPrevChainContext 參數的形式傳遞。否則，必須藉由呼叫 CertFreeCertificateChain 函式，明確釋放 CERT_CHAIN_CONTEXT 結構。

言論

pPrevChainContext 參數必須在第一次呼叫上 NULL，才能建置鏈結內容。若要建置下一個鏈結內容，pPrevChainContext 會設定為先前呼叫所傳回的 CERT_CHAIN_CONTEXT 結構。如果 pPrevChainContext 未 NULL，則即使發生錯誤，這個函式仍一律會使用 CertFreeCertificateChain 函式釋放結構。

要求

要求	價值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	wincrypt.h
連結庫	Crypt32.lib
DLL	Crypt32.dll