CertFindCertificateInStore 函式 (wincrypt.h)

發行項
03/03/2024

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 的使用。此參數可以是下列其中一個值。

值	意義
CERT_FIND_ANY	pvFindPara 的數據類型：NULL，未使用。未使用搜尋準則。傳回存放區中的下一個憑證。注意憑證內容的順序可能不會保留在存放區內。若要存取特定憑證，您必須逐一查看存放區中的憑證。
CERT_FIND_CERT_ID	pvFindPara 的數據類型：CERT_ID 結構。尋找指定之CERT_ID所識別的憑證。
CERT_FIND_CTL_USAGE	pvFindPara 的數據類型：CTL_USAGE 結構。搜尋具有szOID_ENHANCED_KEY_USAGE延伸模組的憑證，或符合CTL_USAGE結構之 pszUsageIdentifier 成員的 CERT_CTL_PROP_ID 。
CERT_FIND_ENHKEY_USAGE	pvFindPara 的數據類型：CERT_ENHKEY_USAGE 結構。在存放區中搜尋具有增強密鑰使用延伸模組或增強密鑰使用方式屬性的憑證，以及符合 CERT_ENHKEY_USAGE 結構中 cUsageIdentifier 成員的使用標識符。如果憑證具有 pszObjId 成員設定為 szOID_ENHANCED_KEY_USAGE 的CERT_EXTENSION結構，則憑證具有增強的密鑰使用方式延伸模組。如果已設定憑證的CERT_ENHKEY_USAGE_PROP_ID標識元，則憑證具有增強的密鑰使用方式屬性。如果在 dwFindFlags 中設定CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG，則不含密鑰使用方式延伸模組或屬性的憑證也會相符。設定此旗標的優先順序高於在 pvFindPara 中傳遞 NULL。如果已設定CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG，則只會在密鑰使用方式延伸模組上完成比對。如需有關搜尋準則之旗標修改的資訊，請參閱。
CERT_FIND_EXISTING	pvFindPara 的數據類型：CERT_CONTEXT 結構。搜尋與指定憑證內容完全相符的憑證。
CERT_FIND_HASH	pvFindPara 的數據類型：CRYPT_HASH_BLOB 結構。搜尋具有SHA1哈希的憑證，該哈希符合 CRYPT_HASH_BLOB 結構中的哈希。
CERT_FIND_HAS_PRIVATE_KEY	pvFindPara 的數據類型：NULL，未使用。搜尋具有私鑰的憑證。金鑰可以是暫時或儲存在磁碟上。密鑰可以是舊版密碼編譯 API (CAPI) 金鑰或 CNG 金鑰。注意憑證內容的順序可能不會保留在存放區內。因此，若要存取特定憑證，您必須逐一查看所有憑證。 Windows 8和 Windows Server 2012：開始支援此旗標。
CERT_FIND_ISSUER_ATTR	pvFindPara 的數據類型：CERT_RDN 結構。搜尋具有指定簽發者屬性的憑證，該屬性符合 CERT_RDN 結構中的屬性。如果已設定這些值，函式會比較憑證中籤發者的屬性與這個CERT_RDN結構中CERT_RDN_ATTR陣列的專案。比較會逐一查看 CERT_RDN_ATTR屬性，尋找與憑證簽發者屬性相符的專案。如果CERT_RDN_ATTR的 pszObjId 成員為 NULL，則會忽略屬性對象識別碼。如果CERT_RDN_ANY_TYPE CERT_RDN_ATTR的 dwValueType 成員，則會忽略實值型別。如果 CERT_RDN_VALUE_BLOB 的 pbData 成員是 NULL，則任何值都是相符的。目前僅支援完全區分大小寫的比對。如需 Unicode 選項的相關信息，請參閱。設定這些值時，搜尋會限制為編碼類型符合 dwCertEncodingType 的憑證。
CERT_FIND_ISSUER_NAME	pvFindPara 的數據類型：CERT_NAME_BLOB 結構。搜尋與整個簽發者名稱完全相符的憑證，其中 CERT_NAME_BLOB 搜尋僅限於符合 dwCertEncodingType 的憑證。
CERT_FIND_ISSUER_OF	pvFindPara 的數據類型：CERT_CONTEXT 結構。搜尋具有符合CERT_CONTEXT中籤發者的主體的憑證。不使用具有此值的 CertFindCertificateInStore ，請使用 CertGetCertificateChain 函式。
CERT_FIND_ISSUER_STR	pvFindPara 的數據類型：Null 終止的 Unicode 字串。搜尋包含指定簽發者名稱字串的憑證。憑證的簽發者成員會使用格式化為 CERT_SIMPLE_NAME_STR 的適當 CertNameToStr 格式，轉換成適當類型的名稱字串。接著會執行不區分大小寫的子字串內相符專案。設定此值時，搜尋會限制為編碼類型符合 dwCertEncodingType 的憑證。如果子字串比對失敗，且主旨包含具有 Punycode 編碼字串的電子郵件 RDN，則CERT_NAME_STR_ENABLE_PUNYCODE_FLAG 用來將主旨轉換成 Unicode 字串，並再次執行子字串比對。
CERT_FIND_KEY_IDENTIFIER	pvFindPara 的數據類型：CRYPT_HASH_BLOB 結構。搜尋具有符合 CRYPT_HASH_BLOB中密鑰標識碼之CERT_KEY_IDENTIFIER_PROP_ID屬性的憑證。
CERT_FIND_KEY_SPEC	pvFindPara 的數據類型：包含密鑰規格的 DWORD 變數。搜尋具有符合 pvFindPara 中密鑰規格之CERT_KEY_SPEC_PROP_ID屬性的憑證。
CERT_FIND_MD5_HASH	pvFindPara 的數據類型：CRYPT_HASH_BLOB 結構。搜尋具有符合 CRYPT_HASH_BLOB 中哈希的 MD5 哈希的憑證。
CERT_FIND_PROPERTY	pvFindPara 的數據類型：包含屬性標識碼的 DWORD 變數。搜尋具有屬性的憑證，該憑證符合 pvFindPara 中 DWORD 值所指定的屬性標識碼。
CERT_FIND_PUBLIC_KEY	pvFindPara 的數據類型：CERT_PUBLIC_KEY_INFO 結構。搜尋具有符合 CERT_PUBLIC_KEY_INFO 結構中公鑰的公鑰的憑證。
CERT_FIND_SHA1_HASH	pvFindPara 的數據類型：CRYPT_HASH_BLOB 結構。搜尋具有SHA1哈希的憑證，該哈希符合 CRYPT_HASH_BLOB 結構中的哈希。
CERT_FIND_SIGNATURE_HASH	pvFindPara 的數據類型：CRYPT_HASH_BLOB 結構。搜尋具有簽章哈希的憑證，該憑證符合 CRYPT_HASH_BLOB 結構中的簽章哈希。
CERT_FIND_SUBJECT_ATTR	pvFindPara 的數據類型：CERT_RDN 結構。搜尋具有指定主體屬性的憑證，以符合 CERT_RDN 結構中的屬性。如果設定 RDN 值，函式會比較憑證中主體的屬性與這個CERT_RDN結構中CERT_RDN_ATTR陣列的專案。比較會逐一查看尋找與憑證主體屬性相符的CERT_RDN_ATTR屬性。如果 CERT_RDN_ATTR 的 pszObjId 成員為 NULL，則會忽略屬性對象識別碼。如果CERT_RDN_ATTR的 dwValueType 成員CERT_RDN_ANY_TYPE，則會忽略實值類型。如果 CERT_RDN_VALUE_BLOB 的 pbData 成員為 NULL，則任何值都是相符的。目前僅支援完全區分大小寫的比對。如需 Unicode 選項的相關信息，請參閱。設定這些值時，搜尋會限制為編碼類型符合 dwCertEncodingType 的憑證。
CERT_FIND_SUBJECT_CERT	pvFindPara 的數據類型：CERT_INFO 結構。搜尋具有簽發者和序號的憑證，其符合 CERT_INFO 結構中的簽發者和序號。
CERT_FIND_SUBJECT_NAME	pvFindPara 的數據類型：CERT_NAME_BLOB 結構。搜尋完整主體名稱與 CERT_NAME_BLOB 結構中名稱完全相符的憑證。搜尋僅限於符合 dwCertEncodingType 值的憑證。
CERT_FIND_SUBJECT_STR	pvFindPara 的數據類型：Null 終止的 Unicode 字串。搜尋包含指定主體名稱字串的憑證。憑證的主體成員會使用格式化為 CERT_SIMPLE_NAME_STR 的適當格式，轉換成適當類型的名稱字串。然後執行不區分大小寫的子字串內字串比對。設定此值時，搜尋僅限於編碼類型符合 dwCertEncodingType 的憑證。
CERT_FIND_CROSS_CERT_DIST_POINTS	pvFindPara 的數據類型：未使用。尋找具有跨憑證發佈點延伸模組或屬性的憑證。
CERT_FIND_PUBKEY_MD5_HASH	pvFindPara 的數據類型：CRYPT_HASH_BLOB 結構。尋找 MD5 哈希公鑰符合指定哈希的憑證。

注意在 pvFindPara 中傳遞字串的 dwFindType 值有替代形式。一個表單使用 Unicode 字串，另一個是 ASCII 字串。結尾為「_W」或不含後綴的值會使用 Unicode。結尾為「_A」的值會使用 ASCII 字串。

[in] pvFindPara

指向與 dwFindType 搭配使用的數據項或結構。

[in] pPrevCertContext

這個函式傳回之最後一個CERT_CONTEXT 結構的指標。這個參數在函式的第一次呼叫時必須是 NULL 。若要尋找符合搜尋準則的後續憑證，請將 pPrevCertContext 設定為先前呼叫函式所傳回的指標。此函式會釋放此參數的非 NULL 值所參考的CERT_CONTEXT。

傳回值

如果函式成功，函式會傳回只讀 CERT_CONTEXT 結構的指標。

如果函式失敗，且找不到符合搜尋準則的憑證，則傳回值為 NULL。

CertFindCertificateInStore 傳回的非 NULLCERT_CONTEXT必須由 CertFreeCertificateContext 釋放，或在後續呼叫 CertFindCertificateInStore 時傳遞為 pPrevCertContext 參數。

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

傳回碼	Description
CRYPT_E_NOT_FOUND	找不到符合搜尋準則的憑證。如果存放區是空的，或到達商店清單的結尾，就會發生這種情況。
E_INVALIDARG	hCertStore 參數中的句柄與 pPrevCertContext 參數所指向之憑證內容中的句柄不同，或是 dwFindType 參數中指定的值無效。

備註

dwFindFlags 參數可用來修改某些搜尋類型的準則。

CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags 值只會與 dwFindType 的CERT_FIND_SUBJECT_ATTR和CERT_FIND_ISSUER_ATTR值搭配使用。如果 pvFindPara 所指向的CERT_RDN_ATTR結構是以 Unicode 字串初始化，就必須設定CERT_UNICODE_IS_RDN_ATTRS_FLAG。進行任何比較之前，會使用 X509_UNICODE_NAME 來提供 Unicode 比較來轉換要比對的字串。

下列 dwFindFlags 值只會與 dwFindType 的CERT_FIND_ENKEY_USAGE值搭配使用：

您可以呼叫 CertDuplicateCertificateContext 來建立傳回內容的重複專案。傳回的內容可以使用 CertAddCertificateContextToStore 新增至不同的證書存儲，或使用該憑證內容的連結新增至不是使用 CertAddCertificateLinkToStore 的存放區。

在後續呼叫函式時，會釋放傳回的指標做為 pPrevCertContext 參數。否則，必須藉由呼叫 CertFreeCertificateContext 明確釋放指標。 pPrevCertContext 不是 NULL 一律由 CertFindCertificateInStore 使用呼叫 CertFreeCertificateContext 釋放，即使函式中有錯誤也一樣。

範例

下列範例示範在證書存儲中尋找符合搜尋準則的憑證內容。如需包含此範例內容的完整範例，請參閱範例 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 應用程式]
目標平台	Windows
標頭	wincrypt.h
程式庫	Crypt32.lib
Dll	Crypt32.dll