Platform SDK: WinTrust |
The WinVerifyTrust function performs a trust verification action on a specified object. The function passes the inquiry to a trust provider, if one exists, that supports the action identifier.
HRESULT WINAPI WinVerifyTrust( HWND hWnd, GUID *pgActionID, WINTRUST_DATA *pWinTrustData );
This parameter can be one of the following values:
Value | Meaning |
---|---|
INVALID_HANDLE_VALUE | There is no interactive user. The trust provider performs the verification action without the user's assistance. |
Zero | The trust provider can use the interactive desktop to display its user interface. |
A valid window handle | A trust provider can treat any value other than INVALID_HANDLE_VALUE or zero as a valid window handle that it can use to interact with the user. |
The WinTrust service is designed to work with trust providers implemented by third parties. Each trust provider provides its own unique set of action identifiers. For information about the action identifiers supported by a trust provider, see the documentation for that trust provider.
For example, Microsoft provides a Software Publisher Trust Provider that can establish the trustworthiness of software being downloaded from the Internet or some other public network. The Software Publisher Trust Provider supports the following action identifiers.
Value | Description |
---|---|
WINTRUST_ACTION_GENERIC_VERIFY | Verifiy a certificate chain only. |
WINTRUST_ACTION_GENERIC_VERIFY_V2 | Verify a file or object using the Microsoft Authenticode Policy Provider. |
HTTPSPROV_ACTION | Verify an SSL/PCT connection through Internet Explorer. |
The format of the structure depends on the action identifier. For information about the data required for a specific action identifier, see the documentation for the trust provider that supports that action.
If the trust provider verifies that the subject is trusted for the specified action, the return value is ERROR_SUCCESS. Otherwise, the function returns a status code from the trust provider.
For example, a trust provider might indicate that the subject is not trusted, or is trusted but with limitations or warnings. The return value can be a trust-provider-specific value described in the documentation for an individual trust provider, or it can be one of the following error codes.
Value | Meaning |
---|---|
TRUST_E_SUBJECT_NOT_TRUSTED | The subject failed the specified verification action. Most trust providers return a more detailed error code that describes the reason for the failure. |
TRUST_E_PROVIDER_UNKNOWN | The trust provider is not recognized on this system. |
TRUST_E_ACTION_UNKNOWN | The trust provider does not support the specified action. |
TRUST_E_SUBJECT_FORM_UNKNOWN | The trust provider does not support the form specified for the subject. |
The WinVerifyTrust function enables applications to invoke a trust provider to verify that a specified object satisfies the criteria of a specified verification operation. The pgActionID parameter identifies the verification operation, and the pWinTrustData parameter identifies the object whose trust is to be verified. A trust provider is a DLL registered with WinTrust. A call to WinVerifyTrust forwards that call to the registered trust provider, if there is one, that supports that specified action identifier.
For example, the Software Publisher Trust Provider can verify that an executable image file comes from a trusted software publisher and that the file has not been modified since it was published. In this case, the pWinTrustData parameter specifies the name of the file and the type of file, such as a Microsoft Portable Executable image file or a Java class file.
Each trust provider supports a specific set of actions that it can evaluate. Each action has a globally unique identifier (GUID) that identifies it. A trust provider can support any number of action identifiers, but two trust providers cannot support the same action identifier.
Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98: Unsupported.
Header: Declared in winbase.h.
Import Library: Use wintrust.lib.