CertVerifyCertificateChainPolicy-Funktion (wincrypt.h)

Artikel
08/15/2024

Die CertVerifyCertificateChainPolicy--Funktion überprüft eine Zertifikatkette, um ihre Gültigkeit zu überprüfen, einschließlich der Einhaltung aller angegebenen Gültigkeitsrichtlinienkriterien.

Syntax

BOOL CertVerifyCertificateChainPolicy(
  [in]      LPCSTR                    pszPolicyOID,
  [in]      PCCERT_CHAIN_CONTEXT      pChainContext,
  [in]      PCERT_CHAIN_POLICY_PARA   pPolicyPara,
  [in, out] PCERT_CHAIN_POLICY_STATUS pPolicyStatus
);

Parameter

[in] pszPolicyOID

Die aktuellen vordefinierten Verkettenrichtlinienstrukturen sind in der folgenden Tabelle aufgeführt.

Wert	Bedeutung
CERT_CHAIN_POLICY_BASE (LPCSTR) 1	Implementiert die Überprüfungsprüfungen der Basiskettenrichtlinie. Das dwFlags Mitglied der Struktur, auf das durch pPolicyPara- verwiesen wird, kann festgelegt werden, um das Standardverhalten der Richtlinienüberprüfung zu ändern.
CERT_CHAIN_POLICY_AUTHENTICODE (LPCSTR) 2	Implementiert die Überprüfungsprüfungen der Authenticode-Kette. Das pvExtraPolicyPara- Element der Struktur, auf das durch pPolicyPara- verwiesen wird, kann auf eine AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_PARA Struktur verweisen. Das pvExtraPolicyStatus- Element der Struktur, auf das pPolicyStatus- verweist, kann auf eine AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_STATUS Struktur verweisen.
CERT_CHAIN_POLICY_AUTHENTICODE_TS (LPCSTR) 3	Implementiert Die Überprüfungsprüfungen der Authenticode-Zeitstempelkette. Das pvExtraPolicyPara Element der Datenstruktur, auf das pPolicyPara- verweist, kann auf eine AUTHENTICODE_TS_EXTRA_CERT_CHAIN_POLICY_PARA Struktur verweisen. Das pvExtraPolicyStatus- Mitglied der Datenstruktur, auf das von pPolicyStatus verwiesen wird, wird nicht verwendet und muss auf `NULL`festgelegt werden.
CERT_CHAIN_POLICY_SSL (LPCSTR) 4	Implementiert die Überprüfung der SSL-Client-/Serverkette-Richtlinienüberprüfung. Das pvExtraPolicyPara Member in der Datenstruktur, auf das von pPolicyPara verwiesen wird, kann so festgelegt werden, dass sie auf eine SSL_EXTRA_CERT_CHAIN_POLICY_PARA Struktur verweist, die mit zusätzlichen Richtlinienkriterien initialisiert wurde. Hinweis: Um zwischen Server- und Clientautorisierungszertifikaten zu unterscheiden, sollte der Aufruf der CertGetCertificateChain--Funktion, um den Kettenkontext abzurufen, den Zertifikattyp angeben, indem die erwartete Verwendung festgelegt wird. Legen Sie die erwartete Verwendung fest, indem Sie den RequestedUsage Member der CERT_CHAIN_PARA Struktur festlegen, die im pChainPara Eingabeparameter der CertGetCertificateChain--Funktion übergeben wird.
CERT_CHAIN_POLICY_BASIC_CONSTRAINTS (LPCSTR) 5	Implementiert die Grundlegende Einschränkungskettenrichtlinie. Durchlaufen Sie alle Zertifikate in der Kettesprüfung für eine szOID_BASIC_CONSTRAINTS oder eine szOID_BASIC_CONSTRAINTS2 Erweiterung. Wenn keine Erweiterung vorhanden ist, wird davon ausgegangen, dass das Zertifikat über eine gültige Richtlinie verfügt. Andernfalls wird für das erste Zertifikatelement überprüft, ob es mit dem erwarteten CA_FLAG oder END_ENTITY_FLAG übereinstimmt, das im dwFlags Member der CERT_CHAIN_POLICY_PARA Struktur durch den pPolicyPara Parameter verweist. Wenn keines oder beide Flags festgelegt sind, kann das erste Element entweder eine Zertifizierungsstelle oder END_ENTITY sein. Alle anderen Elemente müssen eine Zertifizierungsstelle (CA) sein. Wenn pathLenConstraint in der Erweiterung vorhanden ist, wird sie überprüft. Die ersten Elemente in den verbleibenden einfachen Ketten (d. h. die Zertifikate, die zum Signieren der CTL verwendet werden) werden als END_ENTITY überprüft. Wenn diese Überprüfung fehlschlägt, wird dwError- auf TRUST_E_BASIC_CONSTRAINTS festgelegt.
CERT_CHAIN_POLICY_NT_AUTH (LPCSTR) 6	Implementiert die Windows NT-Authentifizierungsketterichtlinie, die aus drei unterschiedlichen Kettenüberprüfungen in der folgenden Reihenfolge besteht: - CERT_CHAIN_POLICY_BASE: Implementiert die Überprüfungsprüfungen der Basiskettenrichtlinie. Die LOWORD von dwFlags- kann in pPolicyPara- festgelegt werden, um das Standardverhalten der Richtlinienüberprüfung zu ändern. Weitere Informationen finden Sie unter CERT_CHAIN_POLICY_BASE. - CERT_CHAIN_POLICY_BASIC_CONSTRAINTS: Implementiert die grundlegende Einschränkungskettenrichtlinie. Das HIWORD von dwFlags- kann festgelegt werden, um anzugeben, ob das erste Element entweder eine Zertifizierungsstelle oder END_ENTITY sein muss. Weitere Informationen finden Sie unter CERT_CHAIN_POLICY_BASIC_CONSTRAINTS. – Überprüft, ob das zweite Element in der Kette, die Zertifizierungsstelle, die das Endzertifikat ausgestellt hat, eine vertrauenswürdige Zertifizierungsstelle für die Windows NT-Authentifizierung ist. Eine Zertifizierungsstelle gilt als vertrauenswürdig, wenn sie im Registrierungsspeicher des "NTAuth"-Systems vorhanden ist, der sich im CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE Speicherort befindet. Wenn diese Überprüfung fehlschlägt, ist die Zertifizierungsstelle nicht vertrauenswürdig, und dwError- auf CERT_E_UNTRUSTEDCA festgelegt ist. Wenn CERT_PROT_ROOT_DISABLE_NT_AUTH_REQUIRED_FLAG im Flags- Wert der HKEY_LOCAL_MACHINE Richtlinie ProtectedRoots-Unterschlüssel festgelegt wird, der durch CERT_PROT_ROOT_FLAGS_REGPATH definiert wird und die obige Überprüfung fehlschlägt, wird die Kette auf CERT_TRUST_HAS_VALID_NAME_CONSTRAINTS in dwInfoStatus-festgelegt. Dies wird festgelegt, wenn eine gültige Namenseinschränkung für alle Namespaces einschließlich UPN vorhanden ist. Wenn die Kette diesen Informationsstatus nicht festgelegt hat, wird dwError- auf CERT_E_UNTRUSTEDCA festgelegt.
CERT_CHAIN_POLICY_MICROSOFT_ROOT (LPCSTR) 7	Überprüft das letzte Element der ersten einfachen Kette für einen öffentlichen Microsoft-Stammschlüssel. Wenn dieses Element keinen öffentlichen Microsoft-Stammschlüssel enthält, wird der dwError Member der CERT_CHAIN_POLICY_STATUS Struktur, auf die der pPolicyStatus-Parameter verweist, auf CERT_E_UNTRUSTEDROOTfestgelegt. Das dwFlags Mitglied der CERT_CHAIN_POLICY_PARA Struktur, auf die der pPolicyStatus--Parameter verweist, kann das MICROSOFT_ROOT_CERT_CHAIN_POLICY_CHECK_APPLICATION_ROOT_FLAG-Flag enthalten, wodurch diese Funktion stattdessen auf den Microsoft-Anwendungsstamm "Microsoft-Stammzertifizierungsstelle 2011" überprüft. Das dwFlags- Mitglied der CERT_CHAIN_POLICY_PARA Struktur, auf die der pPolicyPara--Parameter verweist, kann das MICROSOFT_ROOT_CERT_CHAIN_POLICY_ENABLE_TEST_ROOT_FLAG Flag enthalten, wodurch diese Funktion auch auf die Microsoft-Testwurzeln überprüft wird. Hinweis: Diese Richtlinie Objektbezeichner (OID) führt keine Richtlinienüberprüfungen allein durch, sie ist in Verbindung mit anderen Richtlinien zu verwenden.
CERT_CHAIN_POLICY_EV (LPCSTR) 8	Gibt an, dass die erweiterte Überprüfung von Zertifikaten ausgeführt wird. Windows Server 2008, Windows Vista, Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
CERT_CHAIN_POLICY_SSL_F12 (LPCSTR) 9	Überprüft, ob Zertifikate in der Kette schwache Krypto aufweisen oder ob die Compliance von Stammzertifikaten von Drittanbietern besteht und eine Fehlerzeichenfolge bereitstellt. Das pvExtraPolicyStatus- Mitglied der CERT_CHAIN_POLICY_STATUS Struktur, auf die der pPolicyStatus Parameter verweist, muss auf SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUSverweisen, das mit den Ergebnissen der schwachen Krypto- und Stammprogramm-Complianceprüfungen aktualisiert wird. Vor dem Aufrufen muss das cbSize Member der CERT_CHAIN_POLICY_STATUS Struktur, auf das durch den pPolicyStatus-Parameter-Parameter verwiesen wird, auf einen Wert festgelegt werden, der größer oder gleich "sizeof(SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS) ist. Das dwError- Mitglied in CERT_CHAIN_POLICY_STATUS Struktur, auf das der pPolicyStatus-Parameter verweist, wird auf TRUST_E_CERT_SIGNATURE für potenzielle schwache Krypto festgelegt und auf CERT_E_UNTRUSTEDROOT für Drittanbieterwurzeln festgelegt, die nicht mit dem Microsoft Root-Programm konform sind. Windows 10, Version 1607, Windows Server 2016, Windows 10, Version 1511 mit KB3172985, Windows 10 RTM mit KB3163912, Windows 8.1 und Windows Server 2012 R2 mit KB3163912 und Windows 7 mit SP1 und Windows Server 2008 R2 SP1 mit KB3161029

[in] pChainContext

Ein Zeiger auf eine CERT_CHAIN_CONTEXT Struktur, die eine zu überprüfende Kette enthält.

[in] pPolicyPara

Ein Zeiger auf eine CERT_CHAIN_POLICY_PARA Struktur, die die Richtlinienüberprüfungskriterien für die Kette bereitstellt. Das dwFlags Mitglied dieser Struktur kann festgelegt werden, um das Standardverhalten der Richtlinienüberprüfung zu ändern.

Darüber hinaus können richtlinienspezifische Parameter auch im pvExtraPolicyPara Mitglied der Struktur übergeben werden.

[in, out] pPolicyStatus

Ein Zeiger auf eine CERT_CHAIN_POLICY_STATUS Struktur, in der Statusinformationen in der Kette zurückgegeben werden. OID-spezifischer Extrastatus kann im pvExtraPolicyStatus Mitglied dieser Struktur zurückgegeben werden.

Rückgabewert

Der Rückgabewert gibt an, ob die Funktion nach der Richtlinie suchen konnte. Sie gibt nicht an, ob die Richtlinienüberprüfung fehlgeschlagen oder bestanden wurde.

Wenn die Kette für die angegebene Richtlinie überprüft werden kann, wird TRUE zurückgegeben, und das dwError- Mitglied der pPolicyStatus- wird aktualisiert. Ein dwError- von 0 (ERROR_SUCCESS oder S_OK) gibt an, dass die Kette der angegebenen Richtlinie entspricht.

Wenn die Kette nicht überprüft werden kann, ist der Rückgabewert TRUE, und Sie müssen den pPolicyStatus Parameter für den tatsächlichen Fehler überprüfen.

Ein Wert von FALSE gibt an, dass die Funktion nicht nach der Richtlinie suchen konnte.

Bemerkungen

Ein dwError- Element der CERT_CHAIN_POLICY_STATUS-Struktur, auf das durch pPolicyStatus- verwiesen wird, kann auf ein einzelnes Kettenelement, auf eine einfache Kette oder auf einen gesamten Kettenkontext angewendet werden. Wenn dwError- für den gesamten Kettenkontext gilt, werden sowohl die lChainIndex- als auch die lElementIndex Member der CERT_CHAIN_POLICY_STATUS-Struktur auf –1festgelegt. Wenn dwError- auf eine vollständige einfache Kette angewendet wird, wird lElementIndex- auf –1 festgelegt, und lChainIndex- auf den Index der ersten Kette festgelegt ist, die einen Fehler aufweist. Wenn dwError- auf ein einzelnes Zertifikatelement angewendet wird, lChainIndex- und "lElementIndex" das erste Zertifikat mit dem Fehler indizieren.

Verwenden Sie die folgende Syntax, um das Zertifikatelement abzurufen:

pChainContext->rgpChain[lChainIndex]->rgpElement[lElementIndex];

Verwenden Sie die CertGetCertificateChain--Funktion, um die Zertifikatsperrüberprüfung zu aktivieren und durchzuführen. Die funktion CertVerifyCertificateChainPolicy überprüft nicht, ob Zertifikate in der Zertifikatkette widerrufen werden.

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