CertFindCTLInStore-Funktion (wincrypt.h)

Artikel
07/16/2024

Die CertFindCTLInStore-Funktion findet die erste oder nächste Zertifikatvertrauensliste (CTL) Kontext, die suchkriterien entsprechen, die vom dwFindType und den zugeordneten pvFindParafestgelegt wurden. Diese Funktion kann in einer Schleife verwendet werden, um alle CTL-Kontexte in einem Zertifikatspeicher zu finden, die den angegebenen Suchkriterien entsprechen.

Syntax

PCCTL_CONTEXT CertFindCTLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwMsgAndCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCTL_CONTEXT pPrevCtlContext
);

Parameter

[in] hCertStore

Handle des zu durchsuchenden Zertifikatspeichers.

[in] dwMsgAndCertEncodingType

Gibt den Typ der Codierung an, die für die CTL verwendet wird. Es ist immer akzeptabel, sowohl das Zertifikat als auch Nachrichtencodierungstypen anzugeben, die, 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

Dieser Parameter wird nur verwendet, wenn der dwFindType Parameter auf CTL_FIND_USAGE festgelegt ist.

[in] dwFindFlags

Kann festgelegt werden, wenn dwFindType- auf CTL_FIND_USAGE festgelegt ist. Ausführliche Informationen finden Sie in den Kommentaren unter CTL_FIND_USAGE:

[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
CTL_FIND_ANY	Datentyp des pvFindPara: NULL. Jede CTL ist eine Übereinstimmung.
CTL_FIND_SHA1_HASH	Datentyp von pvFindPara: CRYPT_HASH_BLOB. Es wird eine CTL mit einem Hash gefunden, der dem Hash in der CRYPT_HASH_BLOB-Struktur entspricht.
CTL_FIND_MD5_HASH	Datentyp von pvFindPara: CRYPT_HASH_BLOB. Es wird eine CTL mit einem Hash gefunden, der dem Hash in der CRYPT_HASH_BLOB-Struktur entspricht.
CTL_FIND_USAGE	Datentyp des pvFindPara: CTL_FIND_USAGE_PARA. Jede CTL wird gefunden, die einen Verwendungsbezeichner, Listenbezeichner oder Signierer enthält, der dem Verwendungsbezeichner, listenbezeichner oder signierer in der CTL_FIND_USAGE_PARA-Struktur entspricht. Wenn das cUsageIdentifier- Mitglied SubjectUsage Größe hat, ist jede CTL eine Übereinstimmung. Wenn das cbData Mitglied von ListIdentifier Element null ist, ist jeder Listenbezeichner eine Übereinstimmung. Wenn das cbData Mitglied von ListIdentifier CTL_FIND_NO_LIST_ID_CBDATA ist, ist nur eine CTL ohne Listenbezeichner eine Übereinstimmung. Wenn das pSigner-Element in der CTL_FIND_USAGE_PARA-Struktur NULL-ist, ist jeder CTL-Signer eine Übereinstimmung, und nur der Issuer und SerialNumber Member in der pSigner-CERT_INFO-Struktur werden verwendet. Wenn pSigner- CTL_FIND_NO_SIGNER_PTR ist, ist nur eine CTL ohne Signierer eine Übereinstimmung.
CTL_FIND_SAME_USAGE_FLAG	Datentyp des pvFindPara: CTL_FIND_USAGE_PARA. Es werden nur CTLs mit genau den gleichen Verwendungsbezeichnern abgeglichen. CTLs mit zusätzlichen Verwendungsbezeichnern stimmen nicht überein. Wenn beispielsweise nur "1.2.3" in der CTL_FIND_USAGE_PARA-Struktur angegeben ist, darf die CTL nur "1.2.3" und keine zusätzlichen Verwendungsbezeichner enthalten.
CTL_FIND_EXISTING	Datentyp von pvFindPara: PCCTL_CONTEXT. Sucht nach der nächsten CRL, die eine genaue Übereinstimmung des CTL_CONTEXTist.
CTL_FIND_SUBJECT	Datentyp von pvFindPara: CTL_FIND_SUBJECT_PARA. Es wird eine CTL mit dem angegebenen Betreff gefunden. CertFindSubjectInCTL- kann aufgerufen werden, um einen Zeiger auf den Eintrag des Betreffs in der CTL abzurufen. Das pUsagePara Mitglied in CTL_FIND_SUBJECT_PARA kann optional festgelegt werden, um den oben beschriebenen Abgleich unter CTL_FIND_USAGE zu aktivieren.

[in] pvFindPara

Ein Zeiger auf den Suchwert, der dem dwFindType Parameter zugeordnet ist.

[in] pPrevCtlContext

Ein Zeiger auf die letzte CTL_CONTEXT, die von dieser Funktion zurückgegeben wird. Es muss NULL- sein, um die erste CTL im Store abzurufen. Aufeinander folgende CTLs werden abgerufen, indem sie pPrevCtlContext- auf den Zeiger auf die CTL_CONTEXT festlegen, die von einem vorherigen Funktionsaufruf zurückgegeben wird. Alle Zertifikate, die die Suchkriterien nicht erfüllen oder zuvor von CertDeleteCTLFromStore gelöscht wurden, werden übersprungen. Diese Funktion gibt die CTL_CONTEXT frei, auf die durch nichtNULL- Werte dieses Parameters verwiesen wird.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Zeiger auf einen schreibgeschützten CTL-Kontext.

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

Rückgabecode	Beschreibung
CRYPT_E_NOT_FOUND	Entweder wurden keine CTLs im Speicher gefunden, keine CTL wurde gefunden, die den Suchkriterien entsprechen, oder die Funktion hat das Ende der Liste des Stores erreicht.
E_INVALIDARG	Das Handle im hCertStore--Parameter entspricht nicht dem im CTL-Kontext, auf den der pPrevCtlContext-Parameter verweist, oder ein ungültiger Wert wurde im dwFindType-Parameter angegeben.

Bemerkungen

Ein zurückgegebener Zeiger wird beim Übergeben als pPrevCtlContext- bei einem nachfolgenden Aufruf der Funktion freigegeben. Andernfalls muss der Zeiger durch Aufrufen CertFreeCTLContextfreigegeben werden. Ein nichtNULL-pPrevCtlContext an die Funktion übergeben wird, wird immer mit einem Aufruf von CertFreeCTLContextfreigegeben, auch wenn die Funktion einen Fehler generiert.

CertDuplicateCTLContext- kann aufgerufen werden, um ein Duplikat des zurückgegebenen Kontexts zu erstellen. Der zurückgegebene CTL-Kontext kann einem anderen Zertifikatspeicher mithilfe CertAddCTLContextToStore-hinzugefügt werden, oder ein Link zu diesem CTL-Kontext kann mithilfe CertAddCTLLinkToStoreeinem Nichtsammlungsspeicher hinzugefügt werden. Wenn eine CTL, die den Suchkriterien entspricht, nicht gefunden wird, wird NULL- zurückgegeben.

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