CertFindCertificateInStore 函式 （wincrypt.h）
CertFindCertificateInStore 函式會在 證書存儲中尋找第一個或下一個 憑證內容， 符合 dwFindType 及其相關聯 pvFindPara所建立的搜尋準則。 此函式可在迴圈中使用，在符合指定尋找準則的
語法
PCCERT_CONTEXT CertFindCertificateInStore(
[in] HCERTSTORE hCertStore,
[in] DWORD dwCertEncodingType,
[in] DWORD dwFindFlags,
[in] DWORD dwFindType,
[in] const void *pvFindPara,
[in] PCCERT_CONTEXT pPrevCertContext
);
參數
[in] hCertStore
要搜尋的 證書存儲句柄。
[in] dwCertEncodingType
指定所使用的編碼類型。 憑證和 訊息編碼類型 都必須結合位OR 作業，如下列範例所示：
X509_ASN_ENCODING |PKCS_7_ASN_ENCODING目前定義的編碼類型如下：
- X509_ASN_ENCODING
- PKCS_7_ASN_ENCODING
[in] dwFindFlags
與某些 dwFindType 搭配使用， 值來修改搜尋準則。 對於大部分 dwFindType 值，dwFindFlags 不會使用，而且應該設定為零。 如需詳細資訊，請參閱。
[in] dwFindType
指定要進行的搜尋類型。 搜尋類型會決定資料類型、內容，以及使用 pvFindPara。 此參數可以是下列其中一個值。
| 價值 | 意義 |
|---|---|
|
pvFindPara的數據類型：未使用 NULL。
未使用搜尋準則。 傳回存放區中的下一個憑證。
附注 存放區中可能不會保留憑證內容的順序。
若要存取特定憑證，您必須在存放區中反覆運算憑證。
|
|
pvFindPara的數據類型：CERT_ID 結構。
尋找指定之 CERT_ID所識別的憑證。 |
|
pvFindPara的數據類型：CTL_USAGE 結構。
搜尋具有szOID_ENHANCED_KEY_USAGE延伸模組的憑證，或符合 |
|
pvFindPara的數據類型：CERT_ENHKEY_USAGE 結構。
搜尋存放區中具有 增強金鑰使用 擴充功能或增強金鑰使用屬性，以及符合 CERT_ENHKEY_USAGE 結構中 cUsageIdentifier 成員的使用標識符。 如果憑證具有設定為 szOID_ENHANCED_KEY_USAGE pszObjId 成員的 CERT_EXTENSION 結構，則憑證具有增強的密鑰使用延伸模組。 如果已設定憑證CERT_ENHKEY_USAGE_PROP_ID標識符，則憑證具有增強的密鑰使用方式屬性。 如果在 dwFindFlags中設定CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG，則沒有密鑰使用方式延伸模組或屬性的憑證也會相符。 在 pvFindPara中，設定此旗標的優先順序高於傳遞 如果已設定CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG，則只會在密鑰使用延伸模組上完成比對。 如需搜尋準則之旗標修改的相關信息，請參閱。 |
|
pvFindPara的數據類型：CERT_CONTEXT 結構。
搜尋與指定之憑證內容完全相符的憑證。 |
|
pvFindPara 搜尋具有SHA1哈希的憑證，該哈希符合 CRYPT_HASH_BLOB 結構中的哈希。 |
|
pvFindPara的數據類型：未使用 NULL。
搜尋具有私鑰的憑證。 金鑰可以是暫時或儲存在磁碟上。 密鑰可以是舊版密碼編譯 API （CAPI） 金鑰或 CNG 金鑰。
附注 存放區中可能不會保留憑證內容的順序。 因此，若要存取特定憑證，您必須跨所有憑證進行反覆運算。
|
|
pvFindPara的數據類型：CERT_RDN 結構。
搜尋具有符合 CERT_RDN 結構中屬性之指定簽發者屬性的憑證。 如果設定這些值，函式會比較憑證中籤發者的屬性與這個 CERT_RDN 結構中 CERT_RDN_ATTR 陣列的專案。 比較會逐一查看尋找與憑證簽發者屬性相符的 CERT_RDN_ATTR 屬性。 如果 pszObjId 成員 CERT_RDN_ATTRNULL，則會忽略屬性對象標識符。 如果 dwValueTypeCERT_RDN_ATTR 的成員是CERT_RDN_ANY_TYPE，則會忽略實值型別。 如果 pbDataCERT_RDN_VALUE_BLOB 成員 NULL，則任何值都是相符的。 目前只支援區分大小寫的確切比對。 如需 Unicode 選項的相關信息，請參閱。 設定這些值時，搜尋會限制為編碼類型符合 dwCertEncodingType的憑證。 |
|
pvFindPara的 搜尋與 CERT_NAME_BLOB 中名稱完全相符之整個簽發者名稱的憑證。搜尋僅限於符合 dwCertEncodingType的憑證。 |
|
pvFindPara的數據類型：CERT_CONTEXT 結構。
搜尋具有符合 CERT_CONTEXT中籤發者之主體的憑證。 請使用 CertGetCertificateChain 函式，而不是搭配此值使用 CertFindCertificateInStore。 |
|
pvFindPara的數據類型：Null 終止的 Unicode 字串。
搜尋包含指定簽發者名稱字串的憑證。 憑證的簽發者成員會使用格式化為 CERT_SIMPLE_NAME_STR 的適當格式，將憑證的簽發者成員轉換成適當類型的名稱字串 CertNameTo Str。 接著會執行不區分大小寫的子字串內字串比對。 設定此值時，搜尋會限制為編碼類型符合 dwCertEncodingType的憑證。 如果子字串比對失敗，且主旨包含具有 Punycode 編碼字串的電子郵件 RDN，則會使用 CERT_NAME_STR_ENABLE_PUNYCODE_FLAG 將主旨轉換成 Unicode 字元串，並再次執行子字元串比對。 |
|
pvFindPara 搜尋具有CERT_KEY_IDENTIFIER_PROP_ID屬性的憑證，該屬性符合 CRYPT_HASH_BLOB中的密鑰標識碼。 |
|
包含索引鍵規格的 pvFindPara資料類型：DWORD 變數。
搜尋具有符合 pvFindPara 中密鑰規格之CERT_KEY_SPEC_PROP_ID屬性的憑證。 |
|
pvFindPara 搜尋具有符合 CRYPT_HASH_BLOB中哈希的 MD5 哈希的憑證。 |
|
pvFindPara的數據類型：包含屬性識別碼的 DWORD 變數。
搜尋具有屬性的憑證，其符合 DWORDpvFindPara中指定的屬性識別符。 |
|
pvFindPara的數據類型：CERT_PUBLIC_KEY_INFO 結構。
搜尋具有符合 CERT_PUBLIC_KEY_INFO 結構中公鑰的公鑰的憑證。 |
|
pvFindPara 搜尋具有SHA1哈希的憑證，該哈希符合 CRYPT_HASH_BLOB 結構中的哈希。 |
|
pvFindPara 搜尋具有符合 CRYPT_HASH_BLOB 結構中哈希的SHA1 + SHA256 哈希的憑證。 |
|
pvFindPara 搜尋具有符合 CRYPT_HASH_BLOB 結構中哈希的SHA256哈希的憑證。 |
|
pvFindPara 搜尋具有符合 CRYPT_HASH_BLOB 結構中籤章哈希之簽章哈希的憑證。 |
|
pvFindPara的數據類型：CERT_RDN 結構。
搜尋具有符合 CERT_RDN 結構中屬性之指定主體屬性的憑證。 如果已設定 RDN 值，函式會比較憑證中主體的屬性與這個 CERT_RDN 結構中 CERT_RDN_ATTR 陣列的專案。 比較會逐一查看尋找與憑證主體屬性相符的 CERT_RDN_ATTR 屬性。 如果 pszObjId 成員 CERT_RDN_ATTRNULL，則會忽略屬性對象標識符。 如果 dwValueTypeCERT_RDN_ATTR 的成員是CERT_RDN_ANY_TYPE，則會忽略實值型別。 如果 pbDataCERT_RDN_VALUE_BLOB 成員 NULL，則任何值都是相符的。 目前只支援區分大小寫的確切比對。 如需 Unicode 選項的相關信息，請參閱。 設定這些值時，搜尋會限制為編碼類型符合 dwCertEncodingType的憑證。 |
|
pvFindPara的數據類型：CERT_INFO 結構。
搜尋具有簽發者和序號的憑證，其符合 CERT_INFO 結構中的簽發者和序號。 |
|
pvFindPara的 搜尋與整個主體名稱完全相符的憑證，並在 CERT_NAME_BLOB 結構中尋找名稱。 搜尋僅限於符合 dwCertEncodingType值的憑證。 |
|
pvFindPara的數據類型：Null 終止的 Unicode 字串。
搜尋包含指定主體名稱字串的憑證。 憑證的主體成員會使用格式化為 CERT_SIMPLE_NAME_STR 的適當格式，將憑證的主體成員轉換成適當類型的名稱字串 CertNameTo Str。 接著會執行不區分大小寫的子字串內字串比對。 設定此值時，搜尋會限制為編碼類型符合 dwCertEncodingType的憑證。 |
|
pvFindPara的數據類型：不使用。
尋找具有跨憑證發佈點延伸模組或屬性的憑證。 |
|
pvFindPara 尋找 MD5 哈希公鑰符合指定哈希的憑證。 |
[in] pvFindPara
指向與 dwFindType搭配使用的數據項或結構。
[in] pPrevCertContext
這個函式所傳回之最後一個 CERT_CONTEXT 結構的指標。 在函式的第一次呼叫上，此參數必須 NULL。 若要尋找符合搜尋準則的後續憑證，請將 pPrevCertContext 設定為先前呼叫函式所傳回的指標。 此函式會釋放此參數的非NULL 值所參考的 CERT_CONTEXT。
傳回值
如果函式成功，函式會傳回只讀 CERT_CONTEXT 結構的指標。
如果函式失敗，且找不到符合搜尋準則的憑證，則傳回值會 NULL。
CertFindCertificateInStore 傳回的非NULLCERT_CONTEXT，必須透過 CertFreeCertificateContext 或傳遞為 pPrevCertContext 參數，在後續呼叫 CertFindCertificateInStore時釋放。
如需擴充錯誤資訊，請呼叫 getLastError
| 傳回碼 | 描述 |
|---|---|
|
找不到符合搜尋準則的憑證。 如果商店是空的，或到達商店清單的結尾，就會發生這種情況。 |
|
|
言論
dwFindFlags 參數可用來修改某些搜尋類型的準則。
CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags 值只會與 dwFindType的CERT_FIND_SUBJECT_ATTR和CERT_FIND_ISSUER_ATTR值搭配使用。 如果 pvFind Para 所指向的 CERT_RDN_ATTR 結構是以 Unicode 字串初始化，則必須設定CERT_UNICODE_IS_RDN_ATTRS_FLAG。 進行任何比較之前，會使用 X509_UNICODE_NAME 來提供 Unicode 比較來轉換要比對的字串。
下列
可呼叫 CertDuplicateCertificateContext，以複製傳回的內容。 傳回的內容可以使用 CertAddCertificateContextToStore，將傳回的內容新增至不同的 證書存儲，或使用 CertAddCertificateLinkToStore，將該憑證內容的連結新增至不是集合存放區的存放區。
在後續呼叫函式時，會釋出傳回的指標做為 pPrevCertContext 參數
例子
下列範例示範在符合搜尋準則的證書存儲中尋找憑證內容。 如需包含此範例內容的完整範例，請參閱 範例 C 程式：證書儲存作業。
如需使用此函式的另一個範例，請參閱 範例 C 程式：集合和同層級證書儲存作業。
#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#pragma comment(lib, "crypt32.lib")
#define MY_ENCODING_TYPE (PKCS_7_ASN_ENCODING | X509_ASN_ENCODING)
void main()
{
//-------------------------------------------------------------------
// Declare and initialize variables.
HCERTSTORE hSystemStore; // The system store handle.
PCCERT_CONTEXT pDesiredCert = NULL; // Set to NULL for the first
// call to
// CertFindCertificateInStore.
LPCSTR lpszCertSubject = (LPCSTR) "Cert_subject_1";
//-------------------------------------------------------------------
// Open the certificate store to be searched.
if(hSystemStore = CertOpenStore(
CERT_STORE_PROV_SYSTEM,
0, // Encoding type not needed
// with this PROV.
NULL, // Accept the default HCRYPTPROV.
CERT_SYSTEM_STORE_CURRENT_USER,
// Set the system store location in
// the registry.
L"MY")) // Could have used other predefined
// system stores
// including Trust, CA, or Root.
{
printf("Opened the MY system store. \n");
}
else
{
printf( "Could not open the MY system store.\n");
exit(1);
}
//-------------------------------------------------------------------
// Get a certificate that has lpszCertSubject as its
// subject.
if(pDesiredCert=CertFindCertificateInStore(
hSystemStore,
MY_ENCODING_TYPE, // Use X509_ASN_ENCODING.
0, // No dwFlags needed.
CERT_FIND_SUBJECT_STR, // Find a certificate with a
// subject that matches the string
// in the next parameter.
lpszCertSubject , // The Unicode string to be found
// in a certificate's subject.
NULL)) // NULL for the first call to the
// function. In all subsequent
// calls, it is the last pointer
// returned by the function.
{
printf("The desired certificate was found. \n");
}
else
{
printf("Could not find the desired certificate.\n");
}
//-------------------------------------------------------------------
// Clean up.
if(pDesiredCert)
CertFreeCertificateContext(pDesiredCert);
if(hSystemStore)
CertCloseStore(
hSystemStore,
CERT_CLOSE_STORE_CHECK_FLAG);
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows XP [傳統型應用程式 |UWP 應用程式] |
| 支援的最低伺服器 | Windows Server 2003 [傳統型應用程式 |UWP 應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | wincrypt.h |
| 連結庫 | Crypt32.lib |
| DLL | Crypt32.dll |
另請參閱
CertAddCertificateContextToStore