Microsoft Corporation
February 1996
Note This document is an early release of the final specification. It is meant to specify and accompany software that is still in development. Some of the information in this documentation may be inaccurate or may not be an accurate representation of the functionality of the final specification or software. Microsoft assumes no responsibility for any damages that might occur either directly or indirectly from these inaccuracies. Microsoft may have trademarks, copyrights, patents or pending patent applications, or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give you a license to these trademarks, copyrights, patents, or other intellectual property rights.
Overview
Introduction
Terminology
Trust Model
Windows Verify Trust API
Windows Trust Common ActionData Structures
This document defines the interface to trust verification services. Trust verification services are general-purpose application programming interfaces (APIs) for determining whether the subject of the request can be trusted, based on policies defined by a trust administrator. Trust providers implement trust verification services for different types of subjects and actions required. Envisioned uses of trust verification services include trusted software publishing, image integrity, and Windows compatibility.
Trust verification services provide a common API for determining whether a specific subject can be trusted.
Trust verification services answer the question: Is [a component or resource] trusted [for something specific] according to [a specific authority]?
For example, when downloading software from the Internet, the client application needs to answer the following question: Is [this ActiveX™ control] trusted [to be labeled as provided by a trusted software publisher] according to [the Software Publisher Trust Hierarchy and System Settings]?
The answer to the question depends on the following:
Trust verification services are implemented by trust providers. Trust providers define the format of the subject information they support and what trust actions they implement. A trust action identifies the verification to be performed—for example, verifying that the subject image is published by a trusted software publisher.
It is often convenient to embed trust material used in evaluating trust decisions (such as X.509 certificates or PKCS #7 digital signatures) in subject information being verified, and each different data format may require different mechanisms for performing such embedding and for digesting the data stream. Each trust provider may support many different subject forms. To facilitate this, we define subject forms—for example, portable executable (PE) format executable images and OLE structured storage (IStorage) subjects.
Trust administrators define the local policy regarding what authorities or subjects are trusted. For example, the trust administrator for software publishers would identify which software publishers are trusted and therefore allow their digitally signed published software to run on the specified system. Administration of trust can be simplified by identifying a group of trusted software publishers based on the organization or agency, that is, the certificate authority (CA), that issued their software publishing certificates.
Trusted authorities are typically certificate authorities (or agencies of a certificate authority) whose authentication policies are acceptable to the trust administrator. Trusted authorities also refer to individual producers who are trusted. The trust administrator makes a determination of trust based on information on either the policies used by the authority or the reputation of the authority.
The following terms will be used in this document
Trusted Authority—An authority or entity that may be, or already is being, trusted for something specific. For example, Microsoft might be trusted to provide virus-free images in our products. In this case, Microsoft would be called a Trusted Authority.
Trust Administrator—The person or entity that is responsible for deciding whether an authority is to be trusted or not. For example, just because XYZ Corporation provides signatures with all the executable images it ships, that doesn't necessarily mean that I will trust them to vouch for the integrity of images on my system.
Trust Provider—A software module that implements the algorithm for application-specific policies regarding trust. Trust providers support subject forms that describe where the trust information is located and what trust actions to take regarding the subject.
The model that the trust verification services interface describes is an interface allowing any application to use a variety of trust provider services, available to all trust providers on a machine with a consistent interface. Multiple trust providers can be available on the system at the same time. Each trust provider specializes in different actions and may support one or more subject types.
Each trust provider identifies the actions supported by that provider and the structure of the data provided when evaluating trust for the given action. The data format may include subject information, which is specified uniformly for all trust providers so that they may share common code for interpreting various subject forms.
The relationship of applications to trust verification services and trust providers is shown in Figure 1.
Figure 1. Trust Verification Services
Some trust providers may implement their own administrative database containing a list of trusted authorities or subjects. The list of trusted authorities is called a Trust Authority Database, although the implementation may not depend on a database management system (DBMS). The definition and implementation of the trust authority database is specific to each trust provider and documented in the trust provider specification. Other trust providers may not refer to a configurable trust authority database and may instead follow a closed set of rules for evaluating trust decisions.
This document defines the interfaces between applications and trust verification services. The interfaces between trust verification services and trust providers will be defined in another document.
The WinVerifyTrust function is used to ascertain the trustworthiness of a subject. The caller specifies the trust provider that evaluates the subject according to the action requested.
HRESULT
WINAPI
WinVerifyTrust(
HWND hwnd,
DWORD dwTrustProvider,
DWORD dwActionID,
LPVOID ActionData,
);
The parameters are listed in Table 1.
Table 1. WinVerifyTrust Parameters
| Parameter | Description |
| hwnd | Normally, every attempt is made to make trust decisions without the aid of an interactive user. However, situations may arise where trust can be more accurately determined with user approval or decision. This parameter is used to indicate whether an interactive user is available to assist in any trust decisions. If this value is passed as INVALID_HANDLE_VALUE, then no user interface (UI) will be presented and some default decision will be made without a user’s assistance. If this value is set to any other value, then it is assumed that there is an interactive user available. If the value is zero (0), then the caller's desktop will be used for any UI. Any other value is assumed to be the HWND of a calling user's window. |
| DwTrustProvider | Specifies which trust provider is to be used to answer the question of trust. This value establishes what the remaining parameter values mean. The initial values currently defined for dwTrustProvider are the following:
|
| dwActionID | Specifies what the trust provider is being asked to verify. Each trust provider supplies its own set of trust actions. Please see the individual trust provider sections for these values. |
| ActionData | This parameter is used to pass information required by the trust provider, including data about the level of trust required or context for the trust decision, and, where applicable, information about the subject being verified. The meaning and format of the information passed via this parameter is dependent upon the action specified in the dwActionID parameter. Please refer to the individual trust provider sections for the formats supported. |
This service dispatches the specified ActionData information to the selected trust provider for trust evaluation. If the trust provider specified is WIN_TRUST_PROVIDER_UNKNOWN, then the system will select an appropriate trust provider for the action specified by the dwActionID parameter, or return the error TRUST_E_PROVIDER_UNKNOWN if no trust provider that supports that action is installed.
The definition of the ACTIONDATA structure may be common among trust providers or a trust provider may define specific ACTIONDATA structures it supports. Common ACTIONDATA structures are defined in this specification. Please see the descriptions of individual trust providers for information on the types of ACTIONDATA structures supported.
In the future, additional trust verification service APIs will be defined to enumerate available trust providers on a system and determine the actions they support.
This function returns an HRESULT indicating the results of the trust inquiry. STATUS_SUCCESS (or ERROR_SUCCESS) indicates that the subject information provided in the ActionData parameter is trusted for the specified action. The function may return either one of the standard return values defined below or a trust provider specific value.
If a value other than STATUS_SUCCESS is returned, then the subject is either not trusted or is trusted with some caveats. These caveats, if any, are specified by trust provider specific return codes and are documented with each trust provider. The standard error return codes are listed in Table 2.
Table 2. Standard Error Return Codes
| Status Code | Meaningb |
| TRUST_E_SUBJECT_NOT_TRUSTED | The subject is not trusted for the specified action. Most trust providers will return a more detailed error code than this when trust is not provided, but in some cases this undescriptive value may be returned. |
| TRUST_E_PROVIDER_UNKNOWN | The specified trust provider is not known on this system. |
| TRUST_E_ACTION_UNKNOWN | The trust verification action specified is not supported by the specified trust provider. |
| TRUST_E_SUBJECT_FORM_UNKNOWN | The form specified for the subject is not one supported or known by the specified trust provider. |
Some data structures defined in Windows are documented here for convenience and completeness. The definitions shown below are taken from the WINBASE.H header file common to Win32® platforms.
Many trust providers will require only minimal context data for trust evaluation. They derive most of the information needed for trust decisions directly from a subject. The subject is a data stream that is to be validated by the WinVerifyTrust() call. Some ACTIONDATA structures are used by several trust providers, and they are described independent of them.
The following ACTIONDATA data structures are defined:
typedef LPVOID WIN_TRUST_SUBJECT
typedef struct _WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT {
HANDLE hClientToken;
DWORD dwSubjectType;
WIN_TRUST_SUBJECT Subject;
} WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT , *LPWIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT
typedef struct _WIN_TRUST_ACTDATA_SUBJECT_ONLY {
DWORD dwSubjectType;
WIN_TRUST_SUBJECT Subject;
} WIN_TRUST_ACTDATA_SUBJECT_ONLY , *LPWIN_TRUST_ACTDATA_SUBJECT_ONLY
Within these data structures, the format of the subject data is specified by the value of the dwSubjectType field. Some commonly used subject types and subject data structures are defined below. The hClientToken parameter in the WIN_TRUST_ACTDATA_CONTEXT_WITH_SUBJECT structure is used to pass a handle to the security context of the calling application. A trust provider may use the security context when evaluating trust of the subject.
Subject types describe formats of the data stream being validated by a WinVerifyTrust() call. The subject types are specified independent of specific trust providers. Multiple trust providers may share a common implementation to extract trust material from these subject formats and digest the relevant portions of the data stream. This separation allows trust providers to verify the trustworthiness of a data stream of a given format, without building knowledge of subject formats into each trust provider. Instead, trust providers share other common components (that are also trusted software) to interpret the data stream.
Subject types defined in WINBASE.H, which are valid values for the dwSubjectType field of the ACTIONDATA structures defined above, include the following:
#define WIN_TRUST_SUBJTYPE_RAW_FILE (0L)
#define WIN_TRUST_SUBJTYPE_PE_IMAGE (1L)
#define WIN_TRUST_SUBJTYPE_OLE_STORAGE (2L)
For all of these subject types, the same data structure is required in the Subject parameter of the ACTIONDATA structures. This structure is as follows:
typedef struct _WIN_TRUST_SUBJECT_FILE {
HANDLE hFile;
LPCWSTR lpPath;
} WIN_TRUST_SUBJECT_FILE, *LPWIN_TRUST_SUBJECT_FILE;
The hFile element of the structure is optional. If hFile is provided, trust providers are expected to use this file handle to read the subject as a performance optimization. If hFile is set to the value INVALID_HANDLE_VALUE (defined in WINBASE.H), then the trust provider will open the subject using the lpPath field.
The lpPath element of this structure is mandatory, and it includes the path of the subject being verified. The string may be used for the purpose of opening the file to read it, and optionally for prompting the user for additional information about the file.
The caller may specify both fields in the structure, but provide a different string for lpPath than was used to obtain the HFILE handle. The lpPath string is not validated to ensure consistency with the open handle or the name that the subject may "expect" to have. This gives the caller the option of storing a subject data stream under a temporary name during the trust verification phase, and presenting the original file path in any user interface dialog.