CertFindChainInStore-Funktion (wincrypt.h)

Artikel
08/27/2023

Die CertFindChainInStore-Funktion sucht das erste oder nächste Zertifikat in einem Speicher , das die angegebenen Kriterien erfüllt. Anschließend wird ein Zertifikatkettenkontext für dieses Zertifikat erstellt und überprüft. Das gefundene Zertifikat, für das die Kette erstellt wird, wird gemäß den Kriterien ausgewählt, die von den Parametern dwFindFlags, dwFindType und pvFindPara festgelegt wurden. 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, der 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 Bezeichner des Nachrichtencodierungstyps , der im hohen WORD dieses Werts enthalten ist, wird von dieser Funktion ignoriert.

Bei diesem Parameter kann es sich um den folgenden derzeit definierten Zertifikatcodierungstyp handeln.

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 dwFindTypeCERT_CHAIN_FIND_BY_ISSUER enthält.

Wert	Bedeutung
CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG	Vergleicht den öffentlichen Schlüssel im Zertifikat mit dem öffentlichen Schlüssel des Kryptografiedienstanbieters. Dieser Vergleich ist die letzte Überprüfung der Kette, wenn sie erstellt wird. Da das hCryptProv-Mitglied eines Ausstellers einen privaten Schlüssel enthält, muss er während dieses Vorgangs möglicherweise mehrmals überprüft werden. Um diese Überprüfung zu erleichtern, kann der dwAcquirePrivateKeyFlags-Member in der CERT_CHAIN_FIND_BY_ISSUER_PARA-Struktur festgelegt werden, um die Zwischenspeicherung dieses hCryptProv-Elements zu ermöglichen.
CERT_CHAIN_FIND_BY_ISSUER_COMPLEX_CHAIN_FLAG	Standardmäßig wird nur die erste einfache Kette auf Übereinstimmungen des Ausstellernamens überprüft. Wenn dieses Flag festgelegt ist, wird der Standardwert überschrieben, und nachfolgende einfache Ketten werden ebenfalls auf Übereinstimmungen mit dem Ausstellernamen überprüft.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_FLAG	Verbessert die Leistung dieser Funktion, indem sie dazu führt, dass nur die zwischengespeicherten Systemspeicher (Root, My, Ca, Trust) nach Ausstellerzertifikaten gesucht werden. Wenn dieses Flag nicht festgelegt ist, durchsucht die Funktion die zwischengespeicherten Systemspeicher und den Speicher, der durch den hCertStore-Parameter dargestellt wird.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_URL_FLAG	Es wird nur der URL-Cache 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 nicht überprüft, ob das Zertifikat über einen zugeordneten privaten Schlüssel verfügt.

[in] dwFindType

Bestimmt, welche Kriterien verwendet werden sollen, um ein Zertifikat im Speicher zu finden.

Dieser Parameter kann der folgende derzeit definierte Wert sein.

CERT_CHAIN_FIND_BY_ISSUER

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

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

Diese Funktion vergleicht die namensbasierten BLOBs , die in der pvFindPara-Struktur übergeben werden, an eine beliebige Zertifizierungsstelle (CA) in der Kette, nicht nur an die 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 ausstellende Zertifizierungsstellen vorhanden sind, von denen eine widerrufen wird, ist es möglich, dass diese Funktion die widerrufene Kette zurückgibt. Wenn die Anwendung dann selbst durch Aufrufe der CertVerifyRevocation-Funktion auf Sperrung überprüft und die Kette als ungeeignet erachtet, 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ängen 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 wurde. Die Suche wird von diesem Zertifikat aus gestartet. Für den ersten Aufruf dieser Funktion muss dieser Parameter NULL sein. Bei nachfolgenden Aufrufen ist dies der Zeiger, der vom vorherigen Aufruf der Funktion zurückgegeben wurde. Wenn dieser Parameter nicht NULL ist, gibt diese Funktion diese Struktur frei.

Rückgabewert

Wenn der Kontext der ersten oder nächsten Kette 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 bei einem nachfolgenden Aufruf dieser Funktion als pPrevChainContext-Parameter übergeben wird. Andernfalls muss die CERT_CHAIN_CONTEXT-Struktur explizit durch Aufrufen der CertFreeCertificateChain-Funktion freigegeben werden.

Hinweise

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

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	wincrypt.h
Bibliothek	Crypt32.lib
DLL	Crypt32.dll