WinVerifyTrust-Funktion (wintrust.h)

  • Artikel

Die WinVerifyTrust-Funktion führt eine Vertrauensüberprüfungsaktion für ein angegebenes Objekt aus. Die Funktion übergibt die Abfrage an einen Vertrauensanbieter , der den Aktionsbezeichner unterstützt, sofern vorhanden.

Verwenden Sie für die Zertifikatüberprüfung die Funktionen CertGetCertificateChain und CertVerifyCertificateChainPolicy .

Syntax

LONG WinVerifyTrust(
  [in] HWND   hwnd,
  [in] GUID   *pgActionID,
  [in] LPVOID pWVTData
);

Parameter

[in] hwnd

Optionales Handle für ein Aufruferfenster. Ein Vertrauensanbieter kann diesen Wert verwenden, um zu bestimmen, ob er mit dem Benutzer interagieren kann. Vertrauensanbieter führen jedoch in der Regel Überprüfungsaktionen ohne Eingabe des Benutzers durch.

Dieser Parameter kann einen der folgenden Werte annehmen.

Wert Bedeutung
INVALID_HANDLE_VALUE
 Es gibt keinen interaktiven Benutzer. Der Vertrauensanbieter führt die Überprüfungsaktion ohne die Unterstützung des Benutzers aus.
Zero
 Der Vertrauensanbieter kann den interaktiven Desktop verwenden, um seine Benutzeroberfläche anzuzeigen.
Ein gültiges Fensterhandle
 Ein Vertrauensanbieter kann jeden anderen Wert als INVALID_HANDLE_VALUE oder null als gültiges Fensterhandle behandeln, das er für die Interaktion mit dem Benutzer verwenden kann.

[in] pgActionID

Ein Zeiger auf eine GUID-Struktur , die eine Aktion und den Vertrauensanbieter identifiziert, der diese Aktion unterstützt. Dieser Wert gibt den Typ der Überprüfungsaktion an, die für die Struktur ausgeführt werden soll, auf die pWinTrustData verweist.

Der WinTrust-Dienst ist für die Zusammenarbeit mit Vertrauensanbietern konzipiert, die von Drittanbietern implementiert werden. Jeder Vertrauensanbieter stellt seinen eigenen eindeutigen Satz von Aktionsbezeichnern bereit. Informationen zu den aktionsbezeichnern, die von einem Vertrauensanbieter unterstützt werden, finden Sie in der Dokumentation für diesen Vertrauensanbieter.

Microsoft stellt beispielsweise einen Software Publisher Trust Provider bereit, der die Vertrauenswürdigkeit von Software, die aus dem Internet oder einem anderen öffentlichen Netzwerk heruntergeladen wird, festlegen kann. Der Software Publisher Trust Provider unterstützt die folgenden Aktionsbezeichner. Diese Konstanten sind in Softpub.h definiert.

Wert Bedeutung
DRIVER_ACTION_VERIFY
 Überprüfen Sie die Authentizität eines mit Windows Hardware Quality Labs (WHQL) signierten Treibers. Dies ist ein Authenticode-Add-On-Richtlinienanbieter.
HTTPSPROV_ACTION
 Überprüfen Sie eine SSL/TLS-Verbindung über das Internet Explorer.
OFFICESIGN_ACTION_VERIFY
 Diese Aktions-ID wird nicht unterstützt. Überprüfen Sie die Authentizität einer strukturierten Speicherdatei mithilfe des Microsoft Office Authenticode-Add-On-Richtlinienanbieters.

Windows Server 2003 und Windows XP: Diese Aktions-ID wird unterstützt.
WINTRUST_ACTION_GENERIC_CHAIN_VERIFY
 Überprüfen Sie zertifikatsketten, die aus einem beliebigen Objekttyp erstellt wurden. Ein Rückruf wird bereitgestellt, um die endgültige Verkettungsrichtlinie mithilfe des Kettenkontexts für jeden Signierer und Indikator signierer zu implementieren.
WINTRUST_ACTION_GENERIC_VERIFY_V2
 Überprüfen Sie eine Datei oder ein Objekt mithilfe des Authenticode-Richtlinienanbieters.
WINTRUST_ACTION_TRUSTPROVIDER_TEST
 Schreiben Sie die CRYPT_PROVIDER_DATA-Struktur in eine Datei, nachdem Sie den Authenticode-Richtlinienanbieter aufgerufen haben.

[in] pWVTData

Ein Zeiger, der bei der Umwandlung in eine WINTRUST_DATA-Struktur Informationen enthält, die der Vertrauensanbieter zum Verarbeiten des angegebenen Aktionsbezeichners benötigt. In der Regel enthält die -Struktur Informationen, die das Objekt identifizieren, das der Vertrauensanbieter auswerten muss.

Das Format der Struktur hängt vom Aktionsbezeichner ab. Informationen zu den für einen bestimmten Aktionsbezeichner erforderlichen Daten finden Sie in der Dokumentation für den Vertrauensanbieter, der diese Aktion unterstützt.

Rückgabewert

Wenn der Vertrauensanbieter überprüft, ob der Antragsteller für die angegebene Aktion vertrauenswürdig ist, ist der Rückgabewert null. Kein anderer Wert als null sollte als erfolgreiche Rückgabe betrachtet werden.

Wenn der Vertrauensanbieter nicht überprüft, ob der Antragsteller für die angegebene Aktion vertrauenswürdig ist, gibt die Funktion einen status Code vom Vertrauensanbieter zurück.

Hinweis Der Rückgabewert ist ein LONG, kein HRESULT , wie zuvor dokumentiert. Verwenden Sie keine HRESULT-Makros wie SUCCEEDED , um zu bestimmen, ob die Funktion erfolgreich war. Überprüfen Sie stattdessen den Rückgabewert auf Gleichheit von 0 .

 

Beispielsweise kann ein Vertrauensanbieter angeben, dass der Antragsteller nicht vertrauenswürdig ist oder vertrauenswürdig ist, aber Einschränkungen oder Warnungen aufweist. Der Rückgabewert kann ein vertrauensanbieterspezifischer Wert sein, der in der Dokumentation für einen einzelnen Vertrauensstellungsanbieter beschrieben wird, oder es kann sich um einen der folgenden Fehlercodes handeln.

Rückgabecode Beschreibung
TRUST_E_SUBJECT_NOT_TRUSTED
 Der Antragsteller ist bei der angegebenen Überprüfungsaktion fehlgeschlagen. Die meisten Vertrauensanbieter geben einen ausführlicheren Fehlercode zurück, der die Ursache für den Fehler beschreibt.
Hinweis  

Der TRUST_E_SUBJECT_NOT_TRUSTED Rückgabecode kann abhängig vom Wert des Registrierungsschlüssels EnableCertPaddingCheck unter HKLM\Software\Microsoft\Cryptography\Wintrust\Config zurückgegeben werden. Wenn EnableCertPaddingCheck auf "1" festgelegt ist, wird eine zusätzliche Überprüfung durchgeführt, um zu überprüfen, ob die WIN_CERTIFICATE-Struktur keine überflüssigen Informationen enthält. Bei der Überprüfung wird überprüft, ob über die PKCS #7-Struktur hinaus keine Daten ungleich 0 vorhanden sind. Weitere Informationen finden Sie in der folgenden Sicherheitsempfehlung: http://technet.microsoft.com/security/advisory/2915720#section1.

 
TRUST_E_PROVIDER_UNKNOWN
 Der Vertrauensanbieter wird auf diesem System nicht erkannt.
TRUST_E_ACTION_UNKNOWN
 Der Vertrauensanbieter unterstützt die angegebene Aktion nicht.
TRUST_E_SUBJECT_FORM_UNKNOWN
 Das für den Antragsteller angegebene Formular wird vom Vertrauensanbieter nicht unterstützt.

Hinweise

Mit der WinVerifyTrust-Funktion können Anwendungen einen Vertrauensanbieter aufrufen, um zu überprüfen, ob ein angegebenes Objekt die Kriterien eines angegebenen Überprüfungsvorgangs erfüllt. Der Parameter pgActionID identifiziert den Überprüfungsvorgang, und der Parameter pWinTrustData identifiziert das Objekt, dessen Vertrauensstellung überprüft werden soll. Ein Vertrauensanbieter ist eine DLL, die beim Betriebssystem registriert ist. Ein Aufruf von WinVerifyTrust leitet diesen Aufruf an den registrierten Vertrauensanbieter weiter, sofern vorhanden, der diesen angegebenen Aktionsbezeichner unterstützt.

Der Software Publisher Trust Provider kann beispielsweise überprüfen, ob eine ausführbare Imagedatei von einem vertrauenswürdigen Softwareherausgeber stammt und dass die Datei seit ihrer Veröffentlichung nicht geändert wurde. In diesem Fall gibt der Parameter pWinTrustData den Namen der Datei und den Typ der Datei an, z. B. eine Microsoft Portable Executable-Imagedatei .

Jeder Vertrauensanbieter unterstützt einen bestimmten Satz von Aktionen, die ausgewertet werden können. Jede Aktion verfügt über eine GUID, die sie identifiziert. Ein Vertrauensanbieter kann eine beliebige Anzahl von Aktionsbezeichnern unterstützen, aber zwei Vertrauensanbieter können denselben Aktionsbezeichner nicht unterstützen.

Ein Beispiel für die Verwendung dieser Funktion zum Überprüfen der Signatur einer portablen ausführbaren Datei (PE) finden Sie unter Beispiel C-Programm: Überprüfen der Signatur einer PE-Datei.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile wintrust.h (Softpub.h einschließen)
Bibliothek Wintrust.lib
DLL Wintrust.dll