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.
This document defines the behavior of the Software Publishing trust provider, a module that supports selected actions under the Windows Verify Trust application programming interface (API). It is a companion to the Windows Trust Verification Services specification and should be read after that document. The Software Publishing trust provider allows a calling application to determine whether a software component contains digital signatures that identify it as being authentic software released by a publisher that is trusted on the local user's system.
The Software Publishing trust provider is a module for handling specified actions under the WinVerifyTrust() API as discussed in the Windows Trust Verification Services specification. This module supports verification of the trustability of software components, by interpreting local system rules and analyzing cryptographic material associated with those software components, which may be either embedded directly in those modules to be analyzed, or previously installed into a system database for later retrieval.
The initial implementation of the Software Publishing trust provider, described in the document, provides relatively user-friendly security with weak enforcement. It allows users to install any software desired on their systems, but requires user interaction prior to installation of software not determined to be trustable by the available cryptographic material. Stronger implementations, which support additional actions that can be used to more closely guard the entrance of new software modules into the Trusted Computing Base, may be provided at a future date.
This trust provider makes use of X.509 version 3 certificates and PKCS #7 digital signature structures, and it is assumed that the reader has a working knowledge of these standards.
Additionally, the trust provider uses specific X.509 version 3 extensions and particular signed attributes within PKCS #7 structures that have been defined for the purpose of signing and authenticating software.
The Software Publishing trust provider is called by using the Microsoft® Win32® API WinVerifyTrust() function, documented in the Windows Trust Verification Services specification. Recall that this function has the following prototype:
HRESULT
WINAPI
WinVerifyTrust(
HWND hwnd,
DWORD dwTrustProvider,
DWORD dwActionID,
LPVOID ActionData,
);
The Software Publishing trust provider is identified by the WINBASE.H constant:
#define WIN_TRUST_SOFTWARE_PUBLISHER (1L)
Calls where this value is passed for the dwTrustProvider parameter are handled by the Software Publishing trust provider. The trust provider supports two actions (passed in the dwActionID parameter) at this time, defined as:
#define WIN_SPUB_ACTION_TRUSTED_PUBLISHER (1L)
#define WIN_SPUB_ACTION_PUBLISHED_SOFTWARE (3L)
Note In the alpha development release of ActiveX™ technologies provided at the Microsoft Professional Developers Conference in March 1996, the first action listed above is not supported.
In the initial implementation, the Software Publishing trust provider is also the system default provider for these actions. Therefore, if the caller specifies in the dwTrustProvider parameter the constant:
#define WIN_TRUST_PROVIDER_UNKNOWN (0L)
and the action is either of those defined above, the call will also be handled by this trust provider. This is the calling method that most applications will employ, because it allows later system configuration options, which permit system or network administrators to assign various more-or-less stringent trust providers to handling these actions, without requiring modification to the applications.
For the action WIN_SPUB_ACTION_PUBLISHED_SOFTWARE, the ActionData parameter is expected to be a pointer to a data structure of type WIN_TRUST_ACTDATA_SUBJECT_ONLY.
typedef LPVOID WIN_TRUST_SUBJECT
typedef struct _WIN_TRUST_ACTDATA_SUBJECT_ONLY {
DWORD dwSubjectType;
WIN_TRUST_SUBJECT Subject;
} WIN_TRUST_ACTDATA_SUBJECT_ONLY , *LPWIN_TRUST_ACTDATA_SUBJECT_ONLY
In this structure, dwSubjectType identifies the format of the file or object being verified, and the SUBJECT structure is a pointer to a structure that provides information for reading or manipulating the object. Valid values for the subject type include:
#define WIN_TRUST_SUBJTYPE_RAW_FILE (0L)
#define WIN_TRUST_SUBJTYPE_PE_IMAGE (1L)
The SUBJECT structure for either of these types is of this form:
typedef struct _WIN_TRUST_SUBJECT_FILE {
HANDLE hFile;
LPSTR lpPath;
} WIN_TRUST_SUBJECT_FILE, *LPWIN_TRUST_SUBJECT_FILE;
Details on this structure is provided in the Windows Trust Verification Services specification.
When the WIN_SPUB_ACTION_PUBLISHED_SOFTWARE action is invoked, the subject is inspected to see whether it contains a PKCS #7 signed data structure. If it does, the structure is expected to contain a chain of X.509 certificates. In this development release, a root certificate must be present that is a self-signed certificate containing a hard-coded test root public key and is signed by the root private key. Additionally, a certificate must be present that is signed by the root private key and identifies a software publisher's public key. Finally, the PKCS #7 signed data structure must contain an ExternalData signed attribute that contains a digest of the subject being verified.
In the future, each certificate will also be inspected to ensure that it contains appropriate X509.3 extensions defining key-usage restrictions and other attributes of the certified parties.
If these conditions are met, the API returns SUCCESS to the calling application.
Otherwise, if an HWND was provided, a user interface is displayed providing information obtained from any valid certificates present that contains the path of the subject file. If the user confirms acceptance of the file, the API also returns SUCCESS; if the user does not confirm acceptance, the API returns a distinguished error code.
Full documentation of error conditions and corresponding return codes will be included in a later version of this document.