CertFindCertificateInStore-Funktion (wincrypt.h)

Artikel
07/11/2024

Die funktion CertFindCertificateInStore findet das erste oder nächste Zertifikat Kontext in einem Zertifikatspeicher, das einem Suchkriterium entspricht, das von der dwFindType und den zugehörigen pvFindParafestgelegt wurde. Diese Funktion kann in einer Schleife verwendet werden, um alle Zertifikate zu finden, in einem Zertifikatspeicher, die den angegebenen Suchkriterien entsprechen.

Syntax

PCCERT_CONTEXT CertFindCertificateInStore(
  [in] HCERTSTORE     hCertStore,
  [in] DWORD          dwCertEncodingType,
  [in] DWORD          dwFindFlags,
  [in] DWORD          dwFindType,
  [in] const void     *pvFindPara,
  [in] PCCERT_CONTEXT pPrevCertContext
);

Parameter

[in] hCertStore

Ein Handle des Zertifikatspeichers, durchsucht werden soll.

[in] dwCertEncodingType

Gibt den Typ der verwendeten Codierung an. Sowohl das Zertifikat als auch Nachrichtencodierungstypen müssen angegeben werden, indem sie mit einem bitweisenODER--Vorgang kombiniert werden, wie im folgenden Beispiel gezeigt:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING Derzeit definierte Codierungstypen sind:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFindFlags

Wird mit einigen dwFindType- Werten verwendet, um die Suchkriterien zu ändern. Für die meisten dwFindType--Werte wird dwFindFlags- nicht verwendet und sollte auf Null festgelegt werden. Ausführliche Informationen finden Sie in den Hinweisen.

[in] dwFindType

Gibt den Suchtyp an, der erstellt wird. Der Suchtyp bestimmt den Datentyp, den Inhalt und die Verwendung von pvFindPara. Dieser Parameter kann einer der folgenden Werte sein:

Wert	Bedeutung
CERT_FIND_ANY	Datentyp von pvFindPara: NULLnicht verwendet. Es werden keine Suchkriterien verwendet. Gibt das nächste Zertifikat im Speicher zurück. Hinweis Die Reihenfolge des Zertifikatkontexts bleibt möglicherweise nicht im Speicher erhalten. Um auf ein bestimmtes Zertifikat zuzugreifen, müssen Sie die Zertifikate im Speicher durchlaufen.
CERT_FIND_CERT_ID	Datentyp des pvFindPara: CERT_ID Struktur. Suchen Sie das von der angegebenen CERT_IDidentifizierte Zertifikat.
CERT_FIND_CTL_USAGE	Datentyp von pvFindPara: CTL_USAGE Struktur. Sucht nach einem Zertifikat mit einer szOID_ENHANCED_KEY_USAGE Erweiterung oder einer CERT_CTL_PROP_ID, die dem pszUsageIdentifier Mitglied der CTL_USAGE-Struktur entspricht.
CERT_FIND_ENHKEY_USAGE	Datentyp der pvFindPara-: CERT_ENHKEY_USAGE Struktur. Sucht nach einem Zertifikat im Speicher, das entweder über eine erweiterte Schlüsselverwendung Erweiterung oder eine eigenschaft für die erweiterte Schlüsselverwendung verfügt, und einen Verwendungsbezeichner, der dem cUsageIdentifier Member in der CERT_ENHKEY_USAGE Struktur entspricht. Ein Zertifikat verfügt über eine erweiterte Schlüsselverwendungserweiterung, wenn es eine CERT_EXTENSION Struktur mit dem pszObjId Member auf szOID_ENHANCED_KEY_USAGE festgelegt hat. Ein Zertifikat verfügt über eine erweiterte Schlüsselverwendungseigenschaft, wenn der CERT_ENHKEY_USAGE_PROP_ID Bezeichner festgelegt ist. Wenn CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG in dwFindFlagsfestgelegt wird, werden Zertifikate ohne die Schlüsselverwendungserweiterung oder -eigenschaft ebenfalls übereinstimmen. Das Festlegen dieses Flags hat Vorrang vor der Übergabe NULL- in pvFindPara-. Wenn CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG festgelegt ist, erfolgt eine Übereinstimmung nur für die Schlüsselverwendungserweiterung. Informationen zu Kennzeichnungsänderungen an Suchkriterien finden Sie in den Hinweisen.
CERT_FIND_EXISTING	Datentyp von pvFindPara: CERT_CONTEXT Struktur. Sucht nach einem Zertifikat, das genau mit dem angegebenen Zertifikatkontext übereinstimmt.
CERT_FIND_HASH	Datentyp des pvFindPara: CRYPT_HASH_BLOB Struktur. Sucht nach einem Zertifikat mit einem SHA1-Hash, der dem Hash in der CRYPT_HASH_BLOB-Struktur entspricht.
CERT_FIND_HAS_PRIVATE_KEY	Datentyp von pvFindPara: NULLnicht verwendet. Sucht nach einem Zertifikat mit einem privaten Schlüssel. Der Schlüssel kann kurzlebig sein oder auf dem Datenträger gespeichert werden. Der Schlüssel kann ein legacy-Kryptografie-API-Schlüssel (CAPI) oder ein CNG-Schlüssel sein. Hinweis Die Reihenfolge des Zertifikatkontexts bleibt möglicherweise nicht im Speicher erhalten. Daher müssen Sie für den Zugriff auf ein bestimmtes Zertifikat alle Zertifikate durchlaufen. Windows 8 und Windows Server 2012: Unterstützung für dieses Flag beginnt.
CERT_FIND_ISSUER_ATTR	Datentyp des pvFindPara-: CERT_RDN Struktur. Sucht nach einem Zertifikat mit angegebenen Ausstellerattributen, die Attribute in der CERT_RDN Struktur entsprechen. Wenn diese Werte festgelegt sind, vergleicht die Funktion Attribute des Ausstellers in einem Zertifikat mit Elementen des CERT_RDN_ATTR Arrays in dieser CERT_RDN Struktur. Vergleiche durchlaufen die CERT_RDN_ATTR Attribute, die nach einer Übereinstimmung mit den Ausstellerattributen des Zertifikats suchen. Wenn das pszObjId Member von CERT_RDN_ATTRNULL-ist, wird der Attributobjektbezeichner ignoriert. Wenn der dwValueType Member von CERT_RDN_ATTR CERT_RDN_ANY_TYPE ist, wird der Werttyp ignoriert. Wenn das pbData- Mitglied von CERT_RDN_VALUE_BLOBNULL-ist, ist jeder Wert eine Übereinstimmung. Derzeit wird nur eine genaue Übereinstimmung zwischen Groß- und Kleinschreibung unterstützt. Informationen zu Unicode-Optionen finden Sie in den Hinweisen. Wenn diese Werte festgelegt werden, wird die Suche auf Zertifikate beschränkt, deren Codierungstyp dwCertEncodingTypeentspricht.
CERT_FIND_ISSUER_NAME	Datentyp des pvFindPara: CERT_NAME_BLOB Struktur. Suchen Sie nach einem Zertifikat mit einer exakten Übereinstimmung des gesamten Ausstellernamens mit dem Namen in CERT_NAME_BLOB Die Suche ist auf Zertifikate beschränkt, die mit dem dwCertEncodingTypeübereinstimmen.
CERT_FIND_ISSUER_OF	Datentyp von pvFindPara: CERT_CONTEXT Struktur. Sucht nach einem Zertifikat mit einem Betreff, der dem Aussteller in CERT_CONTEXTentspricht. Anstatt CertFindCertificateInStore- mit diesem Wert zu verwenden, verwenden Sie die CertGetCertificateChain--Funktion.
CERT_FIND_ISSUER_STR	Datentyp von pvFindPara: Null-gekündigte Unicode-Zeichenfolge. Sucht nach einem Zertifikat, das die angegebene Ausstellernamenzeichenfolge enthält. Das Ausstellermitglied des Zertifikats wird mithilfe der entsprechenden Form von CertNameToStr als CERT_SIMPLE_NAME_STR formatiert in eine Namenszeichenfolge des entsprechenden Typs konvertiert. Anschließend wird eine Zwischenzeichenfolgenüberstimmung zwischen Groß- und Kleinschreibung durchgeführt. Wenn dieser Wert festgelegt ist, ist die Suche auf Zertifikate beschränkt, deren Codierungstyp dwCertEncodingTypeentspricht. Wenn die Teilzeichenfolgenüberstimmung fehlschlägt und der Betreff eine E-Mail-RDN mit punycode-codierter Zeichenfolge enthält, wird CERT_NAME_STR_ENABLE_PUNYCODE_FLAG verwendet, um den Betreff in eine Unicode-Zeichenfolge zu konvertieren, und die Teilzeichenfolgenüberstimmung wird erneut ausgeführt.
CERT_FIND_KEY_IDENTIFIER	Datentyp des pvFindPara: CRYPT_HASH_BLOB Struktur. Sucht nach einem Zertifikat mit einer CERT_KEY_IDENTIFIER_PROP_ID-Eigenschaft, die dem Schlüsselbezeichner in CRYPT_HASH_BLOBentspricht.
CERT_FIND_KEY_SPEC	Datentyp von pvFindPara: DWORD Variable, die eine Schlüsselspezifikation enthält. Sucht nach einem Zertifikat mit einer CERT_KEY_SPEC_PROP_ID Eigenschaft, die der Schlüsselspezifikation in pvFindParaentspricht.
CERT_FIND_MD5_HASH	Datentyp des pvFindPara: CRYPT_HASH_BLOB Struktur. Sucht nach einem Zertifikat mit einem MD5-Hash, der dem Hash in CRYPT_HASH_BLOBentspricht.
CERT_FIND_PROPERTY	Datentyp des pvFindPara-: DWORD- Variable, die einen Eigenschaftsbezeichner enthält. Sucht nach einem Zertifikat mit einer Eigenschaft, die dem durch den DWORD- Wert in pvFindPara-angegebenen Eigenschaftsbezeichner entspricht.
CERT_FIND_PUBLIC_KEY	Datentyp von pvFindPara: CERT_PUBLIC_KEY_INFO Struktur. Sucht nach einem Zertifikat mit einem öffentlichen Schlüssel, der dem öffentlichen Schlüssel in der CERT_PUBLIC_KEY_INFO-Struktur entspricht.
CERT_FIND_SHA1_HASH	Datentyp des pvFindPara: CRYPT_HASH_BLOB Struktur. Sucht nach einem Zertifikat mit einem SHA1-Hash, der dem Hash in der CRYPT_HASH_BLOB-Struktur entspricht.
CERT_FIND_SHA1_SHA256_HASH	Datentyp des pvFindPara: CRYPT_HASH_BLOB Struktur. Sucht nach einem Zertifikat mit einem SHA1 + SHA256-Hash, der dem Hash in der CRYPT_HASH_BLOB-Struktur entspricht.
CERT_FIND_SHA256_HASH	Datentyp des pvFindPara: CRYPT_HASH_BLOB Struktur. Sucht nach einem Zertifikat mit einem SHA256-Hash, der dem Hash in der CRYPT_HASH_BLOB-Struktur entspricht.
CERT_FIND_SIGNATURE_HASH	Datentyp des pvFindPara: CRYPT_HASH_BLOB Struktur. Sucht nach einem Zertifikat mit einem Signaturhash, der dem Signaturhash in der CRYPT_HASH_BLOB-Struktur entspricht.
CERT_FIND_SUBJECT_ATTR	Datentyp des pvFindPara-: CERT_RDN Struktur. Sucht nach einem Zertifikat mit angegebenen Betreffattributen, die Attribute in der CERT_RDN Struktur entsprechen. Wenn RDN-Werte festgelegt werden, vergleicht die Funktion Attribute des Betreffs in einem Zertifikat mit Elementen des CERT_RDN_ATTR Arrays in dieser CERT_RDN Struktur. Vergleiche durchlaufen die CERT_RDN_ATTR Attribute, die nach einer Übereinstimmung mit den Attributen des Zertifikatsbetreffs suchen. Wenn das pszObjId Member von CERT_RDN_ATTRNULL-ist, wird der Attributobjektbezeichner ignoriert. Wenn der dwValueType Member von CERT_RDN_ATTR CERT_RDN_ANY_TYPE ist, wird der Werttyp ignoriert. Wenn das pbData- Mitglied von CERT_RDN_VALUE_BLOBNULL-ist, ist jeder Wert eine Übereinstimmung. Derzeit wird nur eine genaue Übereinstimmung zwischen Groß- und Kleinschreibung unterstützt. Informationen zu Unicode-Optionen finden Sie in den Hinweisen. Wenn diese Werte festgelegt werden, wird die Suche auf Zertifikate beschränkt, deren Codierungstyp dwCertEncodingTypeentspricht.
CERT_FIND_SUBJECT_CERT	Datentyp von pvFindPara: CERT_INFO Struktur. Sucht nach einem Zertifikat mit einem Aussteller und einer Seriennummer, die dem Aussteller und der Seriennummer in der CERT_INFO Struktur entspricht.
CERT_FIND_SUBJECT_NAME	Datentyp des pvFindPara: CERT_NAME_BLOB Struktur. Sucht nach einem Zertifikat mit einer exakten Übereinstimmung des gesamten Antragstellernamens mit dem Namen in der CERT_NAME_BLOB-Struktur. Die Suche ist auf Zertifikate beschränkt, die dem Wert von dwCertEncodingTypeentsprechen.
CERT_FIND_SUBJECT_STR	Datentyp von pvFindPara: Null-gekündigte Unicode-Zeichenfolge. Sucht nach einem Zertifikat, das die angegebene Antragstellernamenzeichenfolge enthält. Das Antragstellerelement des Zertifikats wird mithilfe der entsprechenden Form von CertNameToStr- als CERT_SIMPLE_NAME_STR formatiert in eine Namenszeichenfolge des entsprechenden Typs konvertiert. Anschließend wird eine Zwischenzeichenfolgenüberstimmung zwischen Groß- und Kleinschreibung durchgeführt. Wenn dieser Wert festgelegt ist, ist die Suche auf Zertifikate beschränkt, deren Codierungstyp dwCertEncodingTypeentspricht.
CERT_FIND_CROSS_CERT_DIST_POINTS	Datentyp von pvFindPara: Nicht verwendet. Suchen Sie ein Zertifikat mit einer zertifikatübergreifenden Verteilungspunkterweiterung oder -eigenschaft.
CERT_FIND_PUBKEY_MD5_HASH	Datentyp des pvFindPara: CRYPT_HASH_BLOB Struktur. Suchen Sie ein Zertifikat, dessen öffentlicher SCHLÜSSEL mit MD5-Hash mit dem angegebenen Hash übereinstimmt.

Hinweis Es gibt alternative Formen des Werts von dwFindType, die eine Zeichenfolge in pvFindParaübergeben. Ein Formular verwendet eine Unicode-Zeichenfolge und die andere eine ASCII- Zeichenfolge. Werte, die in "_W" oder ohne Suffix enden, verwenden Unicode. Werte, die mit "_A" enden, verwenden ASCII-Zeichenfolgen.

[in] pvFindPara

Verweist auf ein Datenelement oder eine Struktur, die mit dwFindTypeverwendet wird.

[in] pPrevCertContext

Ein Zeiger auf die letzte CERT_CONTEXT Struktur, die von dieser Funktion zurückgegeben wird. Dieser Parameter muss NULL- für den ersten Aufruf der Funktion sein. Um nach aufeinander folgenden Zertifikaten zu suchen, die den Suchkriterien entsprechen, legen Sie pPrevCertContext auf den Zeiger fest, der vom vorherigen Aufruf der Funktion zurückgegeben wird. Diese Funktion gibt die CERT_CONTEXT frei, auf die durch nicht-NULL- Werte dieses Parameters verwiesen wird.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion einen Zeiger auf eine schreibgeschützte CERT_CONTEXT Struktur zurück.

Wenn die Funktion fehlschlägt und ein Zertifikat, das den Suchkriterien entspricht, nicht gefunden wird, wird der Rückgabewert NULL.

Ein nichtNULL-CERT_CONTEXT, das CertFindCertificateInStore- zurückgegeben wird, muss durch CertFreeCertificateContext- oder durch Übergeben als pPrevCertContext-Parameter für einen nachfolgenden Aufruf von CertFindCertificateInStorefreigegeben werden.

Rufen Sie für erweiterte Fehlerinformationen GetLastError-auf. Einige mögliche Fehlercodes folgen.

Rückgabecode	Beschreibung
CRYPT_E_NOT_FOUND	Es wurde kein Zertifikat gefunden, das den Suchkriterien entsprach. Dies kann passieren, wenn der Speicher leer ist oder das Ende der Liste des Stores erreicht ist.
E_INVALIDARG	Das Handle im hCertStore--Parameter ist nicht identisch mit dem im Zertifikat Kontext auf den pPrevCertContext Parameter verwiesen wurde oder ein ungültiger Wert im dwFindType-Parameter angegeben wurde.

Bemerkungen

Der dwFindFlags Parameter wird verwendet, um die Kriterien einiger Suchtypen zu ändern.

Der CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags Wert wird nur mit den werten CERT_FIND_SUBJECT_ATTR und CERT_FIND_ISSUER_ATTR für dwFindTypeverwendet. CERT_UNICODE_IS_RDN_ATTRS_FLAG muss festgelegt werden, wenn die CERT_RDN_ATTR Struktur, auf die pvFindPara verweist, mit Unicode-Zeichenfolgen initialisiert wurde. Bevor ein Vergleich durchgeführt wird, wird die abzugleichende Zeichenfolge mithilfe von X509_UNICODE_NAME konvertiert, um Unicode-Vergleiche bereitzustellen.

Die folgenden dwFindFlags Werte werden nur mit dem CERT_FIND_ENKEY_USAGE Wert für dwFindTypeverwendet:

CertDuplicateCertificateContext- kann aufgerufen werden, um ein Duplikat des zurückgegebenen Kontexts zu erstellen. Der zurückgegebene Kontext kann einem anderen Zertifikatspeicher mithilfe von CertAddCertificateContextToStore-hinzugefügt werden, oder ein Link zu diesem Zertifikatkontext kann einem Speicher hinzugefügt werden, der kein Sammlungsspeicher ist, indem CertAddCertificateLinkToStoreverwendet wird.

Der zurückgegebene Zeiger wird beim Übergeben als pPrevCertContext Parameter für einen nachfolgenden Aufruf der Funktion freigegeben. Andernfalls muss der Zeiger explizit durch Aufrufen CertFreeCertificateContextfreigegeben werden. Eine pPrevCertContext-, die nicht NULL- ist, wird immer von CertFindCertificateInStore mithilfe eines Aufrufs von CertFreeCertificateContextfreigegeben, auch wenn in der Funktion ein Fehler auftritt.

Beispiele

Das folgende Beispiel zeigt das Suchen eines Zertifikatkontexts im Zertifikatspeicher, das ein Suchkriterium erfüllt. Ein vollständiges Beispiel, das den Kontext für dieses Beispiel enthält, finden Sie unter Beispiel-C-Programm: Zertifikatspeichervorgänge.

Ein weiteres Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel C-Programm: Sammlungs- und Gleichgeordnete Zertifikatspeichervorgänge.

#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);

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [Desktop-Apps \| UWP-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform-	Fenster
Header-	wincrypt.h
Library	Crypt32.lib
DLL-	Crypt32.dll