25    Security Support Provider Interface

The Security Support Provider Interface (SSPI) provides a common interface between transport-level applications and security providers. SSPI provides a mechanism by which a distributed application can call one of several security providers to obtain an authenticated connection without knowledge of the details of the security protocol.

The SSPI consists of the following APIs:

• Credential Management APIs--Credential Management APIs provide access to credentials (password data, tickets, and so on) of a principal or free such access. The APIs are:

  • AcquireCredentialsHandle--This method acquires a handle to the reference credentials.

  • FreeCredentialsHandle--This method releases a credential handle and associated resources.

  • QueryCredentialAttributes--This method allows queries on various credential attributes like associated name, domain name, and so forth.

• Context Management APIs--Context management APIs provide methods for creating and using security contexts. The contexts are created on both the client and the server side of a communication link. These contexts can then be used later with the message support APIs. The APIs are:

  • InitializeSecurityContext--Initiates a security context by generating an opaque message (security token) that can be passed to the server.

  • AcceptSecurityContext--Creates a security context using the opaque message received from the client.

  • DeleteSecurityContext--Frees a security context and associated resources.

  • QueryContextAttributes--Allows queries on various context attributes.

  • ApplyControlToken--Applies a supplemental security message to an existing security context.

  • CompleteAuthToken--Completes an authentication token, since some protocols, like DCE RPC, need to revise the security information once the transport has updated some message fields.

  • ImpersonateSecurityContext--Attaches the client's security context as an impersonation token to the calling thread.

  • RevertSecurityContext--Ceases impersonation and defaults the calling thread to its primary token.

• Message Support APIs--Message support APIs provide communication integrity and privacy services based on a security context. The APIs are:

  • MakeSignature--Generates a secure signature based on a message and a security context.

  • VerifySignature--Verifies that the signature matches a received message.

• Package Management APIs--Package Managment APIs provide services for different security packages that the security provider supports. The APIs are:

  • EnumerateSecurityPackages--Lists available security packages and their capabilities.

  • QuerySecurityPackageInfo--Queries an individual security package for its capabilities.

SSPI does not currently provide any public interfaces for encryption/decryption functionality. Future versions of the SSPI will make message support routines for encryption available.

A security provider is a dynamic-link library that implements the Security Support Provider Interface and makes one or more security packages available to applications. A security package maps the SSPI functions to an implementation of the security protocol specific to that package, such as NTLM, Kerberos, or SSL. Security packages are sometimes referred to as ``SSPs,'' such as the ``NTLM SSP.'' The name of the security package is used in the initialization step to identify a specific package.

The Security Support Provider Interface allows an application to use any of the available security packages on a system without changing the interface to use security services. SSPI does not establish logon credentials because that is generally a privileged operation handled by the operating system.

An application can use the package management functions to list the security packages available and select one to support its needs. The application then uses the credential management functions to obtain a handle to the credentials of the user on whose behalf they are executing. With this handle, the application can use the context management functions to create a security context to a service. A security context is an opaque data structure that contains the security data relevant to a connection, such as a session key, the duration of the session, and so on. Finally, the application uses the security context with the message support functions to ensure message integrity and privacy during the connection.

25.1    Security Package Capabilities

The capabilities of the security package determine what services it provides to the application. These capabilities include, for example, support for client-only authentication or mutual authentication, or support for message integrity and message privacy. In addition, some packages are designed for use only on reliable transport protocols and are not designed for use on datagram transports.

The security package capabilities available by a specific package are obtained using the QuerySecurityPackageInfo API. The following lists show the security package capabilities:

• Authentication-related capabilities:

  • Client-only authentication

  • Multileg authentication required

• Transport-related capabilities:

  • Datagram-style transports

  • Connection-oriented transports

  • Data stream connection semantics

• Message-related capabilities:

  • Supports message integrity

  • Supports message privacy

Applications will typically select security packages based on the type of security capabilities available to meet the application needs. More discussion on security package capabilities can be found in the section below on Security Context Semantics.

25.2    Initializing the Security Provider

This section describes how applications-level protocols initialize and use the Security Support Provider Interface. The section describes various stages of a secure network connection setup. The stages include:

• Initializing the SSPI

• Establishing an authenticated connection

• Ensuring communication integrity during message exchange

• ``Security quality of service'' to service a client request

These stages are described in the following sections.

25.2.1    Initializing the SSPI

Both the client and server use the same sequence of operations to initialize the security provider and select the appropriate security package.

Initializing the security interface involves the following steps:

• Load the security provider DLL

• Get a pointer to the provider initialization function

• Use the initialization function to get a reference to the provider's security function table

• Get specific information about the security package, such as the maximum token size

The security function table contains the SSPI entry points for the security package. The function table is used to invoke the calls implemented by the security package.

25.3    Loading the Security Provider DLL

In order to initialize security, we need to ``load'' the provider. In all our discussions it will be assumed that the client side of the provider is a DLL..

The provider is loaded using a call to the LoadLibrary function, shown in the example below:

void * DllHandle;
//loading NTLM SSP
DllHandle = (void *)LoadLibrary(TEXT(``security.dll'');
if(!DllHandle)
{
 // 
 // DLL did not get loaded.
 //
 Status = GetLastError();
 return Status;
}
//
// DllHandle is valid
//

• NTLM

• MSN

• Schannel (SSL/ Private Communications Technology [PCT])

25.4    Provider Initialization

Once the provider has been loaded successfully, you need to perform some setup to use the security interface conveniently in the rest of the application. First, you need to get a pointer to the initialization function for the provider. Then you will use the initialization function to get a reference to the provider's security function table. Finally, you can get information from the provider about the security packages, or protocols, supported by this security provider. Each security package may have unique capabilities of interest to the application. However, in most cases, applications use security packages that support default or common capabilities.

The example below shows how to initialize the security provider.

//
// Initial provider setup.
//
INIT_SECURITY_INTERFACE  InitSecurityInterface;
PSecurityFunctionTable  SecurityInterface = 0;
SecPkgInfo  PAPI *    SecurityPackages;
DWORD    NumOfPkgs;
SECURITY_PROVIDER_INFO PAPI * List;
InitSecurityInterface = GetProcAddress(DllHandle, SECURITY_ENDPOINT);
if(!InitSecurityInterface)
{
 //
 // Something is amiss..
 //
}
//
// We got the InitSecurityInterface!
// Now use it to get the function table.
//
SecurityInterface = (*InitSecurityInterface)();
if(!SecurityInterface)
{
 //
 // we have a problem...
 //
}
//
// Lets find out the security packages supported by the provider.
//
Status = (*SecurityInterface->EnumerateSecurityPackages)( &NumOfPkgs, &SecurityPackages);
//
// Now using the capabilities information figure out which package you want to use.
//
PkgToUseIndex = -1;
for(I=0;I<NumOfPackages;I++)
{
 //
 // for example, if app needs integrity & privacy on messages, it checks
 //
 if(SecurityPackages[I].fCapabilities & (SECPKG_FLAG_INTEGRITY | SECPKG_FLAG_PRIVACY))
 {
  PkgToUseIndex = I;
  break;
 }
}
if(PkgToUseIndex > 0)
{
 //
 // Find out the maximum token size for this package
 //
 g_MaxToken = SecurityPackages[I].cbMaxToken;
}

Both the client and server need to agree on the security package they will use before the SSPI initialization steps shown above.

At this point the application has successfully initialized a security support provider and chosen a security package with sufficient capabilities needed by the application protocol. The SecurityInterface points to an array of function pointers as defined by SSPI.

Notice that the call to EnumerateSecurityPackages initializes the reference pointer SecurityPackages, with return data. Some SSPI functions have return output parameters, such as security package information. For the output data parameters, the caller passes in a pointer to a pointer to the return structure type, and the security provider allocates memory and returns the data to the caller by assigning the address of the return data buffer to the argument. The convention used by SSPI to return data is the following:

``The security package allocates, and the caller frees.''

Therefore, the calling program will use FreeContextBuffer to free the memory containing data allocated by the security provider when it is done referencing the data. The examples below will continue to reference SecurityPackages information, so it must be freed later.

25.5    Security Function Table

The Security Function Table is an array of function pointers which are defined in the include file, SSPI.H. The function names correspond to the interface specification for SSPI.

The definition of the Security Function Table is shown below:

typedef struct _SECURITY_FUNCTION_TABLE_W {
 unsigned long      dwVersion;
 ENUMERATE_SECURITY_PACKAGES_FN_W EnumerateSecurityPackagesW;
 void SEC_FAR *      Reserved1;
// QUERY_CREDENTIALS_ATTRIBUTES_FN_W QueryCredentialsAttributesW;
 ACQUIRE_CREDENTIALS_HANDLE_FN_W  AcquireCredentialsHandleW;
 FREE_CREDENTIALS_HANDLE_FN   FreeCredentialHandle;
 void SEC_FAR *      Reserved2;
 INITIALIZE_SECURITY_CONTEXT_FN_W InitializeSecurityContextW;
 ACCEPT_SECURITY_CONTEXT_FN   AcceptSecurityContext;
 COMPLETE_AUTH_TOKEN_FN    CompleteAuthToken;
 DELETE_SECURITY_CONTEXT_FN   DeleteSecurityContext;
 APPLY_CONTROL_TOKEN_FN    ApplyControlToken;
 QUERY_CONTEXT_ATTRIBUTES_FN_W  QueryContextAttributesW;
 IMPERSONATE_SECURITY_CONTEXT_FN  ImpersonateSecurityContext;
 REVERT_SECURITY_CONTEXT_FN   RevertSecurityContext;
 MAKE_SIGNATURE_FN     MakeSignature;
 VERIFY_SIGNATURE_FN     VerifySignature;
 FREE_CONTEXT_BUFFER_FN    FreeContextBuffer;
 QUERY_SECURITY_PACKAGE_INFO_FN_W QuerySecurityPackageInfoW;
 void SEC_FAR *      Reserved3;
 void SEC_FAR *      Reserved4;
 QUERY_SECURITY_CONTEXT_TOKEN_FN  QuerySecurityContextToken;
} SecurityFunctionTableW, SEC_FAR * PSecurityFunctionTableW;

25.5.1    Memory Use, Security Buffers, and Descriptor

Most of the SSPI functions have variable length arguments for the caller (application) to provide message data to the security package and for the security package to return security data to the caller. SSPI APIs use a parameter type, BufferDescriptor, to define the size and location of the variable length data. Security buffers are used by the caller, for example, to pass message data to the security package, or to receive an output security token.

Security buffers can be passed in as an array of buffers. The security buffer descriptor identifies the number of buffers and starting address of the buffer array. Each security buffer also has a buffer type field to identify the contents of the buffer.

The definition of security buffers, buffer descriptors, and buffer data types from SSPI.H are shown below:

//
// SecBuffer
//
// Generic memory descriptors for buffers passed in to the security
// API
//
typedef struct _SecBuffer {
 unsigned long cbBuffer;    // Size of the buffer, in bytes
 unsigned long BufferType;   // Type of the buffer (below)
 void SEC_FAR * pvBuffer;   // Pointer to the buffer
} SecBuffer, SEC_FAR * PSecBuffer;
typedef struct _SecBufferDesc {
 unsigned long ulVersion;   // Version number
 unsigned long cBuffers;    // Number of buffers
#ifdef MIDL_PASS
 [size_is(cBuffers)]
#endif
 PSecBuffer pBuffers;    // Pointer to array of buffers
} SecBufferDesc, SEC_FAR * PSecBufferDesc;
#define SECBUFFER_VERSION   0
#define SECBUFFER_EMPTY    0 // Undefined, replaced by provider
#define SECBUFFER_DATA    1 // Packet data
#define SECBUFFER_TOKEN    2 // Security token
#define SECBUFFER_PKG_PARAMS  3 // Package specific parameters
#define SECBUFFER_MISSING   4 // Missing Data indicator
#define SECBUFFER_EXTRA    5 // Extra data
#define SECBUFFER_STREAM_TRAILER 6 // Security Trailer
#define SECBUFFER_STREAM_HEADER  7 // Security Header
#define SECBUFFER_ATTRMASK   0xF0000000
#define SECBUFFER_READONLY   0x80000000 // Buffer is read-only

Each time a security API is called that takes a SecBufferDesc parameter, it should be setup with one or more SecBuffers. For example, there can be two security buffers, one that contains input message data and the other for the output opaque security token returned by the security package. The order of security buffers in the security buffer descriptor is not important but they should be tagged with appropriate type. Also, an input buffer that can not be modified by the security package should additionally be tagged as read only.

The size of the output buffer that is expected to contain the security token is important. An application can find the maximum token size for a security package during initial setup. The call to EnumerateSecurityPackages returns an array of pointers to security package information. The security package information structure contains maximum token size value. In the example code, the information is in SecPkgInfo.cbMaxToken. It can also be obtained later on using QuerySecurityPackageInfo.

The application initializes the buffer pointers and sizes in the buffer description to indicate where message data and other information may be found.

The example below shows how to initialize an array of security buffers. This particular case shows how input security buffers are initialized by the server-side of a connection in a call to AcceptSecurityContext. Note that the last buffer contains the opaque security token received by the client and the SECBUFFER_READONLY flag is also set.

SecBuffer  Buffers[3];
SecBufferDesc BufferDesc;
...
BufferDesc.ulVersion = SECBUFFER_VERSION;
BufferDesc.cBuffers = 3;
BufferDesc.pBuffers = &Buffers;
Buffers[0].cbBuffer = sizeof(Protocol_Header);
Buffers[0].BufferType = SECBUFFER_READONLY | SECBUFFER_DATA;
Buffers[0].pvBuffer = pHeader;
Buffers[1].cbBuffer = pHeader->MessageSize;
Buffers[1].BufferType = SECBUFFER_DATA;
Buffers[1].pvBuffer = pMessage;
Buffers[2].cbBuffer = pHeader->TrailerSize;
Buffers[2].BufferType = SECBUFFER_READONLY | SECBUFFER_TOKEN;
Buffers[2].pvBuffer = pSecurityTrailer;

25.6    Establishing an Authenticated Connection

In a client/server application protocol, a server typically binds to a well known communication port (for example, a socket, RPC interface, and so forth) and waits for clients to connect and request service. The role of security at connection setup is two fold:

• Server should be able to authenticate the client.

• Client should be able to authenticate the server.

Associated with these two basic requirements are other security issues, such as, the authentication information should not be prone to replay, corruption, and so on. The application does not need to worry about how these are handled. It can simply request it from the chosen provider which will encapsulate the underlying security protocol.

The protocol used to establish an authenticated connection involves the exchange of one or more ``security tokens'' between the security providers on each side. These tokens are sent as ``opaque'' messages by the two sides along with any other application protocol specific information. The application level protocol strips the security token out of the received message and passes on to the security package on their side to figure out if authentication is complete or if further exchange of tokens is required. Theoretically, the exchange of security tokens can continue ad infinitum, however, in practice it contains one to three legs of message exchange.

For example, NTLM authentication is based on the challenge/response scheme, and uses three legs to authenticate a client to the server, as shown in the figure below.

Figure 25-1:  NTLM Challenge Response Authentication Protocol via SSPI

25.6.1    Client Context Initialization

To establish a secure connection, the client needs to acquire an outbound credentials handle so that it can send over an authentication request to the server. The server creates a security context for the client from the authentication request. There are two client-side SSPI functions involved in authentication setup:

• AcquireCredentialsHandle to obtain a reference to previously obtained logon credentials

• InitializeSecurityContext to create the initial authentication request security tokens

Using the reference to the Security Function Table initialized during the security provider setup stage, the client calls AcquireCredentialsHandle as follows:

//
// Acquire an out-bound Credentials handle using the chosen security package.
//
SecurityStatus = (*SecurityInterface->AcquireCredentialsHandle)(
     0,
     SecurityPackages[PkgToUseIndex].Name,
     SECPKG_CRED_OUTBOUND,
     0,
     0,
     0,
     0,
     &Credentials,
     &TimeStamp
     );

The arguments to AcquireCredentialHandle are the following:

• Arg1 = Principal Name, set to NULL here to let the security package use the default.

• Arg2 = Security Package Name, set to the one that was selected during package setup.

• Arg3 = Type of credential, the client will use outbound credentials.

• Arg4 = Pointer to LogonID, set to NULL to let the security package use the default.

• Arg5 = AuthIdentity, set to NULL to use the process's default credentials. This parameter may be used to provide. package specific data. For an NTLM security package it may contain a pointer to the SEC_WINNT_AUTH_IDENTIY structure that contains the username, domainname, and password. This feature is used, for example, by file system redirectors to allow users to specify an alternate account name than the one they are currently logged in as when connecting to a remote file server.

• Arg6 = GetKey function, set to NULL, not used.

• Arg7 = Any argument to the GetKey function, also set to NULL.

• Arg8 = returned Credentials Handle, used for additional SSPI calls.

• Arg9 = returned TimeStamp which indicates the lifespan of the credentials handle.

Once the client has acquired an outbound credentials handle, it is ready to start the authentication protocol to establish a connection with the server. The application client calls the security package again to initialize the security context.

To initiate the first leg of the authentication, the client calls InitializeSecurityContext to obtain an initial security token that will be sent in a connection request message to the server.

The example of the client call to InitializeSecurityContext is shown below:

//
// Set up the Buffer Descriptor.
//
OutBufferDesc.ulVersion = 0;
OutBufferDesc.cBuffers = 1;
OutBufferDesc.pBuffers = &OutSecBuffer;
OutSecBuffer.cbBuffer = BufferLen;
OutSecBuffer.BufferType = SECBUFFER_TOKEN;
OutSecBuffer.pvBuffer = Buffer;
//
// Lets get the authentication token from the security package
// to send to the server to request an authenticated connection.
//
SecurityStatus = (*SecurityInterface->InitializeSecurityContext(
    Credentials,
    0,
    ServerPrincipalName,
    ISC_REQ_USE_DCE_STYLE | ISC_REQ_DELEGATE |
    ISC_REQ_MUTUAL_AUTH |ISC_REQ_REPLAY_DETECT |
    ISC_REQ_SEQUENCE_DETECT |ISC_REQ_CONFIDENTIALITY |
    ISC_REQ_CONNECTION,
    0,
    0,
    0,
    0,
    &SecurityContext,
    BufferDescriptor,
    &ContextAttributes,
    &TimeStamp
    );

The arguments to InitializeSecurityContext are the following:

• Arg1 = Credentials handle received from AcquireCredentialsHandle call.

• Arg2 = Old Context handle if any.

• Arg3 = Target server name, which is ignored by NTLM SSP.

• Arg4 = Context Attributes Requested (See SSPI.H for valid values).

• Arg5 = Reserved Parameter.

• Arg6 = Data Representation (see SSPI.H for valid values).

• Arg7 = Input Buffer Descriptor (if there is one received from the server).

• Arg8 = Reserved Parameter.

• Arg9 = New Context Handle.

• Arg10 = Output Buffer Descriptor (contains what will be sent to the server).

• Arg11 = Context Attributes that are supported by the provider.

• Arg12 = TimeStamp for the lifespan of context validity.

The client then uses the security token information received in the output buffer descriptor to generate a message to send to the server. The construction of the message in terms of placement of various buffers and so forth, is part of the application protocol and should be understood between the two parties.

The client checks the return status from InitializeSecurityContext to see if authentication will complete in a single call. Otherwise it expects to receive a server-side authentication token in a response message to continue the security protocol. The return status SEC_I_CONTINUE_NEEDED, indicates the security protocol requires multiple authentication messages.

25.6.2    Server Context Initialization

To establish an authenticated connection, the server needs to acquire a credentials handle so that it can receive an incoming authentication request from the client. The server's credentials may be used to authenticate the server in security protocols that support server authentication or mutual authentication. When a connection request is received, the server creates a local security context to represent the client. The server uses the security context to carry out future requests by the same client.

First, the server obtains a handle to its credentials, which may be defined by the service account used to start the server. It does so by calling AcquireCredentialsHandle as follows:

//
// Acquire an out-bound Credentials handle using the chosen security package.
//
SecurityStatus = (*SecurityInterface->AcquireCredentialsHandle)(
     0,
     SecurityPackages[PkgToUseIndex].Name,
     SECPKG_CRED_INBOUND,
     0,
     0,
     0,
     0,
     &Credentials,
     &TimeStamp
     );

The arguments to the server-side call to AcquireCredentialHandle are as follows:

• Arg1 = Principal Name, set to NULL here to let the security package use the default

• Arg2 = Security Package Name, set to the one that was selected at initialization

• Arg3 = Type of credentials, inbound for a server, use SECPKG_CRED_BOTH if this server is going to be a client to another server.

• Arg4 = Pointer to LogonID (set to NULL to let the security package use the default).

• Arg5 = AuthIdentity Package specific authentication data. Since NTLM does not support server authentication, this can be NULL. For other security providers, this can be server authentication data, such as public key credentials.

• Arg6 = GetKey function (set to NULL)

• Arg7 = Any argument to the GetKey function (also set to NULL)

• Arg8 = Returned Credentials Handle.

• Arg9 = Returned TimeStamp which indicates the life span of the credentials handle.

The returned Credentials Handle should be assigned to a global variable that is used for the lifetime of the server process. The returned TimeStamp is a temporary variable.

The server can wait (in a listen state) until a connection request arrives before acquiring an inbound credentials handle or it may acquire the handle and then go into a listen state.

When the server receives a connection request message from a client, it creates a security context for the client using AcceptSecurityContext. The server initializes the SecurityBufferDescriptors to refer to sections of the data message received, rather than copying data to an alternate buffer.

The following example shows the call to AcceptSecurityContext.

//
// Set up the Input and OutputBuffer Descriptor using the information from message received
// from the client.
//
OutBufferDesc.ulVersion = 0;
OutBufferDesc.cBuffers = 1;
OutBufferDesc.pBuffers = &OutSecBuffer;
OutSecBuffer.cbBuffer = BufferLen;
OutSecBuffer.BufferType = SECBUFFER_TOKEN;
OutSecBuffer.pvBuffer = Buffer;
InBufferDesc.ulVersion = 0;
InBufferDesc.cBuffers = 1;
InBufferDesc.pBuffers = &InSecBuffer;
InSecBuffer.cbBuffer = InBufferLen;
InSecBuffer.BufferType = SECBUFFER_TOKEN;
InSecBuffer.pvBuffer = InBuffer;
//
// Lets initialize client's context from the SSP and see if 
// we need to send anything back to the client
//
SecurityStatus = (*SecurityInterface->AcceptSecurityContext(
    Credentials,
    0,
    InputBufferDescriptor,
    ISC_REQ_USE_DCE_STYLE | ISC_REQ_DELEGATE |
    ISC_REQ_MUTUAL_AUTH |ISC_REQ_REPLAY_DETECT |
    ISC_REQ_SEQUENCE_DETECT |ISC_REQ_CONFIDENTIALITY |
    ISC_REQ_CONNECTION,
    DataRepresentation,
    &SecurityContext,
    OutputBufferDescriptor,
    &ContextAttributes,
    &TimeStamp
    );

The arguments to AcceptSecurityContext are as follows:

• Arg1 = Credentials handle returned from the AcquireCredentialsHandle call.

• Arg2 = Old Context handle if any.

• Arg3 = Input Buffer Descriptor (if there is one received from client).

• Arg4 = Context Attributes Requested (See Section 25.7.5 below for more information).

• Arg5 = Data Representation (see SSPI.H for valid values).

• Arg6 = New Context Handle.

• Arg7 = Output Buffer Descriptor, containing what will be sent back to the client.

• Arg8 = Context Attributes that are supported by the provider.

• Arg9 = TimeStamp for the lifespan of context validity.

The server checks the return status and output buffer descriptor to ensure there are no errors so far, otherwise it rejects the connection request. If there is information in the output buffer it bundles it into a response message to the client as per the application protocol.

If the return status requires the protocol to continue (SEC_I_CONTINUE_NEEDED or SEC_I_COMPLETE_AND_CONTINUE), then another message exchange with the client is required. Otherwise the authentication is complete. For third leg, the server waits for the client to respond with another message. Note that this wait maybe timed out so as to avoid a denial of service attack (a malicious client may never respond hanging this server thread, and soon it will hang all server threads!!).

25.6.3    Client Continuation

On receipt of the response from the server, the client decomposes the message and, using the continue status from the previous call, it calls InitializeSecurityContext again:

if(SecurityStatus == SEC_I_CONTINUE_NEEDED || SecurityStatus = SEC_I_COMPLETE_AND_CONTINUE)
{
//
// Set up the Input and OutputBuffer Descriptor using the information from message 
// received from the server.
//
OutBufferDesc.ulVersion = 0;
OutBufferDesc.cBuffers = 1;
OutBufferDesc.pBuffers = &OutSecBuffer;
OutSecBuffer.cbBuffer = BufferLen;
OutSecBuffer.BufferType = SECBUFFER_TOKEN;
OutSecBuffer.pvBuffer = Buffer;
InBufferDesc.ulVersion = 0;
InBufferDesc.cBuffers = 1;
InBufferDesc.pBuffers = &InSecBuffer;
InSecBuffer.cbBuffer = InBufferLen;
InSecBuffer.BufferType = SECBUFFER_TOKEN;
InSecBuffer.pvBuffer = InBuffer;
//
// 
SecurityStatus = (*SecurityInterface->InitializeSecurityContext(
    0,
    &SecurityContext,
    0,
    0,
    0,
    DataRepresentation,
    InputBufferDescriptor,
    0,
    &SecurityContext,
    OutputBufferDescriptor,
    &ContextAttributes,
    &TimeStamp
    );
}

The client checks the return status from this call and may be required to continue for another leg. It uses the information in the OutputBufferDescriptor to construct a message and sends it to the server.

25.6.4    Server Continuation

The server should be waiting for the response based on the return code from previous call to AcquireSecurityContext. To continue the authentication protocol, the server also calls AcceptSecurityContext again.

if(SecurityStatus = SEC_I_CONTINUE_NEEDED || SecurityStatus = SEC_I_COMPLETE_AND_CONTINUE)
{
//
// Set up the Input and OutputBuffer Descriptor using the information from message
// receivedfrom the client.
//
OutBufferDesc.ulVersion = 0;
OutBufferDesc.cBuffers = 1;
OutBufferDesc.pBuffers = &OutSecBuffer;
OutSecBuffer.cbBuffer = BufferLen;
OutSecBuffer.BufferType = SECBUFFER_TOKEN;
OutSecBuffer.pvBuffer = Buffer;
InBufferDesc.ulVersion = 0;
InBufferDesc.cBuffers = 1;
InBufferDesc.pBuffers = &InSecBuffer;
InSecBuffer.cbBuffer = InBufferLen;
InSecBuffer.BufferType = SECBUFFER_TOKEN;
InSecBuffer.pvBuffer = InBuffer;
//
// Lets do the next leg of client's context initialization from the security package and see if we need
// to send anything back to the client
//
SecurityStatus = (*SecurityInterface->AcceptSecurityContext(
    0,
    &SecurityContext,
    InputBufferDescriptor,
    0,
    DataRepresentation,
    &SecurityContext,
    OutputBufferDescriptor,
    &ContextAttributes,
    &TimeStamp
    );
}

The return status is checked to see if the server needs to wait for another leg from the client. In most existing authentication protocols this is the maximum even for mutual authentication. NTLM security package performs client authentication and Kerberos security package does mutual authentication in three legs.

25.7    Secure Message Exchange

The Microsoft SSPI provides message APIs that can be used to ensure application protocol message integrity. Message privacy APIs (data encryption) are not exposed directly but a particular provider may expose them and document them separately.

If the application wants to generate signed messages, the client must have specified the ISC_REQ_REPLAY_DETECT or ISC_REQ_SEQUENCE_DETECT flag as the Context Attributes argument in the first call to the InitializeSecurityContext function.

After an authenticated connection has been established, the security support providers on each side establish a common session key that is used to sign messages on the sending side and to verify messages on the receiving side. The algorithms used in message signatures are private to the security package.

The SSPI message APIs are the following:

• MakeSignature--Generates a secure signature based on a message and a security context.

• VerifySignature--Verifies that the signature matches a received message.

  The message APIs provide integrity for application data messages. MakeSignature generates a checksum of the message and also includes sequencing information to prevent message loss or insertion. The next sections show how the sender and receiver use the SSPI Message APIs.

25.7.1    Sender

The sender of a message calls MakeSignature API to get a signature for the message and appends it to the message at an appropriate place so that the receiver is able to extract it on receipt:

//
// Setup the Buffer Descriptors.
//
OutBufferDesc.ulVersion = 0;
OutBufferDesc.cBuffers = 2;
OutBufferDesc.pBuffers = &OutSecBuffer;
OutSecBuffer[0].cbBuffer = MessageLen;
OutSecBuffer[0].BufferType = SECBUFFER_DATA | SECBUFFER_READONLY;
OutSecBuffer[0].pvBuffer = Message;
OutSecBuffer[1].cbBuffer = SignatureLen;
OutSecBuffer[1].BufferType = SECBUFFER_EMPTY;
OutSecBuffer[1].pvBuffer = (Message + MessageLen); // just after the message
//
// Now call MakeSignature API to get it signed.
//
SecurityStatus = (*SecurityInterface->MakeSignature)(
     &SecurityContext,
0,
BufferDescriptor,
Sequence
);

The arguments to MakeSignature are the following:

• Arg1 = Context Handle for the active security context

• Arg2 = Quality of protection

• Arg3 = Buffer descriptor containing the message for signing.

• Arg4 = Sequence number of the message if sequence detection is on.

The sender then uses the buffer descriptor (including the signature) to construct a message to send to the receiver.

The quality of protection value allows applications to select different cryptographic algorithms supported by the security package. By default NTLM does not support this parameter. Other security packages, however, may provide different quality of protection options.

25.7.2    Receiver

The receiver takes the message and breaks it down to create the buffer descriptor as before. It then passes this buffer descriptor on to the VerifySignature API to verify the message integrity.

//
// Setup the Buffer Descriptors.
//
InBufferDesc.ulVersion = 0;
InBufferDesc.cBuffers = 2;
InBufferDesc.pBuffers = &InSecBuffer;
InSecBuffer[0].cbBuffer = MessageLen;
InSecBuffer[0].BufferType = SECBUFFER_DATA | SECBUFFER_READONLY;
InSecBuffer[0].pvBuffer = Message;
InSecBuffer[1].cbBuffer = SignatureLen;
InSecBuffer[1].BufferType = SECBUFFER_TOKEN;
InSecBuffer[1].pvBuffer = (Message + MessageLen); // just after the message
//
// Now call MakeSignature API to get it signed.
//
SecurityStatus = (*SecurityInterface->VerifySignature)(
     &SecurityContext,
BufferDescriptor,
Sequence,
&QualityOfProtection
);

The arguments to VerifySignature are the following:

• Arg1 = Context Handle for the active context

• Arg2 = Buffer descriptor containing received message

• Arg3 = Sequence number expected for the received message

• Arg4 = Quality of protection on the message (if any)

Once the receiver is ensured of the authenticity and integrity of the message, the receiver is free to use it as per the application protocol.

25.7.3    Impersonation

An important aspect of client/server communication besides authentication and message exchange is the ability of a server to determine whether it should service the client's request. A large number of servers run under system's context and therefore have far more privileges and abilities than a typical client requesting service. An example of this is a network file server which has full access to all files, whereas requesting users may not. Therefore, the server should carry out a client request if and only if the client has sufficient access rights for the requested service.

There are two approaches for determining whether a client has sufficient access rights for the operation: an access check by the server, or an access check by the system. The brute force approach builds the logic of doing authorization checks for client access into the server. The server code uses authorization information, for example, from a separate authorization file, and determines if the client has sufficient rights to perform the requested operation.

SSPI provides an API, ImpersonateSecurityContext, that allows a server to impersonate the client's security context as well as to revert back to its own security context (RevertSecurityContext) when done servicing.

The example below shows how to use ImpersonateSecurityContext and RevertSecurityContext APIs:

//
// When accessing a resource on behalf the client, we need to 
// impersonate the client so that appropriate access check is done.
//
SecurityStatus = (*SecurityInterface->ImpersonateSecurityContext) (&SecurityContext);
if(SecurityStatus != SEC_E_OK)
{
 //
 // We have a problem...
 // This security context is not at least impersonation level.
 //
 return error;
}
//
// At this point the calling thread is under an impersonation token with client's credentials
//
//
// Process the request..
//
. . .
//
// Revert to primary token once we are done.
//
SecurityStatus = (*SecurityInterface->RevertSecurityContext)(&SecurityContext);
if(SecurityStatus != SEC_E_OK)
{
 //
 // check for any errors...
 //
 return error;
}
//
// The server thread is back to its original context.
//

25.7.4    Using Delegation in Kerberos

The Kerberos authentication protocol supports delegation. When delegation is supported, the impersonating server can use the client's delegation level credentials to initialize a security context with a remote server to request a service on the client's behalf.

Consider how a client's security context, identified by C, is established on a server called Server 1. When Server 1 impersonates the client, the impersonation context on Server 1 is identified as C/S1. Server 1 makes an off-machine connection to Server 2. Through the use of delegation, Server 2 is also able to impersonate the client's security context. Server 2's impersonation of the client is identified as C/S2.

The following example shows how delegation can be accomplished using SSPI:

//
// When accessing a resource on behalf the client, we need to impersonate the client so that
// appropriate access check is done.
//
SecurityStatus = (*SecurityInterface->ImpersonateSecurityContext)(&SecurityContext);
if(SecurityStatus != SEC_E_OK)
{
 //
 // We have a problem...
 // This security context is not at least impersonation level.
 //
 return error;
}
//
// At this point the calling thread is under an impersonation token with client's credentials
//
//
// Now we can call InitializeSecurityContext to get an authentication token with ``current''
// credentials (client's) to send to another remote server:
//
// Set up security buffers and the descriptor.
//
//
// Call InitializeSecurityContext...
// If this fails, then the client security context is not delegation level,
// WATCH OUT FOR THIS, and handle according to the application protocol.
//
//
// construct a message with the auth token from the SSP to send to the remote server.
// and send the message.
//
// Wait for the reply from the server.
//
//
// If SEC_I_CONTINUE_NEEDED is returned by the first call to Initialize, use
// the auth token returned by the remote server to call InitializeSecurityContext again.
//
if(SecurityStatus == SEC_I_CONTINUE_NEEDED || SecurityStatus = SEC_I_COMPLETE_AND_CONTINUE)
{
 //
 // Fill up Input security buffers and setup output security buffers.
 //
 //
 // call InitializeSecurityContext.
 //
 //
 // Convert the security buffers into a message.
 // and send the message.
 //
 //
 // wait for reply.
 //
}
//
// At this point the connection is established.
//
// 
// Request service from the remote server by exchanging messages. Note that
// the remote server will process these assuming that they are coming from the client.
//
. . .
//
// Once done, tear down the connection.
//
//
// Now, you may revert to primary token.
//
SecurityStatus = (*SecurityInterface->RevertSecurityContext)(&SecurityContext);
if(SecurityStatus != SEC_E_OK)
{
 //
 // check for any errors...
 //
 return error;
}
//
// The server thread is back to its original context.
//

25.7.5    Security Context Details

The Security Support Provider Interface model supports three types of security contexts, which are summarized in the following table.

Table 25-1:  Security Contexts

25.7.5.1    Connection-Oriented Contexts

With a connection-oriented context, the caller of the function is responsible for formatting messages. The caller also relies on the security provider to authenticate connections, and to ensure the integrity of specific parts of the message. Most of the range of context options are available to connection-oriented contexts. These options include mutual authentication, replay detection, and sequence detection, as described in Context Requirements.

A security package sets the SECPKG_FLAG_CONNECTION flag to indicate that it supports connection-oriented semantics.

25.7.5.2    Datagram Contexts

Datagram, or connectionless, contexts have slightly different semantics from connection-oriented contexts. A connectionless context implies that the server has no way of determining when the client has shut down or otherwise terminated the connection. In other words, no termination notice is passed from the transport application to the server, as would occur in a connection context. To better support some models, particularly DCE-style RPC, the following rules apply when the client specifies the ISC_REQ_DATAGRAM flag in its call to the InitializeSecurityContext function:

• The security package does not produce an authentication blob (binary large object) on the first call to the InitializeSecurityContext function. However, the client can immediately use the returned security context in a call to the MakeSignature function to generate a signature for a message.

• The security package must allow for the context to be re-established multiple times to allow the server to drop the connection without notice. This also implies that any keys used in the MakeSignature and VerifySignature functions can be reset to a consistent state.

• The security package must allow for the caller to specify sequence information, and must provide it back again at the other end. This is not exclusive of any sequence information maintained by the package and can be viewed as a special payload.

A security package sets the SECPKG_FLAG_DATAGRAM flag to indicate that it supports datagram semantics.

25.7.5.3    Stream Contexts

Stream contexts are quite different from either connection or datagram contexts. Stream contexts were introduced to handle the secure streams-oriented protocols such as SSL or PCT.

In the interest of sharing the same interface, similar credential management, and so on, the Security Support Provider Interface has been extended to provide support for stream contexts. The security protocol incorporated both the authentication scheme, and the record formats. This posed a problem to the typical implementation, which required the blocking to be done by the caller.

To satisfy the requirements of the stream-oriented protocols, a security package that supports stream contexts has the following characteristics:

• The package sets the SECPKG_FLAG_STREAM flag to indicate that it supports stream semantics, just as it would set a flag to indicate support for connection and datagram semantics.

• A transport application requests stream semantics by setting the ISC_REQ_STREAM and ASC_REQ_STREAM flags in the calls to the InitializeSecurityContext and AcceptSecurityContext functions.

• The application calls the QueryContextAttributes function with a SecPkgContext_StreamSizes structure to query the security context for the number of buffers to provide, and the sizes to reserve for headers or trailers.

• The application provides buffer descriptors to spare during the actual processing of the data.

Obviously, the final item is of the most interest. By specifying stream semantics, the caller is indicating a willingness to do extra work so the security provider can handle the blocking of the messages.

In essence, for the MakeSignature and VerifySignature functions, the caller passes in a list of buffers. When a message is received from a channel that is stream-oriented (such as a TCP port), the caller passes in a buffer list as follows:

Table 25-2:  Buffer Lists

The security package then goes to work on the blob. If the function returns successfully, the buffer list looks like this:

Table 25-3:  Buffer List after Successful Return

The provider could have also returned buffer #4 as follows:

This indicates that the data in this buffer is part of the next record, and has not yet been processed.

Conversely, if the message function returns the SEC_E_INCOMPLETE_MESSAGE error code, the returned buffer list would look like this:

This indicates that more data was needed to process the record. Unlike most errors returned from a message function, this buffer type does not indicate that the context has been compromised, just that more data is needed. Security providers must not update their state in this condition.

Similarly, on the send side of the communication, the caller can simply call the MakeSignature function, in which case the security package may need to reallocate the buffer, copy things around, and so on. Or the caller can be more efficient by providing a buffer list as follows:

This allows the caller to use the buffers more efficiently. By calling the QueryContextAttributes function to determine the amount of space to reserve before calling MakeSignature, the operation is more efficient for the application and the security package.

25.7.5.4    Context Requirements

Context requirements are expressed as a combination of bit flags, passed to either the InitializeSecurityContext or AcceptSecurityContext function. These flags affect the context in a number of ways, and are detailed in the following table. Not all flags apply to all contexts; some are valid only for the server, others only for the client.

The caller uses the fContextReq parameter of the InitializeSecurityContext or AcceptSecurityContext call to specify a set of flags that indicate the required capabilities. When the function returns, the pfContextAttr parameter indicates the attributes of the established context. The caller is responsible for determining whether the final context attributes are acceptable. For example, if the caller requested mutual authentication, but the security package indicates that it was not or could not be performed, the caller must decide whether to cancel the context or continue on.

The following table describes the various context requirements.

Table 25-4:  Context Requirements

25.8    Datatype Descriptions

25.8.1    BINDPTR

A union containing a pointer to a FUNCDESC, VARDESC, or an ITypeComp() interface. It is defined as follows:

typedef union tagBINDPTR {
    FUNCDESC FAR* lpfuncdesc;
    VARDESC FAR* lpvardesc;
    ITypeComp FAR* lptcomp;
} BINDPTR;

25.8.2    BOOL

Boolean variable (should be TRUE or FALSE).

typedef long BOOL;

25.8.3    BSTR

A length-prefixed string used by Automation data manipulation functions.

typedef OLECHAR *BSTR;

BSTRs are wide, double-byte (Unicode) strings on 32-bit Windows platforms and narrow, single-byte strings on the Apple^® PowerMac^(TM).

typedef [wire_marshal( wireBSTR )] OLECHAR *  BSTR;

25.8.4    BYTE

BYTE is an unsigned character data type that is binary data.

typedef unsigned char     BYTE;

25.8.5    CLIPFORMAT

typedef
union _userCLIPFORMAT switch(long fContext) u
{
    case WDT_INPROC_CALL:	     DWORD     dwValue;
    case WDT_REMOTE_CALL:   [string] wchar_t * pwszName;
} userCLIPFORMAT;
typedef [unique] userCLIPFORMAT *  wireCLIPFORMAT;
typedef [wire_marshal(wireCLIPFORMAT)] WORD  CLIPFORMAT;

25.8.6    CONST

Variable that remains constant during an execution.

#define CONST const

25.8.7    CUSTDATA

Used for retrieving custom data. It is defined as follows:

typedef struct  tagCUSTDATA
    {
    DWORD cCustData;
    /* [size_is] */ LPCUSTDATAITEM prgCustData;
    }    CUSTDATA;

The following table describes the fields of the CUSTDATA structure.

25.8.8    DISPID

Used by IDispatch::Invoke() to identify methods, properties, and arguments.

typedef LONG DISPID;

The following dispatch identifiers (DISPIDs) have special meaning.

Note: The reserved DISPIDs are:

• DISPID_Name-800

• DISPID_Delete-801

• DISPID_Object-802

• DISPID_Parent-803

25.8.9    DISPPARAMS

Used by IDispatch::Invoke() to contain the arguments passed to a method or property.

typedef struct FARSTRUCT tagDISPPARAMS{
VARIANTARG FAR* rgvarg;               // Array of arguments.
    DISPID FAR* rgdispidNamedArgs;    // Dispatch IDs of named arguments.
    unsigned int cArgs;               // Number of arguments.
    unsigned int cNamedArgs;          // Number of named arguments.
} DISPPARAMS;

25.8.10    DWORD

A 32-bit unsigned integer or the address of a segment and its associated offset.

typedef unsigned long DWORD;

25.8.11    FAR *

Defined to nothing.

#define far
#define FAR far

25.8.12    FUNCDESC

Describes a function, and is defined as follows:

typedef struct tagFUNCDESC {
    MEMBERID memid;         // Function member ID.
/* [size_is] */ SCODE __RPC_FAR *lprgscode;
/* [size_is] */ ELEMDESC __RPC_FAR *lprgelemdescParam;
    FUNCKIND funckind;      // Specifies whether the
                            // function is virtual, static,
                            // or dispatch-only.
    INVOKEKIND invkind;     // Invocation kind. Indicates if this is a
                            // property function, and if so, what kind.
    CALLCONV callconv;      // Specifies the function's calling 
                            // convention.
    short cParams;          // Count of total number of parameters.
    short cParamsOpt;       // Count of optional parameters (detailed
                            // description follows).
    short oVft;             // For FUNC_VIRTUAL, specifies the offset in
                            // the VTBL.
    short cScodes;          // Count of permitted return values. 
    ELEMDESC elemdescFunc;  // Contains the return type of the function.
    WORD wFuncFlags;        // Definition of flags follows.
}    FUNCDESC;

The cParams field specifies the total number of required and optional parameters. The cParamsOpt field specifies the form of optional parameters accepted by the function, as follows:

• A value of 0 specifies that no optional arguments are supported.

• A value of -1 specifies that the method's last parameter is a pointer to a safe array of variants. Any number of variant arguments greater than cParams -1 must be packaged by the caller into a safe array and passed as the final parameter. The caller must free this array of optional parameters after control is returned from the call.

• Any other number indicates that the last n parameters of the function are variants and do not need to be specified by the caller explicitly. The parameters left unspecified should be filled in by the compiler or interpreter as variants of type VT_ERROR with the value DISP_E_PARAMNOTFOUND. For 16-bit systems (Macintosh), the fields cScodes and lprgscode store the count and the set of errors that a function can return. If cScodes = -1, then the set of errors is unknown. If cScodes = -1, or if cScodes = 0, then lprgscodeis undefined.

25.8.13    HANDLE

A pointer to any type.

typedef void *HANDLE;

25.8.14    HBITMAP

Handle to a bitmap.

typedef HANDLE HBITMAP;

25.8.15    HENHMETAFILE

Handle to an enhanced metafile.

typedef HANDLE HENHMETAFILE;

25.8.16    HGLOBAL

Handle to a global memory block.

typedef HANDLE HGLOBAL;

25.8.17    HINSTANCE

Handle to an instance.

typedef HANDLE HINSTANCE;

25.8.18    HKEY

Handle to a registry key.

typedef HANDLE HKEY;

25.8.19    HMETAFILEPICT

typedef
struct _remoteMETAFILEPICT
{
    long            mm;
    long            xExt;
    long            yExt;
    userHMETAFILE * hMF;
} remoteMETAFILEPICT;
typedef union _userHMETAFILEPICT switch( long fContext ) u
{
    case WDT_INPROC_CALL:   long                hInproc;
    case WDT_REMOTE_CALL:   remoteMETAFILEPICT* hRemote;
    default:                long                hGlobal;
} userHMETAFILEPICT;

25.8.20    HREFTYPE

A handle that identifies a type description.

typedef unsigned long HREFTYPE;

25.8.21    HTASK

A handle to a task.

typedef HANDLE HTASK;

25.8.22    HUGEP

#ifndef HUGEP
#if defined(_WIN32) || defined(_MPPC_)
#define HUGEP
#else
#define HUGEP __huge
#endif // WIN32
#endif // HUGEP

25.8.23    INVOKEKIND

Defined as follows:

typedef enum tagINVOKEKIND {
    INVOKE_FUNC = DISPATCH_METHOD,
    INVOKE_PROPERTYGET = DISPATCH_PROPERTYGET,
    INVOKE_PROPERTYPUT = DISPATCH_PROPERTYPUT,
    INVOKE_PROPERTYPUTREF = DISPATCH_PROPERTYPUTREF
} INVOKEKIND;

In C, value assignment is written as *pobj1 = *pobj2, while reference assignment is written as pobj1 = pobj2. Other languages have other syntactic conventions. A property or data member can support only a value assignment, a reference assignment, or both. The INVOKEKIND enumeration constants are the same constants that are passed to IDispatch::Invoke() to specify the way in which a function is invoked.

25.8.24    IPID

Interface pointer identifier. It is identical to a GUID.

typedef GUID IPID;

25.8.25    LANGID

Language identifier.

The first release of Windows NT supports 35 sublanguages/locales. The following 28 sublanguages/locales use the Latin 1 script:

Table 25-5:  Sublanguages Using the Latin 1 Script

The following 5 sublanguages/locales use the Latin 2 script:

Table 25-6:  Sublanguages Using Latin 2 Script

The following sublanguage/locale uses the Cyrillic script:

Table 25-7:  Sublanguages and Locales Using Cyrillic Script

The following sublanguage/locale uses the Other script:

Table 25-8:  Sublanguages and Locales Using Other Script

The following special identifiers are also defined:

Table 25-9:  Special Identifiers

25.8.26    LCID

Identifies a locale for national language support. Locale information is used for international string comparisons and localized member names.

typedef unsigned long LCID;

25.8.27    LCTYPE

An LCTYPE constant is a constant that specifies a particular piece of locale information. The values in the following list correspond to the names of these values in the configuration registry, under both the user's preferences (as values in the registry key HKEY_CURRENT_USER\Control Panel\International) and the system's installed languages (as files pointed to by registry keys, one key per language installed, under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\NLS). All values are null-terminated Unicode^(TM) strings. If no maximum length is indicated, the strings may vary in length.

Table 25-10:  LCTYPE Values

Table 25-11:  LOCALE_ILZERO Values

Table 25-12:  LCTYPE Values (continued)

Table 25-13:  LOCALE_INEGNUMBER Values

Table 25-14:  LCTYPE Values (continued)

Table 25-15:  LOCALE_ICURRENCY Values

Table 25-16:  LCTYPE Values (continued)

Table 25-17:  LOCALE_INEGCURR Values

Table 25-18:  LCTYPE Values (continued)

Table 25-19:  LOCALE_IDATE Values

Table 25-20:  LCTYPE Values (continued)

Table 25-21:  LOCALE_ILDATE Values

Table 25-22:  LCTYPE Values (continued)

Table 25-23:  LOCALE_ITIME Values

Table 25-24:  LCTYPE Values (continued)

Table 25-25:  LOCALE_ICENTURY Values

Table 25-26:  LCTYPE Values (continued)

Table 25-27:  LOCALE_ITLZERO Values

Table 25-28:  LCTYPE Values (continued)

Table 25-29:  LOCALE_IDAYLZERO Values

Table 25-30:  LCTYPE Values (continued)

Table 25-31:  LOCALE_IMONLZERO Values

Table 25-32:  LCTYPE Values (continued)

Table 25-33:  LOCALE_S1159 Values

Table 25-34:  LCTYPE Values (continued)

Table 25-35:  LOCALE_IOPTIONALCALENDAR Values

Table 25-36:  LCTYPE Values (continued)

Table 25-37:  LOCALE_IFIRSTDAYOFWEEK Values

Table 25-38:  LCTYPE Values (continued)

Table 25-39:  LOCALE_IFIRSTWEEKOFYEAR Values

Table 25-40:  LCTYPE Values (continued)

Table 25-41:  LOCALE_IPOSSIGNPOSN Values

Table 25-42:  LCTYPE Values (continued)

25.8.28    LONG

32-bit signed integer.

typedef long LONG;

25.8.29    LPBC

A pointer to a Bind Context.

typedef [unique] IbindCtx *LPBC;

25.8.30    LPBYTE

Pointer to a BYTE.

typedef unsigned char FAR *LPBYTE;

25.8.31    LPCLSID

A pointer to a class ID.

typedef CLSID *LPCLSID;

25.8.32    LPCOLESTR

A pointer to an OLECHAR array.

typedef [string] const OLECHAR *LPOLESTR;

25.8.33    LPCTSTR

Pointer to a constant null-terminated Unicode or Windows character string.

typedef const TCHAR FAR *LPCTSTR;

25.8.34    LPCWSTR

Pointer to a constant null-terminated Unicode character string.

typedef [string] const WCHAR *LPCWSTR;

25.8.35    LPDWORD

Pointer to a DWORD.

typedef DWORD *LPDWORD;

25.8.36    LPIID

A pointer to an interface identifier.

typedef IID *LPIID;

25.8.37    LPMALLOC

A pointer to an IMalloc() interface.

typedef [unique] IMalloc() *LPMALLOC;

25.8.38    LPMALLOCSPY

A pointer to an IMallocSpy() interface.

typedef [unique] IMallocSpy() *LPMALLOCSPY;

25.8.39    LPMARSHAL

A pointer to an IMarshal() interface.

typedef [unique] IMarshal() *LPMARSHAL;

25.8.40    LPMONIKER

A pointer to an IMoniker() interface.

typedef [unique] IMoniker() *LPMONIKER;

25.8.41    LPOLESTR

A pointer to an OLECHAR array.

typedef [string] OLECHAR *LPOLESTR;

25.8.42    LPRUNNINGOBJECTTABLE

A pointer to the running object table interface.

Typedef [unique] IRunningObjectTable() *LPRUNNINGOBJECTTABLE;

25.8.43    LPSECURITY_ATTRIBUTES

typedef
struct _SECURITY_ATTRIBUTES {
    DWORD nLength;
    [size_is(nLength)] LPVOID lpSecurityDescriptor;
    BOOL bInheritHandle;
} SECURITY_ATTRIBUTES, *PSECURITY_ATTRIBUTES, *LPSECURITY_ATTRIBUTES;

25.8.44    LPSTR

Pointer to a null-terminated Windows character string.

typedef [string] CHAR *LPSTR;

25.8.45    LPSTREAM

Pointer to an IStream() interface.

typedef [unique] IStream() *LPSTREAM;

25.8.46    LPUNKNOWN

A pointer to an IUnknown() interface.

typedef [unique] IUnknown() *LPUNKNOWN;

25.8.47    LPVOID

Pointer to any type.

typedef void *LPVOID;

25.8.48    LPWORD

Pointer to a WORD.

typedef WORD *LPWORD;

25.8.49    LPWSTR

Pointer to a null-terminated Unicode character string.

typedef [string] WCHAR *LPWSTR;

25.8.50    MEMBERID

Identifies the member in a type description. For IDispatch() interfaces, this is the same as DISPID.

typedef DISPID MEMBERID;

This is a 32-bit integral value in the following format.

Table 25-43:  MEMBERID Format

Negative IDs are reserved for use by Automation.

25.8.51    OLECHAR

A wide character.

typedef WCHAR OLECHAR;

25.8.52    PFILETIME

typedef
struct _FILETIME
{
    DWORD dwLowDateTime;
    DWORD dwHighDateTime;
} FILETIME, *PFILETIME, *LPFILETIME;

25.8.53    PHKEY

Pointer to a registry key.

typedef HKEY FAR *PHKEY;

25.8.54    PROPID

A pointer to an unsigned long.

typedef ULONG PROPID;

25.8.55    PROPSPEC

The PROPSPEC structure is used by many of the methods of IPropertyStorage() to specify a property either by its property identifier or the associated string name. The structure and related definitions are defined as follows in the header files:

const ULONG    PRSPEC_LPWSTR = 0
const ULONG    PRSPEC_PROPID = 1
typedef ULONG    PROPID
typedef struct tagPROPSPEC 
{
    ULONG ulKind;        // PRSPEC_LPWSTR or PRSPEC_PROPID
    union 
    {
    PROPID      propid;
    LPOLESTR    lpwstr;
    }
} PROPSPEC

25.8.55.1    Members

ulKind

If ulKind is set to PRSPEC_LPWSTR, lpwstr is used and set to a string name. If ulKind is set to PRSPEC_PROPID, propid is used and set to a property identifier value.

propid

Specifies the value of the property identifier. Use either this value or the following lpwstr, not both.

lpwstr

Specifies the string name of the property as a null-terminated Unicode string.

25.8.55.2    Remarks

Header: Declared in objidl.h.

String names are optional and can be assigned to a set of properties when the property is created with a call to IPropertyStorage::WriteMultiple(), or later, with a call to IPropertyStorage::WritePropertyNames().

Windows NT:

Use version 4.0 or later.

Windows:

Use Windows 95 or later. Available as a redistributable for Windows 95.

Windows CE:

Unsupported.

25.8.56    PROPVARIANT

The PROPVARIANT structure is used in most of the methods of IPropertyStorage() to define the type tag and the value of a property in a property set. There are five members. The first, the value type tag, and the last, the value of the property, are significant. The middle three are reserved for future use. The PROPVARIANT structure is defined as follows:

struct PROPVARIANT{
    VARTYPE        vt;          // value type tag
    WORD           wReserved1;
    WORD           wReserved2;
    WORD           wReserved3;
    union { 
    // none                     // VT_EMPTY, VT_NULL, VT_ILLEGAL
    unsigned char  bVal;        // VT_UI1
    short          iVal;        // VT_I2
    USHORT         uiVal;       // VT_UI2
    long           lVal;        // VT_I4
    ULONG          ulVal;       // VT_UI4
    LARGE_INTEGER  hVal;        // VT_I8
    ULARGE_INTEGER uhVal;       // VT_UI8
    float          fltVal;      // VT_R4
    double         dblVal;      // VT_R8
    CY             cyVal;       // VT_CY
    DATE           date;        // VT_DATE
    BSTR           bstrVal;     // VT_BSTR  
    VARIANT_BOOL   boolVal;        // VT_BOOL
    SCODE          scode;       // VT_ERROR
    FILETIME       filetime;    // VT_FILETIME
    LPSTR          pszVal;      // VT_LPSTR     // string in the current system Ansi code page
    LPWSTR         pwszVal;     // VT_LPWSTR    // string in Unicode
    CLSID*         puuid;       // VT_CLSID
    CLIPDATA*      pclipdata;   // VT_CF
    BLOB           blob;        // VT_BLOB, VT_BLOBOBJECT
    IStream*       pStream;     // VT_STREAM, VT_STREAMED_OBJECT
    IStorage*      pStorage;    // VT_STORAGE, VT_STORED_OBJECT
    CAUB           caub;         // VT_VECTOR | VT_UI1
    CAI            cai;          // VT_VECTOR | VT_I2
    CAUI           caui;         // VT_VECTOR | VT_UI2
    CAL            cal;          // VT_VECTOR | VT_I4
    CAUL           caul;         // VT_VECTOR | VT_UI4
    CAH            cah;          // VT_VECTOR | VT_I8
    CAUH           cauh;         // VT_VECTOR | VT_UI8
    CAFLT          caflt;        // VT_VECTOR | VT_R4
    CADBL          cadbl;        // VT_VECTOR | VT_R8
    CACY           cacy;         // VT_VECTOR | VT_CY
    CADATE         cadate;       // VT_VECTOR | VT_DATE
    CABSTR         cabstr;       // VT_VECTOR | VT_BSTR
    CABOOL         cabool;       // VT_VECTOR | VT_BOOL
    CASCODE        cascode;      // VT_VECTOR | VT_ERROR
    CALPSTR        calpstr;      // VT_VECTOR | VT_LPSTR
    CALPWSTR       calpwstr;     // VT_VECTOR | VT_LPWSTR
    CAFILETIME     cafiletime;   // VT_VECTOR | VT_FILETIME
    CACLSID        cauuid;       // VT_VECTOR | VT_CLSID
    CACLIPDATA     caclipdata;   // VT_VECTOR | VT_CF
    CAPROPVARIANT  capropvar;    // VT_VECTOR | VT_VARIANT
    }} PROPVARIANT

The bool member in previous definitions of this structure has been renamed to boolVal, since some compilers now recognize bool as a keyword.

25.8.56.1    Remarks

Header: Declared in objidl.h.

PROPVARIANT is the fundamental data type by which property values are read and written through the IPropertyStorage() interface. The data type PROPVARIANT is related to the data type VARIANT, defined as part of Automation in OLE2 and defined in the Win32 SDK header file oleauto.h. Several definitions are reused from Automation, as follows:

typedef struct  tagCY {
    unsigned long      Lo;
    long               Hi;
    } CY
typedef CY             CURRENCY;
typedef short          VARIANT_BOOL;
typedef unsigned short VARTYPE;
typedef double         DATE;
typedef OLECHAR*       BSTR;
typedef struct         tagCLIPDATA {
    ULONG              cbSize;  //Includes sizeof(ulClipFmt)
    long               ulClipFmt;
    BYTE*              pClipData;
    } CLIPDATA

In addition, several new data types that define counted arrays of other data types are required. The data types of all counted arrays begin with the letters CA (such as CAUB) and have an ORed vt value. The counted array structure has the following form (where name is the specific name of the counted array):

#define TYPEDEF_CA(type, name) 
    typedef struct tag ## name {\
        ULONG cElems;\
        type *pElems;\
        } name

Table 25-44:  PROPVARIANT Types

Clipboard format identifiers, stored with the tag VT_CF, use one of five different representations (identified in the ulClipFmt member of the CLIPDATA structure):

Table 25-45:  Clipboard Format Identifiers

Within a vector of values, each repetition of a value is to be aligned to 32-bit boundaries. The exception to this rule is scalar types which are less than 32 bits: VT_UI1, VT_12, VT_U12, and VT_BOOL. Vectors of these values are packed. Therefore, a value with type tag VT_I2 | VT_VECTOR would be a DWORD element count, followed by a sequence of packed 2-byte integers with no padding between them. However, a value with type tag VT_LPSTR | VT_VECTOR would be a DWORD element count, followed by a sequence of (DWORD cch, char rgch[]) strings, each of which may be followed by null padding to round to a 32-bit boundary.

Windows NT:

Use version 4.0 or later.

Windows:

Use Windows 95 or later. Available as a redistributable for Windows 95.

Windows CE:

Unsupported.

25.8.57    PSECURITY_DESCRIPTOR

A pointer to a security descriptor.

typedef PVOID PSECURITY_DESCRIPTOR;

25.8.58    PULONG

Pointer to an unsigned long (32 bits).

typedef ULONG *PULONG;

25.8.59    PVALENT

typedef
struct value_entA {
    LPSTR   ve_valuename;
    DWORD ve_valuelen;
    DWORD ve_valueptr;
    DWORD ve_type;
}VALENTA, FAR *PVALENTA;
typedef struct value_entW {
    LPWSTR  ve_valuename;
    DWORD ve_valuelen;
    DWORD ve_valueptr;
    DWORD ve_type;
}VALENTW, FAR *PVALENTW;
#ifdef UNICODE
typedef VALENTW VALENT;
typedef PVALENTW PVALENT;
#else
typedef VALENTA VALENT;
typedef PVALENTA PVALENT;
#endif // UNICODE

25.8.60    PVOID

Pointer to any type.

typedef void *PVOID;

25.8.61    PWCHAR

Pointer to a Unicode character.

typedef WCHAR *PWCHAR;

25.8.62    REFCLSID

A pointer to a class ID.

typedef CLSID *REFCLSID;

25.8.63    REFFMTID

A pointer to an FMTID.

typedef FMTID *REFFMTID;

25.8.64    REFGUID

A pointer to a globally unique identifier.

typedef GUID *REFGUID;

25.8.65    REFIID

A pointer to an interface identifier.

typedef IID *REFIID;

25.8.66    REGKIND

Controls how a type library is registered. It is defined as follows:

typedef enum tagREGKIND{
    REGKIND_DEFAULT,
    REGKIND_REGISTER,
    REGKIND_NONE
} REGKIND;

Table 25-46:  REGKIND Values

25.8.67    REGSAM

Data type used for specifying the security access attributes in the registry. A REGSAM value can be one or more of the following values:

KEY_ALL_ACCESS

Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, KEY_CREATE_SUB_KEY, KEY_CREATE_LINK, and KEY_SET_VALUE access.

KEY_CREATE_LINK

Permission to create a symbolic link.

KEY_CREATE_SUB_KEY

Permission to create subkeys.

KEY_ENUMERATE_SUB_KEYS

Permission to enumerate subkeys.

KEY_EXECUTE

Permission for read access.

KEY_NOTIFY

Permission for change notification.

KEY_QUERY_VALUE

Permission to query subkey data.

KEY_READ

Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access.

KEY_SET_VALUE

Permission to set subkey data.

KEY_WRITE

Combination of KEY_SET and KEY_CREATE_SUB_KEY access.

25.8.68    RPC_AUTH_IDENTITY_HANDLE

typedef
void * RPC_AUTH_IDENTITY_HANDLE;

An identity handle points to the data structure that contains the client's authentication and authorization credentials specified for remote procedure calls.

25.8.69    RPC_AUTHZ_HANDLE

A pointer to the authorization service.

typedef void __RPC_FAR *RPC_AUTHZ_HANDLE;

25.8.70    RPC_FAR

Defined to nothing.

#define RPC_FAR

25.8.71    RPCOLEMESSAGE

typedef
struct tagRPCOLEMESSAGE
    {
        void             *reserved1;
        RPCOLEDATAREP     dataRepresentation;
        void             *Buffer;
        ULONG             cbBuffer;
        ULONG             iMethod;
        void             *reserved2[5];
        ULONG             rpcFlags;
    } RPCOLEMESSAGE;

25.8.72    SECURITY_INFORMATION

Header: Declared in winnt.h.

The SECURITY_INFORMATION structure identifies the object-related security information being set or queried. This security information includes:

• The owner of an object

• The primary group of an object

• The discretionary access-control list (ACL) of an object

• The system ACL of an object

  typedef DWORD SECURITY_INFORMATION;
  

  Each item of security information is designated by a bit flag. The following values specify the bits:

Table 25-47:  Security Information Bit Flags

Windows NT:

Use version 3.1 or later.

Windows:

Unsupported.

Windows CE:

Unsupported.

25.8.73    SIZEL

typedef
struct tagSIZEL
{
    LONG cx;
    LONG cy;
} SIZEL, *PSIZEL, *LPSIZEL;

25.8.74    SOLE_AUTHENTICATION_SERVICE

Header: Declared in objidl.h.

Identifies an authentication service. This structure is retrieved through a call to CoQueryAuthenticationServices(), and passed in to CoInitializeSecurity().

typedef struct tagSOLE_AUTHENTICATION_SERVICE {
        DWORD       dwAuthnSvc;
        DWORD       dwAuthzSvc;
        OLECHAR*    pPrincipalName;
        HRESULT     hr;
    } SOLE_AUTHENTICATION_SERVICE;

25.8.74.1    Members

dwAuthnSvc

The authentication service. It may contain a single value taken from the list of RPC_C_AUTHN_xxx constants defined in rpcdce.h. RPC_C_AUTHN_NONE turns off authentication. On Win32, RPC_C_AUTHN_DEFAULT causes COM to use the RPC_C_AUTHN_WINNT authentication.

dwAuthzSvc

The authorization service. It may contain a single value taken from the list of RPC_C_AUTHZ_xxx constants defined in rpcdce.h. The validity and trustworthiness of authorization data, like any application data, depends on the authentication service and authentication level selected. This parameter is ignored when using the RPC_C_AUTHN_WINNT authentication service.

pPrincipalName

Principal name to be used with the authentication service. If the principal name is NULL, COM assumes the current user identifier. A NULL principal name is allowed for NTLM SSP and Kerberos authentication services, but may not work for other authentication services.

hr

When used in CoInitializeSecurity(), set on return to indicate the status of the call to register the authentication services.

Windows NT:

Use version 4.0 or later.

Windows:

Use Windows 95 or later. Available as a redistributable for Windows 95.

Windows CE:

Unsupported.

25.8.75    STDAPI

Standard API calling convention.

#define STDAPI EXTERN_C HRESULT STDAPICALLTYPE

25.8.76    SYSKIND

Identifies the target operating system platform. It is defined as follows:

typedef enum tagSYSKIND {
    SYS_WIN16,
    SYS_WIN32,
    SYS_MAC
} SYSKIND;

Table 25-48:  SYSKIND Values

25.8.77    SYSTEMTIME

The SYSTEMTIME structure has the following form:

typedef struct _SYSTEMTIME {
    WORD wYear;
    WORD wMonth;
    WORD wDayOfWeek;
    WORD wDay;
    WORD wHour;
    WORD wMinute;
    WORD wSecond;
    WORD wMilliseconds;
} SYSTEMTIME;

The SYSTEMTIME structure represents a date and time using individual members for the month, day, year, weekday, hour, minute, second, and millisecond:

wYear

The current year.

wMonth

The current month; January is 1.

wDayOfWeek

The current day of the week; Sunday is 0, Monday is 1, and so on.

wDay

The current day of the month.

wHour

The current hour.

wMinute

The current minute.

wSecond

The current second.

wMilliseconds

The current millisecond.

25.8.78    TLIBATTR

Contains information about a type library. Information from this structure is used to identify the type library and to provide national language support for member names. It is defined as follows:

typedef struct FARSTRUCT tagTLIBATTR {
    GUID guid;                      // Unique ID of the library.
    LCID lcid;                      // Language/locale of the library.
    SYSKIND syskind;                // Target hardware platform.
    unsigned short wMajorVerNum;    // Major version number.
    unsigned short wMinorVerNum;    // Minor version number.
    unsigned short wLibFlags;       // Library flags.
} TLIBATTR, FAR * LPTLIBATTR;

25.8.79    TYPEATTR

Contains attributes of an ITypeInfo(), and is defined as follows:

typedef struct FARSTRUCT tagTYPEATTR {
    GUID guid;                    // The GUID of the type information.
    LCID lcid;                    // Locale of member names and doc
                                  // strings.
    unsigned long dwReserved;
    MEMBERID memidConstructor;    // ID of constructor, or MEMBERID_NIL if
                                  // none.
    MEMBERID memidDestructor;     // ID of destructor, or MEMBERID_NIL if
                                  // none. 
    OLECHAR FAR* lpstrSchema;     // Reserved for future use.
    unsigned long cbSizeInstance; // The size of an instance of 
                                  // this type.
    TYPEKIND typekind;            // The kind of type this information
                                  // describes.
    unsigned short cFuncs;        // Number of functions.
    unsigned short cVars;         // Number of variables/data members.
    unsigned short cImplTypes;    // Number of implemented interfaces.
    unsigned short cbSizeVft;     // The size of this type's VTBL.
    unsigned short cbAlignment;   // Byte alignment for an instance
                                  // of this type.
    unsigned short wTypeFlags;
    unsigned short wMajorVerNum;  // Major version number.
    unsigned short wMinorVerNum;  // Minor version number.
    TYPEDESC tdescAlias;          // If TypeKind == TKIND_ALIAS, 
                                  // specifies the type for which 
                                  // this type is an alias.
    IDLDESC idldescType;          // IDL attributes of the 
                                  // described type.
} TYPEATTR, FAR* LPTYPEATTR;

The cbAlignment field indicates how addresses are aligned. A value of 0 indicates alignment on the 64K boundary; 1 indicates no special alignment. For other values, n indicates aligned on byte n.

25.8.80    UINT

Unsigned integer.

typedef unsigned int UINT;

25.8.81    ULARGE_INTEGER

Header: Declared in winnt.h.

The ULARGE_INTEGER structure is used to specify a 64-bit unsigned integer value.

typedef union _ULARGE_INTEGER { 
    struct {
        DWORD LowPart; 
        DWORD HighPart; 
    };
    DWORDLONG QuadPart;
} ULARGE_INTEGER;

25.8.81.1    Members

The ULARGE_INTEGER structure is actually a union. If your compiler has built-in support for 64-bit integers, use the QuadPart member to store the 64-bit integer. Otherwise, use the LowPart and HighPart members to store the 64-bit integer.

LowPart

Specifies the low-order 32 bits.

HighPart

Specifies the high-order 32 bits.

QuadPart

Specifies a 64-bit unsigned integer.

Windows NT:

Use version 3.1 or later.

Windows:

Use Windows 95 or later.

Windows CE:

Use version 1.0 or later.

25.8.82    ULONG

Unsigned long integer.

typedef DWORD ULONG;

25.8.83    USHORT

Unsigned short integer.

typedef unsigned short USHORT;

25.8.84    VARDESC

Describes a variable, constant, or data member. It is defined as follows:

typedef struct FARSTRUCT tagVARDESC {
    MEMBERID memid;
    OLECHAR FAR* lpstrSchema;    // Reserved for future use.
    union {
                                 // VAR_PERINSTANCE, the offset of this
                                 // variable within the instance.
    unsigned long oInst;
                                 // VAR_CONST, the value of the constant.
    VARIANT FAR* lpvarValue;
    } UNION_NAME(u);
    ELEMDESC elemdescVar;
    unsigned short wVarFlags;
    VARKIND varkind;
} VARDESC

25.8.85    VARIANT and VARIANTARG

Use VARIANTARG to describe arguments passed within DISPPARAMS, and VARIANT to specify variant data that cannot be passed by reference. The VARIANT type cannot have the VT_BYREF bit set. VARIANTs can be passed by value, even if VARIANTARGs cannot.

typedef struct FARSTRUCT tagVARIANT VARIANT;
typedef struct FARSTRUCT tagVARIANT VARIANTARG;
typedef struct tagVARIANT  {
    VARTYPE vt;
    unsigned short wReserved1;
    unsigned short wReserved2;
    unsigned short wReserved3;
    union {
        unsigned char    bVal;             // VT_UI1.
        short            iVal;             // VT_I2.
        long             lVal;             // VT_I4.
        float            fltVal;           // VT_R4.
        double           dblVal;           // VT_R8.
        VARIANT_BOOL     boolVal;          // VT_BOOL.
        SCODE            scode;            // VT_ERROR.
        CY               cyVal;            // VT_CY.
        DATE             date;             // VT_DATE.
        BSTR             bstrVal;          // VT_BSTR.
        IUnknown         FAR* punkVal;     // VT_UNKNOWN.
        IDispatch        FAR* pdispVal;    // VT_DISPATCH.
        SAFEARRAY        FAR* parray;      // VT_ARRAY|*.
        unsigned char    FAR* pbVal;       // VT_BYREF|VT_UI1.
        short            FAR* piVal;       // VT_BYREF|VT_I2.
        long             FAR* plVal;       // VT_BYREF|VT_I4.
        float            FAR* pfltVal;     // VT_BYREF|VT_R4.
        double           FAR* pdblVal;     // VT_BYREF|VT_R8.
        VARIANT_BOOL     FAR* pboolVal;    // VT_BYREF|VT_BOOL.
        SCODE            FAR* pscode;      // VT_BYREF|VT_ERROR.
        CY               FAR* pcyVal;      // VT_BYREF|VT_CY.
        DATE             FAR* pdate;       // VT_BYREF|VT_DATE.
        BSTR             FAR* pbstrVal;    // VT_BYREF|VT_BSTR.
        IUnknown FAR*    FAR* ppunkVal;    // VT_BYREF|VT_UNKNOWN.
        IDispatch FAR*   FAR* ppdispVal;   // VT_BYREF|VT_DISPATCH.
        SAFEARRAY FAR*   FAR* pparray;     // VT_ARRAY|*.
        VARIANT          FAR* pvarVal;     // VT_BYREF|VT_VARIANT.
        void             FAR* byref;       // GenericByRef.
    };
};

To simplify extracting values from VARIANTARGs, Automation provides a set of functions for manipulating this type. Use of these functions is strongly recommended to ensure that applications apply consistent coercion rules. The vt value governs the interpretation of the union as follows:

Table 25-49:  tagVARIANT vt Values

25.8.86    VARTYPE

An enumeration type used in VARIANT, TYPEDESC, OLE property sets, and safe arrays. The enumeration constants listed in the following VARENUM section are valid in the vt field of a VARIANT structure.

typedef unsigned short VARTYPE;
enum VARENUM{
    VT_EMPTY     = 0,             // Not specified.
    VT_NULL      = 1,             // Null.
    VT_I2        = 2,             // 2-byte signed int.
    VT_I4        = 3,             // 4-byte signed int.
    VT_R4        = 4,             // 4-byte real.
    VT_R8        = 5,             // 8-byte real.
    VT_CY        = 6,             // Currency.
    VT_DATE      = 7,             // Date.
    VT_BSTR      = 8,             // Binary string.
    VT_DISPATCH  = 9,             // IDispatch
    VT_ERROR     = 10,            // Scodes.
    VT_BOOL      = 11,            // Boolean; True=-1, False=0.
    VT_VARIANT   = 12,            // VARIANT FAR*.
    VT_UNKNOWN   = 13,            // IUnknown FAR*.
    VT_UI1       = 17,            // Unsigned char.
    // Other constants that are not valid in VARIANTs omitted here.
};
    VT_RESERVED  = (int) 0x8000
    // By reference, a pointer to the data is passed.
    VT_BYREF     = (int) 0x4000    
    VT_ARRAY     = (int) 0x2000   // A safe array of the data is passed.

25.8.87    VOID

Any type.

#define VOID void

25.8.88    WCHAR

Unicode character.

typedef wchar_t WCHAR

25.8.89    WINAPI

Calling convention for the Win32 API.

#define WINAPI     FAR PASCAL

25.8.90    WINOLEAPI

Calling convention for the Windows OLE API.

#define WINOLEAPI    STDAPI

25.8.91    WORD

16-bit unsigned integer.

typedef unsigned short WORD;