CertFindCTLInStore 函式 (wincrypt.h)

發行項
03/13/2024

CertFindCTLInStore 函式會尋找符合 dwFindType 及其相關聯 pvFindPara 所建立搜尋準則的第一個或下一個憑證信任清單， (CTL) 內容。此函式可用於迴圈，以在符合指定尋找準則的證書存儲中尋找所有 CTL 內容。

語法

PCCTL_CONTEXT CertFindCTLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwMsgAndCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCTL_CONTEXT pPrevCtlContext
);

參數

[in] hCertStore

要搜尋的證書存儲句柄。

[in] dwMsgAndCertEncodingType

指定 CTL 上所使用的編碼類型。將憑證和訊息編碼類型與位 OR 作業結合在一起，一律可以接受，如下列範例所示：

X509_ASN_ENCODING |PKCS_7_ASN_ENCODING目前定義的編碼類型如下：

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

只有當 dwFindType 參數設定為CTL_FIND_USAGE時，才會使用此參數。

[in] dwFindFlags

當 dwFindType 設定為 CTL_FIND_USAGE 時可以設定。如需詳細資訊，請參閱下列CTL_FIND_USAGE底下的批注。

[in] dwFindType

指定要進行的搜尋類型。搜尋類型會決定數據類型、內容，以及 pvFindPara 的使用。此參數可以是下列其中一個值。

值	意義
CTL_FIND_ANY	pvFindPara 的數據類型：NULL。任何 CTL 都相符。
CTL_FIND_SHA1_HASH	pvFindPara 的數據類型：CRYPT_HASH_BLOB。找到具有符合 CRYPT_HASH_BLOB 結構中哈希的 CTL。
CTL_FIND_MD5_HASH	pvFindPara 的數據類型：CRYPT_HASH_BLOB。找到具有符合 CRYPT_HASH_BLOB 結構中哈希的 CTL。
CTL_FIND_USAGE	pvFindPara 的數據類型：CTL_FIND_USAGE_PARA。發現任何 CTL 都有使用識別碼、清單標識碼或簽署者，符合 CTL_FIND_USAGE_PARA 結構中的使用標識碼、清單標識碼或簽署者。如果 cUsageIdentifier 成員是 SubjectUsage 大小，則任何 CTL 都相符。如果 ListIdentifier 成員的 cbData 成員為零，則任何清單標識碼都是相符的。如果 ListIdentifier 的 cbData 成員CTL_FIND_NO_LIST_ID_CBDATA，則只有不含清單標識碼的 CTL 符合。如果CTL_FIND_USAGE_PARA結構中的 pSigner 成員是 NULL，則任何 CTL 簽署者都相符，而且只會使用 pSignerCERT_INFO 結構中的 Issuer 和 SerialNumber 成員。如果 pSigner 是CTL_FIND_NO_SIGNER_PTR，則只有不含簽署者的 CTL 是相符專案。
CTL_FIND_SAME_USAGE_FLAG	pvFindPara 的數據類型：CTL_FIND_USAGE_PARA。只會比對具有相同使用標識碼的 CTL。具有其他使用標識碼的 CTL 不相符。例如，如果在 CTL_FIND_USAGE_PARA 結構中只指定「1.2.3」，則針對相符專案，CTL 必須只包含「1.2.3」，而且沒有額外的使用標識碼。
CTL_FIND_EXISTING	pvFindPara 的數據類型：PCCTL_CONTEXT。搜尋與 CTL_CONTEXT完全相符的下一個CRL。
CTL_FIND_SUBJECT	pvFindPara 的數據類型：CTL_FIND_SUBJECT_PARA。找到具有指定主體的 CTL。您可以呼叫 CertFindSubjectInCTL ，以取得 CTL 中主體專案的指標。 CTL_FIND_SUBJECT_PARA中的pUsagePara 成員可以選擇性地設定為啟用前面所述的比對CTL_FIND_USAGE。

[in] pvFindPara

與 dwFindType 參數相關聯的搜尋值指標。

[in] pPrevCtlContext

這個函式所傳回之最後一個CTL_CONTEXT 的指標。它必須是 NULL ，才能取得存放區中的第一個 CTL。後續 CTL 的擷取方式是將 pPrevCtlContext 設定為先前函數調用所傳回 CTL_CONTEXT 的指標。系統會略過任何不符合搜尋準則或先前由 CertDeleteCTLFromStore 刪除的憑證。此函式會釋放此參數非 NULL 值所參考的CTL_CONTEXT。

傳回值

如果函式成功，則傳回值是只讀 CTL 內容的指標。

如需擴充的錯誤資訊，請呼叫 GetLastError。接下來有一些可能的錯誤碼。

傳回碼	Description
CRYPT_E_NOT_FOUND	在存放區中找不到 CTL、找不到符合搜尋準則的 CTL，或函式到達商店清單的結尾。
E_INVALIDARG	hCertStore 參數中的句柄與 pPrevCtlContext 參數所指向 CTL 內容中的句柄不同，或 dwFindType 參數中指定的值無效。

備註

在後續呼叫函式時，會釋放傳回的指標當做 pPrevCtlContext 傳遞。否則，必須呼叫 CertFreeCTLContext 來釋放指標。傳遞至函式的非 NULLpPrevCtlContext 一律會釋放呼叫 CertFreeCTLContext，即使函式產生錯誤也一樣。

您可以呼叫 CertDuplicateCTLContext，使傳回的內容重複。傳回的 CTL 內容可以使用 CertAddCTLContextToStore 新增至不同的證書存儲，或使用 CertAddCTLLinkToStore 將 CTL 內容的連結新增至非 CTL 存放區。如果找不到符合搜尋準則的 CTL，則會傳回 NULL 。

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	wincrypt.h
程式庫	Crypt32.lib
Dll	Crypt32.dll