CertFindCertificateInStore-Funktion (wincrypt.h)
Die CertFindCertificateInStore-Funktion findet den ersten oder nächsten Zertifikatkontext in einem Zertifikatspeicher , der einem suchkriterien entspricht, die vom dwFindType und dem zugehörigen pvFindPara eingerichtet wurden. Diese Funktion kann in einer Schleife verwendet werden, um alle Zertifikate in einem Zertifikatspeicher zu finden, 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 zu durchsuchenden Zertifikatspeichers .
[in] dwCertEncodingType
Gibt den Typ der verwendeten Codierung an. Sowohl der Zertifikat- als auch der Nachrichtencodierungstyp müssen durch Kombination mit einem bitweisen OR-Vorgang angegeben 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 unter Hinweise.
[in] dwFindType
Gibt den Suchtyp an. Der Suchtyp bestimmt den Datentyp, den Inhalt und die Verwendung von pvFindPara. Dieser Parameter kann einen der folgenden Werte annehmen.
| Wert | Bedeutung |
|---|---|
|
Datentyp von pvFindPara: NULL, nicht verwendet.
Es werden keine Suchkriterien verwendet. Gibt das nächste Zertifikat im Speicher zurück. Hinweis Die Reihenfolge des Zertifikatkontexts kann im Speicher nicht beibehalten werden.
Um auf ein bestimmtes Zertifikat zuzugreifen, müssen Sie die Zertifikate im Speicher durchlaufen.
|
|
Datentyp von pvFindPara: CERT_ID Struktur.
Suchen Sie das zertifikat, das durch den angegebenen CERT_ID identifiziert wurde. |
|
Datentyp von pvFindPara: CTL_USAGE Struktur.
Sucht nach einem Zertifikat mit einer szOID_ENHANCED_KEY_USAGE-Erweiterung oder einem CERT_CTL_PROP_ID, das dem pszUsageIdentifier-Member der CTL_USAGE-Struktur entspricht. |
|
Datentyp von pvFindPara: CERT_ENHKEY_USAGE Struktur.
Sucht nach einem Zertifikat im Speicher, das entweder über eine erweiterte Schlüsselverwendungserweiterung oder eine erweiterte Schlüsselverwendungseigenschaft und einen Verwendungsbezeichner verfügt, der dem cUsageIdentifier-Member in der CERT_ENHKEY_USAGE-Struktur entspricht. Ein Zertifikat verfügt über eine erweiterte Schlüsselverwendungserweiterung, wenn es über eine CERT_EXTENSION-Struktur verfügt, wobei das pszObjId-Element auf szOID_ENHANCED_KEY_USAGE festgelegt ist. Ein Zertifikat verfügt über eine erweiterte Schlüsselverwendungseigenschaft, wenn sein CERT_ENHKEY_USAGE_PROP_ID-Bezeichner festgelegt ist. Wenn CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG in dwFindFlags festgelegt ist, werden Auch Zertifikate ohne schlüsselverwendungserweiterung oder -eigenschaft übereinstimmen. Das Festlegen dieses Flags hat Vorrang vor dem Übergeben von NULL in pvFindPara. Wenn CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG festgelegt ist, erfolgt eine Übereinstimmung nur für die Schlüsselverwendungserweiterung. Informationen zu Flagänderungen an Suchkriterien finden Sie unter Hinweise. |
|
Datentyp von pvFindPara: CERT_CONTEXT Struktur.
Sucht nach einem Zertifikat, das genau mit dem angegebenen Zertifikatkontext übereinstimmt. |
|
Datentyp von pvFindPara: CRYPT_HASH_BLOB Struktur.
Sucht nach einem Zertifikat mit einem SHA1-Hash, der dem Hash in der CRYPT_HASH_BLOB-Struktur entspricht. |
|
Datentyp von pvFindPara: NULL, nicht 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 Cryptography API (CAPI)-Schlüssel oder ein CNG-Schlüssel sein. Hinweis Die Reihenfolge des Zertifikatkontexts kann im Speicher nicht beibehalten werden. Daher müssen Sie für den Zugriff auf ein bestimmtes Zertifikat alle Zertifikate durchlaufen.
|
|
Datentyp von pvFindPara: CERT_RDN Struktur.
Sucht nach einem Zertifikat mit angegebenen Ausstellerattributen, die attributen 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-Element von CERT_RDN_ATTRNULL ist, wird der Attributobjektbezeichner ignoriert. Wenn das dwValueType-Element von CERT_RDN_ATTR CERT_RDN_ANY_TYPE ist, wird der Werttyp ignoriert. Wenn das pbData-Element 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 unter Hinweise. Wenn diese Werte festgelegt werden, ist die Suche auf Zertifikate beschränkt, deren Codierungstyp dwCertEncodingType entspricht. |
|
Datentyp von 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 dwCertEncodingType übereinstimmen. |
|
Datentyp von pvFindPara: CERT_CONTEXT Struktur.
Sucht nach einem Zertifikat mit einem Antragsteller, der dem Aussteller in CERT_CONTEXT entspricht. Anstatt CertFindCertificateInStore mit diesem Wert zu verwenden, verwenden Sie die CertGetCertificateChain-Funktion . |
|
Datentyp von pvFindPara: Unicode-Zeichenfolge mit Null-Beendigung.
Sucht nach einem Zertifikat, das die angegebene Ausstellernamenzeichenfolge enthält. Das Ausstellermitglied des Zertifikats wird in eine Namenszeichenfolge des entsprechenden Typs konvertiert, wobei die entsprechende Form von CertNameToStr als CERT_SIMPLE_NAME_STR formatiert wird. Anschließend wird eine Unterzeichenfolgenübereinstimmung zwischen Groß- und Kleinschreibung durchgeführt. Wenn dieser Wert festgelegt ist, ist die Suche auf Zertifikate beschränkt, deren Codierungstyp dwCertEncodingType entspricht. Wenn die Teilzeichenfolgenübereinstimmung fehlschlägt und der Betreff ein 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übereinstimmung wird erneut ausgeführt. |
|
Datentyp von pvFindPara: CRYPT_HASH_BLOB Struktur.
Sucht nach einem Zertifikat mit einer CERT_KEY_IDENTIFIER_PROP_ID-Eigenschaft, die dem Schlüsselbezeichner in CRYPT_HASH_BLOB entspricht. |
|
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 pvFindPara entspricht. |
|
Datentyp von pvFindPara: CRYPT_HASH_BLOB Struktur.
Sucht nach einem Zertifikat mit einem MD5-Hash, der dem Hash in CRYPT_HASH_BLOB entspricht. |
|
Datentyp von pvFindPara: DWORD-Variable , die einen Eigenschaftsbezeichner enthält.
Sucht nach einem Zertifikat mit einer Eigenschaft, die dem Eigenschaftenbezeichner entspricht, der durch den DWORD-Wert in pvFindPara angegeben wird. |
|
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. |
|
Datentyp von pvFindPara: CRYPT_HASH_BLOB Struktur.
Sucht nach einem Zertifikat mit einem SHA1-Hash, der dem Hash in der CRYPT_HASH_BLOB-Struktur entspricht. |
|
Datentyp von pvFindPara: CRYPT_HASH_BLOB Struktur.
Sucht nach einem Zertifikat mit einem Signaturhash, der dem Signaturhash in der CRYPT_HASH_BLOB-Struktur entspricht. |
|
Datentyp von pvFindPara: CERT_RDN Struktur.
Sucht nach einem Zertifikat mit angegebenen Antragstellerattributen, die mit Attributen in der CERT_RDN-Struktur übereinstimmen. Wenn RDN-Werte festgelegt sind, vergleicht die Funktion Attribute des Antragstellers 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 Zertifikatsubjekts suchen. Wenn das pszObjId-Element von CERT_RDN_ATTRNULL ist, wird der Attributobjektbezeichner ignoriert. Wenn das dwValueType-Element von CERT_RDN_ATTR CERT_RDN_ANY_TYPE ist, wird der Werttyp ignoriert. Wenn das pbData-Element 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 unter Hinweise. Wenn diese Werte festgelegt werden, ist die Suche auf Zertifikate beschränkt, deren Codierungstyp dwCertEncodingType entspricht. |
|
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 entsprechen. |
|
Datentyp von 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 dwCertEncodingType entsprechen. |
|
Datentyp von pvFindPara: Unicode-Zeichenfolge mit Null-Beendigung.
Sucht nach einem Zertifikat, das die angegebene Antragstellernamenzeichenfolge enthält. Das Antragstellermember des Zertifikats wird in eine Namenszeichenfolge des entsprechenden Typs konvertiert, wobei die entsprechende Form von CertNameToStr als CERT_SIMPLE_NAME_STR formatiert wird. Anschließend wird eine Unterzeichenfolgenübereinstimmung zwischen Groß- und Kleinschreibung durchgeführt. Wenn dieser Wert festgelegt ist, ist die Suche auf Zertifikate beschränkt, deren Codierungstyp dwCertEncodingType entspricht. |
|
Datentyp von pvFindPara: Nicht verwendet.
Suchen Sie nach einem Zertifikat, das entweder über eine Zertifikatverteilungspunkterweiterung oder -eigenschaft verfügt. |
|
Datentyp von pvFindPara: CRYPT_HASH_BLOB Struktur.
Suchen Sie nach einem Zertifikat, dessen öffentlicher MD5-Hashschlüssel dem angegebenen Hash entspricht. |
[in] pvFindPara
Zeigt auf ein Datenelement oder eine Struktur, die mit dwFindType verwendet wird.
[in] pPrevCertContext
Ein Zeiger auf die letzte CERT_CONTEXT Struktur, die von dieser Funktion zurückgegeben wird. Dieser Parameter muss beim ersten Aufruf der Funktion NULL sein. Um nach aufeinander folgenden Zertifikaten zu suchen, die die Suchkriterien erfüllen, legen Sie pPrevCertContext auf den Zeiger fest, der vom vorherigen Aufruf der Funktion zurückgegeben wurde. Diese Funktion gibt die CERT_CONTEXT frei, auf die von Nicht-NULL-Werten 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 kein Zertifikat gefunden wird, das den Suchkriterien entspricht, ist der Rückgabewert NULL.
Ein nicht NULL-CERT_CONTEXT, den CertFindCertificateInStore zurückgibt, muss durch CertFreeCertificateContext oder durch Übergeben als pPrevCertContext-Parameter bei einem nachfolgenden Aufruf von CertFindCertificateInStore freigegeben werden.
Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Es folgen einige mögliche Fehlercodes.
| Rückgabecode | Beschreibung |
|---|---|
|
Es wurde kein Zertifikat gefunden, das den Suchkriterien entspricht. Dies kann passieren, wenn der Speicher leer ist oder das Ende der Liste des Geschäfts erreicht ist. |
|
Das Handle im hCertStore-Parameter ist nicht dasselbe wie im Zertifikatkontext , auf den der pPrevCertContext-Parameter verweist, oder ein ungültiger Wert wurde im dwFindType-Parameter angegeben. |
Hinweise
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 dwFindType verwendet. CERT_UNICODE_IS_RDN_ATTRS_FLAG muss festgelegt werden, wenn die CERT_RDN_ATTR Struktur, auf die von pvFindPara verwiesen wird, 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 dwFindType verwendet:
CertDuplicateCertificateContext kann aufgerufen werden, um ein Duplikat des zurückgegebenen Kontexts zu erstellen. Der zurückgegebene Kontext kann mithilfe von CertAddCertificateContextToStore einem anderen Zertifikatspeicher hinzugefügt werden, oder ein Link zu diesem Zertifikatkontext kann einem Speicher hinzugefügt werden, der kein Sammlungsspeicher ist, mithilfe von CertAddCertificateLinkToStore.
Der zurückgegebene Zeiger wird freigegeben, wenn er als pPrevCertContext-Parameter bei einem nachfolgenden Aufruf der Funktion übergeben wird. Andernfalls muss der Zeiger explizit durch Aufrufen von CertFreeCertificateContext freigegeben werden. Ein pPrevCertContext , der nicht NULL ist, wird immer von CertFindCertificateInStore mithilfe eines Aufrufs von CertFreeCertificateContext freigegeben, auch wenn ein Fehler in der Funktion vorliegt.
Beispiele
Das folgende Beispiel zeigt die Suche nach einem Zertifikatkontext im Zertifikatspeicher, der 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: Vorgänge zum Sammlungs- und Geschwisterzertifikatspeicher.
#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 |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | wincrypt.h |
| Bibliothek | Crypt32.lib |
| DLL | Crypt32.dll |
Weitere Informationen
CertAddCertificateContextToStore
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für