CertFindChainInStore-Funktion (wincrypt.h)

Artikel
07/16/2024

Die funktion CertFindChainInStore findet das erste oder nächste Zertifikat in einem speicher, das den angegebenen Kriterien entspricht. Anschließend wird ein Zertifikatkettenkontext für dieses Zertifikat erstellt und überprüft. Das gefundene Zertifikat, für das die Kette erstellt wird, wird nach Kriterien ausgewählt, die durch die dwFindFlags, dwFindTypeund pvFindPara Parameter festgelegt werden. Diese Funktion kann in einer Schleife verwendet werden, um alle Zertifikate in einem Zertifikatspeicher zu finden, die den angegebenen Suchkriterien entsprechen, und um einen Zertifikatkettenkontext für jedes gefundene Zertifikat zu erstellen.

Syntax

PCCERT_CHAIN_CONTEXT CertFindChainInStore(
  [in] HCERTSTORE           hCertStore,
  [in] DWORD                dwCertEncodingType,
  [in] DWORD                dwFindFlags,
  [in] DWORD                dwFindType,
  [in] const void           *pvFindPara,
  [in] PCCERT_CHAIN_CONTEXT pPrevChainContext
);

Parameter

[in] hCertStore

Das Handle des Speichers, auf dem nach einem Zertifikat gesucht werden soll, auf dem eine Kette erstellt wird. Dieses Handle wird als zusätzlicher Speicher an die CertGetCertificateChain Funktion übergeben, während die Kette erstellt wird.

[in] dwCertEncodingType

Der Zertifikatcodierungstyp, der zum Codieren des Speichers verwendet wurde. Der Nachrichtencodierungstyp Bezeichners, der in der hohen WORD- dieses Werts enthalten ist, wird von dieser Funktion ignoriert.

Dieser Parameter kann der folgende aktuell definierte Zertifikatcodierungstyp sein.

Wert	Bedeutung
X509_ASN_ENCODING 1 (0x1)	Gibt die X.509-Zertifikatcodierung an.

[in] dwFindFlags

Enthält zusätzliche Optionen für die Suche. Die möglichen Werte für diesen Parameter hängen vom Wert des dwFindType-Parameters ab.

Dieser Parameter kann null oder eine Kombination aus einem oder mehreren der folgenden Werte enthalten, wenn dwFindType-CERT_CHAIN_FIND_BY_ISSUERenthält.

Wert	Bedeutung
CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG	Vergleicht den öffentlichen Schlüssel im Zertifikat mit demöffentlichen Schlüssel des kryptografischen Dienstanbieters. Dieser Vergleich ist die letzte Prüfung auf der Kette, wenn sie erstellt wird. Da das hCryptProv Mitglied eines Ausstellers einen privaten Schlüssel enthält, muss er während dieses Prozesses möglicherweise mehrmals überprüft werden; um diese Überprüfung zu erleichtern, kann das dwAcquirePrivateKeyFlags Member in der CERT_CHAIN_FIND_BY_ISSUER_PARA-Struktur festgelegt werden, um das Zwischenspeichern dieses hCryptProv-zu ermöglichen.
CERT_CHAIN_FIND_BY_ISSUER_COMPLEX_CHAIN_FLAG	Standardmäßig wird nur die erste einfache Kette auf Ausstellernamen-Übereinstimmungen überprüft. Bei diesem Kennzeichensatz wird der Standardwert überschrieben, und nachfolgende einfache Ketten werden auch auf Ausstellernamenübereinstimmungen überprüft.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_FLAG	Verbessert die Leistung dieser Funktion, indem sie nur die zwischengespeicherten Systemspeicher (Root, My, Ca, Trust) durchsuchen, um Ausstellerzertifikate zu finden. Wenn dieses Flag nicht festgelegt ist, durchsucht die Funktion die zwischengespeicherten Systemspeicher und den durch den hCertStore Parameter dargestellten Speicher.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_URL_FLAG	Nur der URL-Cache wird durchsucht. Das Internet wird nicht durchsucht.
CERT_CHAIN_FIND_BY_ISSUER_LOCAL_MACHINE_FLAG	Öffnet nur die Zertifikatspeicher des lokalen Computers. Die Zertifikatspeicher des aktuellen Benutzers werden nicht geöffnet.
CERT_CHAIN_FIND_BY_ISSUER_NO_KEY_FLAG	Es wird keine Überprüfung durchgeführt, um festzustellen, ob das Zertifikat über einen zugeordneten privaten Schlüssel verfügt.

[in] dwFindType

Bestimmt, welche Kriterien zum Suchen eines Zertifikats im Speicher verwendet werden sollen.

Dieser Parameter kann der folgende aktuell definierte Wert sein.

CERT_CHAIN_FIND_BY_ISSUER

Sucht das Zertifikat basierend auf dem Namen des Ausstellers. Der pvFindPara Parameter ist ein Zeiger auf eine CERT_CHAIN_FIND_BY_ISSUER_PARA Struktur, die Elemente enthält, die die Suche ändern.

Die Zertifikatkette wird für ein Zertifikat mit einem verfügbaren privaten Schlüsselerstellt. Standardmäßig werden nur die Aussteller in der ersten einfachen Kette in einer Ausstellernamenvergleichung verglichen. Wenn dieses Kennzeichen festgelegt ist, werden alle Ketten auf ein Ausstellerzertifikat überprüft, das einem Satz von Ausstellernamen entspricht.

Diese Funktion vergleicht den Namen BLOBs, die in der pvFindPara- Struktur übergeben wurden, mit allen Zertifizierungsstelle (CA) in der Kette, nicht nur der Zertifizierungsstelle im Stammzertifikat.

Diese Funktion führt keine Sperrüberprüfungen durch.

Wenn pPrevChainContext- nicht NULL-ist, gibt diese Funktion bei jedem Aufruf der Funktion eine Kette für ein anderes Zertifikat zurück. Wenn nur ein geeignetes Zertifikat vorhanden ist, aber zwei übereinstimmende Zertifizierungsstellen vorhanden sind, von denen einer widerrufen wird, ist es möglich, dass diese Funktion die widerrufene Kette zurückgibt. Wenn die Anwendung dann über Aufrufe der CertVerifyRevocation-Funktion auf sperrung überprüft und die Kette nicht geeignet findet, gibt ein zusätzlicher Aufruf der CertFindChainInStore-Funktion keine Kette zurück, die dasselbe Zertifikat von der gültigen Zertifizierungsstelle enthält. Stattdessen wird eine völlig andere Kette mit einem anderen Zertifikat oder NULL-zurückgegeben, wenn keine solche Kette gefunden werden kann.

[in] pvFindPara

Ein Zeiger, der zusätzliche Suchkriterien enthält. Der Typ und das Format der Daten, auf die dieser Parameter verweist, hängt vom Wert des dwFindType-Parameters ab.

[in] pPrevChainContext

Ein Zeiger auf eine CERT_CHAIN_CONTEXT Struktur, die von einem vorherigen Aufruf dieser Funktion zurückgegeben wird. Die Suche wird mit diesem Zertifikat begonnen. Für den ersten Aufruf dieser Funktion muss dieser Parameter NULL-sein. Bei nachfolgenden Aufrufen handelt es sich um den Zeiger, der vom vorherigen Aufruf der Funktion zurückgegeben wird. Wenn dieser Parameter nicht NULL-ist, wird diese Struktur durch diese Funktion freigegeben.

Rückgabewert

Wenn der erste oder nächste Kettenkontext nicht erstellt wird, wird NULL- zurückgegeben. Andernfalls wird ein Zeiger auf eine schreibgeschützte CERT_CHAIN_CONTEXT Struktur zurückgegeben. Die CERT_CHAIN_CONTEXT Struktur wird freigegeben, wenn sie als pPrevChainContext- Parameter für einen nachfolgenden Aufruf dieser Funktion übergeben wird. Andernfalls muss die CERT_CHAIN_CONTEXT-Struktur explizit durch Aufrufen der CertFreeCertificateChain--Funktion freigegeben werden.

Bemerkungen

Der pPrevChainContext Parameter muss NULL- für den ersten Aufruf sein, um den Kettenkontext zu erstellen. Um den nächsten Kettenkontext zu erstellen, wird die pPrevChainContext- auf die CERT_CHAIN_CONTEXT Struktur festgelegt, die von einem vorherigen Aufruf zurückgegeben wird. Wenn pPrevChainContext- nicht NULL-ist, wird die Struktur immer von dieser Funktion mithilfe der CertFreeCertificateChain Funktion freigegeben, auch wenn ein Fehler auftritt.

Anforderungen

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