CertFindCTLInStore-Funktion (wincrypt.h)

Artikel
08/27/2023

Die CertFindCTLInStore-Funktion sucht den ersten oder nächsten CTL-Kontext (Certificate Trust List), der suchkriterien entspricht, die vom dwFindType und dem zugehörigen pvFindPara festgelegt 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 Codierungstyp an, der für die CTL verwendet wird. Es ist immer akzeptabel, sowohl den Zertifikat- als auch den Nachrichtencodierungstyp anzugeben, indem sie mit einem bitweisen OR-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 Typ der durchgeführten Suche an. Der Suchtyp bestimmt den Datentyp, den Inhalt und die Verwendung von pvFindPara. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
CTL_FIND_ANY	Datentyp von pvFindPara: NULL. Jede CTL ist eine Übereinstimmung.
CTL_FIND_SHA1_HASH	Datentyp von pvFindPara: CRYPT_HASH_BLOB. Eine CTL mit einem Hash, der mit dem Hash in der CRYPT_HASH_BLOB-Struktur übereinstimmt, wird gefunden.
CTL_FIND_MD5_HASH	Datentyp von pvFindPara: CRYPT_HASH_BLOB. Eine CTL mit einem Hash, der mit dem Hash in der CRYPT_HASH_BLOB-Struktur übereinstimmt, wird gefunden.
CTL_FIND_USAGE	Datentyp von pvFindPara: CTL_FIND_USAGE_PARA. Es wird eine beliebige CTL gefunden, die über einen Nutzungsbezeichner, listenbezeichner oder Signierer verfügt, der dem Nutzungsbezeichner, Listenbezeichner oder Signierer in der CTL_FIND_USAGE_PARA-Struktur entspricht. Wenn das cUsageIdentifier-Element die SubjectUsage-Größe aufweist, ist jede CTL eine Übereinstimmung. Wenn das cbData-Element des ListIdentifier-Elements null ist, ist jeder Listenbezeichner eine Übereinstimmung. Wenn das cbData-Element 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-StrukturNULL ist, ist jeder CTL-Signierer eine Übereinstimmung, und nur die Member Issuer und SerialNumber 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 von pvFindPara: CTL_FIND_USAGE_PARA. Es werden nur CTLs mit genau den gleichen Nutzungsbezeichnern abgeglichen. CTLs mit zusätzlichen Nutzungsbezeichnern werden nicht abgeglichen. Wenn beispielsweise nur "1.2.3" in der CTL_FIND_USAGE_PARA-Struktur angegeben ist, darf die CTL für eine Übereinstimmung nur "1.2.3" und keine zusätzlichen Verwendungsbezeichner enthalten.
CTL_FIND_EXISTING	Datentyp von pvFindPara: PCCTL_CONTEXT. Sucht nach der nächsten Zertifikatsperrliste, die genau mit der CTL_CONTEXT übereinstimmt.
CTL_FIND_SUBJECT	Datentyp von pvFindPara: CTL_FIND_SUBJECT_PARA. Eine CTL mit dem angegebenen Betreff wird gefunden. CertFindSubjectInCTL kann aufgerufen werden, um einen Zeiger auf den Eintrag des Antragstellers in der CTL abzurufen. Der pUsagePara-Member in CTL_FIND_SUBJECT_PARA kann optional so festgelegt werden, dass der unter CTL_FIND_USAGE beschriebene Abgleich aktiviert wird.

[in] pvFindPara

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

[in] pPrevCtlContext

Ein Zeiger auf den letzten CTL_CONTEXT , der von dieser Funktion zurückgegeben wird. Es muss NULL sein, um die erste CTL im Speicher zu erhalten. Aufeinander folgende CTLs werden abgerufen, indem pPrevCtlContext auf den Zeiger auf die von einem vorherigen Funktionsaufruf zurückgegebene CTL_CONTEXT festgelegt wird. Alle Zertifikate, die nicht den Suchkriterien entsprechen oder die zuvor von CertDeleteCTLFromStore gelöscht wurden, werden übersprungen. Diese Funktion gibt die CTL_CONTEXT frei, auf die nicht NULL-Werte dieses Parameters verwiesen werden.

Rückgabewert

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

Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten. Es folgen einige mögliche Fehlercodes.

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

Hinweise

Ein zurückgegebener Zeiger wird freigegeben, wenn er bei einem nachfolgenden Aufruf der Funktion als pPrevCtlContext übergeben wird. Andernfalls muss der Zeiger durch Aufrufen von CertFreeCTLContext freigegeben werden. Ein an die Funktion übergebener pPrevCtlContext ungleich NULL wird immer mit einem Aufruf von CertFreeCTLContext freigegeben, 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 mithilfe von CertAddCTLContextToStore einem anderen Zertifikatspeicher hinzugefügt werden, oder ein Link zu diesem CTL-Kontext kann einem Nichtsammlungsspeicher mithilfe von CertAddCTLLinkToStore hinzugefügt werden. Wenn keine CTL gefunden wird, die den Suchkriterien entspricht, wird NULL zurückgegeben.

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