CertVerifyCertificateChainPolicy-Funktion (wincrypt.h)

Artikel
08/27/2023

Die CertVerifyCertificateChainPolicy-Funktion überprüft eine Zertifikatkette, um deren Gültigkeit zu überprüfen, einschließlich der Konformität mit allen 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 Verifikationskettenrichtlinienstrukturen sind in der folgenden Tabelle aufgeführt.

Wert	Bedeutung
CERT_CHAIN_POLICY_BASE (LPCSTR) 1	Implementiert die Überprüfungen der Basiskettenrichtlinie. Der dwFlags-Member der Struktur, auf die von pPolicyPara verwiesen wird, kann so festgelegt werden, dass das Standardverhalten der Richtlinienüberprüfung geändert wird.
CERT_CHAIN_POLICY_AUTHENTICODE (LPCSTR) 2	Implementiert die Überprüfungen der Authenticode-Verkettungsrichtlinie. Der pvExtraPolicyPara-Member der Struktur, auf die pPolicyPara verweist, kann so festgelegt werden, dass er auf eine AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_PARA-Struktur zeigt. Der pvExtraPolicyStatus-Member der Struktur, auf die pPolicyStatus verweist, kann so festgelegt werden, dass er auf eine AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_STATUS-Struktur verweist.
CERT_CHAIN_POLICY_AUTHENTICODE_TS (LPCSTR) 3	Implementiert Überprüfungen von Authenticode-Zeitstempelketten-Richtlinienüberprüfungen. Der pvExtraPolicyPara-Member der Datenstruktur, auf die pPolicyPara verweist, kann so festgelegt werden, dass er auf eine AUTHENTICODE_TS_EXTRA_CERT_CHAIN_POLICY_PARA-Struktur zeigt. Der pvExtraPolicyStatus-Member der Datenstruktur, auf die von pPolicyStatus verwiesen wird, wird nicht verwendet und muss auf NULL festgelegt werden.
CERT_CHAIN_POLICY_SSL (LPCSTR) 4	Implementiert die Überprüfungen der SSL-Client-/Server-Kettenrichtlinie. Der pvExtraPolicyPara-Member in der Datenstruktur, auf die von pPolicyPara verwiesen wird, kann so festgelegt werden, dass er 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 zum Abrufen des Kettenkontexts den Zertifikattyp angeben, indem die erwartete Verwendung festgelegt wird. Legen Sie die erwartete Nutzung 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. Durchläuft alle Zertifikate in der Kette, die entweder für eine szOID_BASIC_CONSTRAINTS- oder eine szOID_BASIC_CONSTRAINTS2-Erweiterung überprüft werden. Wenn keine erweiterung vorhanden ist, wird angenommen, dass das Zertifikat über eine gültige Richtlinie verfügt. Andernfalls überprüft das erste Zertifikatelement, ob es mit der erwarteten CA_FLAG oder END_ENTITY_FLAG übereinstimmt, die im dwFlags-Member der CERT_CHAIN_POLICY_PARA-Struktur angegeben ist, auf die der pPolicyPara-Parameter verweist. Wenn keines oder beide Flags festgelegt sind, kann das erste Element entweder eine Zertifizierungsstelle oder eine 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-Authentifizierungskettenrichtlinie, die aus drei unterschiedlichen Kettenüberprüfungen in der folgenden Reihenfolge besteht: CERT_CHAIN_POLICY_BASE– Implementiert die Überprüfungen der Basiskettenrichtlinie. Der 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 Richtlinie für einschränkungsketten. Das HIWORD von dwFlags kann festgelegt werden, um anzugeben, ob das erste Element entweder eine Zertifizierungsstelle oder eine 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 Systemregistrierungsspeicher "NTAuth" im CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE Speicherort vorhanden ist. Wenn diese Überprüfung fehlschlägt, ist die Zertifizierungsstelle nicht vertrauenswürdig, und dwError ist auf CERT_E_UNTRUSTEDCA festgelegt. Wenn CERT_PROT_ROOT_DISABLE_NT_AUTH_REQUIRED_FLAG im Flags-Wert des durch CERT_PROT_ROOT_FLAGS_REGPATH definierten Unterschlüssels der HKEY_LOCAL_MACHINE Richtlinie ProtectedRoots festgelegt ist und die obige Überprüfung fehlschlägt, wird die Kette auf CERT_TRUST_HAS_VALID_NAME_CONSTRAINTS überprüft, die in dwInfoStatus festgelegt ist. Dies wird festgelegt, wenn eine gültige Namenseinschränkung für alle Namespaces einschließlich UPN vorhanden ist. Wenn für die Kette diese Informationen nicht festgelegt status, wird dwError auf CERT_E_UNTRUSTEDCA festgelegt.
CERT_CHAIN_POLICY_MICROSOFT_ROOT (LPCSTR) 7	Überprüft das letzte Element der ersten einfachen Kette auf 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_UNTRUSTEDROOT festgelegt. Der dwFlags-Member der CERT_CHAIN_POLICY_PARA-Struktur , auf die der pPolicyStatus-Parameter verweist, kann das flag MICROSOFT_ROOT_CERT_CHAIN_POLICY_CHECK_APPLICATION_ROOT_FLAG enthalten, wodurch diese Funktion stattdessen nach dem Microsoft-Anwendungsstamm "Microsoft Root Certificate Authority 2011" sucht. Der dwFlags-Member der CERT_CHAIN_POLICY_PARA-Struktur , auf die der pPolicyPara-Parameter verweist, kann das flag MICROSOFT_ROOT_CERT_CHAIN_POLICY_ENABLE_TEST_ROOT_FLAG enthalten, wodurch diese Funktion auch nach den Microsoft-Teststämmen sucht. Hinweis Dieser Richtlinienobjektbezeichner (Policy Object Identifier , OID) führt keine Richtlinienüberprüfungen selbst durch, er ist für die Verwendung in Verbindung mit anderen Richtlinien vorgesehen.
CERT_CHAIN_POLICY_EV (LPCSTR) 8	Gibt an, dass eine erweiterte Validierung 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 eine schwache Kryptografie aufweisen oder ob die Kompatibilität von Stammzertifikaten von Drittanbietern besteht, und stellt eine Fehlerzeichenfolge bereit. Der pvExtraPolicyStatus-Member der CERT_CHAIN_POLICY_STATUS Struktur, auf die der pPolicyStatus-Parameter verweist, muss auf SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS verweisen, der mit den Ergebnissen der Überprüfungen der schwachen Krypto- und Stammprogrammkonformität aktualisiert wird. Vor dem Aufrufen muss der cbSize-Member der CERT_CHAIN_POLICY_STATUS Struktur, auf die der pPolicyStatus-Parameter verweist, auf einen Wert festgelegt werden, der größer oder gleich sizeof(SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS) ist. Das dwError-Element in CERT_CHAIN_POLICY_STATUS Struktur, auf die der pPolicyStatus-Parameter verweist, wird auf TRUST_E_CERT_SIGNATURE für potenzielle schwache Kryptografie festgelegt und auf CERT_E_UNTRUSTEDROOT für Root-Elemente von Drittanbietern festgelegt, die nicht mit dem Microsoft-Stammprogramm 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. Der dwFlags-Member dieser Struktur kann so festgelegt werden, dass das Standardverhalten der Richtlinienüberprüfung geändert wird.

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

[in, out] pPolicyStatus

Ein Zeiger auf eine CERT_CHAIN_POLICY_STATUS-Struktur, in der status Informationen zur Kette zurückgegeben werden. OID-spezifische zusätzliche status können im element pvExtraPolicyStatus dieser Struktur zurückgegeben werden.

Rückgabewert

Der Rückgabewert gibt an, ob die Funktion die Richtlinie überprüfen konnte. Er gibt nicht an, ob die Richtlinienprüfung fehlgeschlagen oder bestanden wurde.

Wenn die Kette für die angegebene Richtlinie überprüft werden kann, wird TRUE zurückgegeben, und der dwError-Member des pPolicyStatus wird aktualisiert. DwError von 0 (ERROR_SUCCESS oder S_OK) gibt an, dass die Kette die angegebene Richtlinie erfüllt.

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

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

Hinweise

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

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 CertVerifyCertificateChainPolicy-Funktion überprüft nicht, ob Zertifikate in der Zertifikatkette widerrufen werden.

Anforderungen


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