CertFindChainInStore 函式 (wincrypt.h)

發行項
08/27/2023

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成員包含私密金鑰，因此可能需要在此程式中檢查數次;為了方便進行這項檢查，可以在CERT_CHAIN_FIND_BY_ISSUER_PARA結構中設定dwAcquirePrivateKeyFlags成員，以啟用該 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結構中傳遞的名稱與鏈結中任何憑證授權單位單位 (CA) ，而不只是根憑證中的憑證授權單位單位。

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

如果 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 [僅限傳統型應用程式]
目標平台	Windows
標頭	wincrypt.h
程式庫	Crypt32.lib
Dll	Crypt32.dll