

The following is a description of the functions that will allow
network providers to participate in common login and password
changes.  

----------------------------------------------------------------------------
MPR - Credential Manager API                                
                                                            

//========================
// Changes to mpr.h
//========================

//
// Boolean state flags used for changing password (dwChangeInfo).
//
// WN_VALID_LOGON_ACCOUNT - If this flag is set, then the password (or, more
//      accurately, the authentication information) that was changed will
//      affect future logons.  Some authentication information changes will
//      only affect connections made in untrusted domains.  These are
//      accounts that the user cannot use to logon to this machine anyway.
//      In these cases, this flag will not be set.
//
#define WN_VALID_LOGON_ACCOUNT     0x00000001


DWORD APIENTRY
WNetLogonNotify(
    LPCWSTR             lpPrimaryAuthenticator,
    PLUID               lpLogonId,
    LPCWSTR             lpAuthentInfoType,
    LPVOID              lpAuthentInfo,
    LPCWSTR             lpPreviousAuthentInfoType,  // may be NULL
    LPVOID              lpPreviousAuthentInfo,      // may be NULL
    LPWSTR              lpStationName,
    LPVOID              StationHandle,
    LPWSTR              *lpLogonScripts
    );

DWORD APIENTRY
WNetPasswordChangeNotify(
    LPCWSTR             lpPrimaryAuthenticator,
    LPCWSTR             lpAuthentInfoType,
    LPVOID              lpAuthentInfo,
    LPCWSTR             lpPreviousAuthentInfoType,
    LPVOID              lpPreviousAuthentInfo,
    LPWSTR              lpStationName,
    LPVOID              StationHandle,
    DWORD               dwChangeInfo
    );

//========================
// Changes to ntconfig.h
//========================
//
// The provider class is a set of bit masks that are used in a
// a registry value to declare the class (or type) of provider.
// This value is found in:
//
\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\*myService*\Netw 
rkProvider
//      Class = REG_DWORD  ?
//
// If the Class value is not found in the registry under the NetworkProvider
// key, then the it will be assumed that the provider class is NetworkProvider
// only.
//
//    WN_NETWORK_CLASS - This provider supports the standard WNet
//        network functions for such things as adding connections and
//        enumerating resources, etc...
//
//    WN_CREDENTIAL_CLASS - This provider includes credential management
//        functionality and supports the credential management services.
//
//    WN_PRIMARY_AUTHENT_CLASS - This class is not supported in this release.
//
//
#define WN_NETWORK_CLASS            0x00000001
#define WN_CREDENTIAL_CLASS         0x00000002
#define WN_PRIMARY_AUTHENT_CLASS    0x00000004

//=====================
// Changes to npapi.h
//=====================
DWORD APIENTRY
NPLogonNotify (
    PLUID               lpLogonId,
    LPCWSTR             lpAuthentInfoType,
    LPVOID              lpAuthentInfo,
    LPCWSTR             lpPreviousAuthentInfoType,
    LPVOID              lpPreviousAuthentInfo,
    LPWSTR              lpStationName,
    LPVOID              StationHandle,
    LPWSTR              *lpLogonScript
    );
typedef DWORD (*PF_NPLogonNotify) (
    PLUID               lpLogonId,
    LPCWSTR             lpAuthentInfoType,
    LPVOID              lpAuthentInfo,
    LPCWSTR             lpPreviousAuthentInfoType,
    LPVOID              lpPreviousAuthentInfo,
    LPWSTR              lpStationName,
    LPVOID              StationHandle,
    LPWSTR              *lpLogonScript
    );

DWORD APIENTRY
NPPasswordChangeNotify (
    LPCWSTR             lpAuthentInfoType,
    LPVOID              lpAuthentInfo,
    LPCWSTR             lpPreviousAuthentInfoType,
    LPVOID              lpPreviousAuthentInfo,
    LPWSTR              lpStationName,
    LPVOID              StationHandle,
    DWORD               dwChangeInfo
    );

typedef DWORD (*PF_NPPasswordChangeNotify) (
    LPCWSTR             lpAuthentInfoType,
    LPVOID              lpAuthentInfo,
    LPCWSTR             lpPreviousAuthentInfoType,
    LPVOID              lpPreviousAuthentInfo,
    LPWSTR              lpStationName,
    LPVOID              StationHandle,
    DWORD               dwChangeInfo
    );

//***************************************************************************
//   WNET API DESCRIPTIONS
//***************************************************************************
DWORD APIENTRY
WNetLogonNotify (
    LPCWSTR             lpPrimaryAuthenticator,
    PLUID               lpLogonId,
    LPCWSTR             lpAuthentInfoType,
    LPVOID              lpAuthentInfo,
    LPCWSTR             lpPreviousAuthentInfoType,  // may be NULL
    LPVOID              lpPreviousAuthentInfo,      // may be NULL
    LPWSTR              lpStationName,
    LPVOID              StationHandle,
    LPWSTR              *lpLogonScripts
    );

Description:

    This function provides notification to provider dll's that must handle
    log-on events.

    Each Credential Manager Provider is allowed to return
    a single command line string which will execute a logon script.
    WNetLogonNotify gathers these strings into a MULTI_SZ string buffer.
    (Meaning each string is NULL terminated, and the set of strings is
    NULL terminated - thus making the last string doubly NULL terminated).

    !! IMPORTANT !!
        The caller of this function is responsible for freeing the
        buffer pointed to by *lpLogonScripts.  The windows API function
        LocalFree() should be used to do this.

Arguments:

    lpPrimaryAuthenticator - This is a pointer to a string that identifies
        the primary authenticator.  The router uses this information to
        skip the credential manager identified by this string.  Since it
        is the primary, it has already handled the logon.  This string is
        obtained from the "\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\
        Services\*(keyname)\NetworkProvider\Name" registry value.

    lpLogonId - The logon ID of the session currently being logged on.

    lpAuthentInfoType - This points to a string that identifies the
        AuthentInfo structure type.

        When Microsoft is the primary authenticator, the values that may
        be expected here are the ones described for the lpAuthentInfoType
        parameter to NPLogonNotify().

    lpAuthentInfo - This points to a structure that contains the
        credentials used to successfully log the user on via the
        primary authenticator.  The structures that may be specified when
        using Micosoft's primary authenticator are:

        When Microsoft is the primary authenticator, the structures that
        may be expected here are the ones described for the lpAuthentInfo
        parameter to NPLogonNotify().

    lpPreviousAuthentInfoType - This is pointer to a string that identifies
        the PreviousAuthentInfo structure.  If this pointer is NULL, then
        no PreviousAuthentInfo is available.

        The values that may be expected here are the same as the values that
        may be expected for the lpAuthentInfoType parameter.

    lpPreviousAuthentInfo - If the user was forced to change the password
        prioir to logging on, this points to a AuthentInfo structure that
        will contain the credential information used prior to the password
        change.  If the user was not forced to change the password prior
        to logging on, then this pointer is NULL.

        The structures that may be expected here are the same as the
        structures that may be expected for the lpAuthentInfo parameter.

    lpStationName - This parameter contains the name of the station the
        user has logged onto.  This may be used to determine whether or
        not interaction with the user to obtain additional (provider-specific)
        credentials is possible.  This information will also have a bearing
        on the meaning and use of the StationHandle parameter.

        When Microsoft is the primary authenticator, the values that
        may be expected here are the ones described for the lpStationName
        parameter to NPLogonNotify().

    StationHandle - Is a 32-bit value whose meaning is dependent upon the
        name (and consequently, the type) of station being logged onto.

        When Microsoft is the primary authenticator, the values that
        may be expected here are the ones described for the lpStationHandle
        parameter to NPLogonNotify().

    lpLogonScripts - This is a pointer to a location where a pointer to
        a MULTI_SZ string may be returned.  Each null terminated
        string in the MULTI_SZ string is assumed to contain the name
        of a program to execute and parameters to pass to the program.
        The memory allocated to hold the returned string must be
        deallocatable by the calling routine.  The caller of this
        routine is responsible for freeing the memory used to house
        this string when it is no longer needed.

DWORD APIENTRY
WNetPasswordChangeNotify(
    LPCWSTR             lpPrimaryAuthenticator,
    LPCWSTR             lpAuthentInfoType,
    LPVOID              lpAuthentInfo,
    LPCWSTR             lpPreviousAuthentInfoType,
    LPVOID              lpPreviousAuthentInfo,
    LPWSTR              lpStationName,
    LPVOID              StationHandle,
    DWORD               dwChangeInfo
    );

Description:

    This function is used to notify credential managers of a password
    change for an account.

Arguments:

    lpPrimaryAuthenticator - This is a pointer to a string that identifies
        the primary authenticator.  Credential Manager does not need the
        password notification since it already handled the change.
        This string is obtained from the "\HKEY_LOCAL_MACHINE\SYSTEM\
        CurrentControlSet\Services\*(keyname)\NetworkProvider\Name" registry
        value.

    lpAuthentInfoType - This points to a string that identifies the
        AuthentInfo structure type.

        When Microsoft is the primary authenticator, the values that
        may be expected here are the ones described for the
        lpAuthentInfoType parameter to NPLogonNotify().

    lpAuthentInfo - This points to a structure that contains the
        new credentials.

        When Microsoft is the primary authenticator, the structures that
        may be expected here are the ones described for the lpAuthentInfo
        parameter to NPLogonNotify().

    lpPreviousAuthentInfoType - This points to the string that identifies
        the PreviousAuthentInfo structure type.

        The values that may be expected here are the same as the values that
        may be expected for the lpAuthentInfoType parameter.

    lpPreviousAuthentInfo - This points to an AuthentInfo structure that
        contains the previous credential information. (old password and such).

        The structures that may be expected here are the same as the
        structures that may be expected for the lpAuthentInfo parameter.

    lpStationName - This parameter contains the name of the station the
        user performed the authentication information change from.
        This may be used to determine whether or not interaction with the
        user to obtain additional (provider-specific) information is possible.
        This information will also have a bearing on the meaning and use of
        the StationHandle parameter.

        When Microsoft is the primary authenticator, the values that
        may be expected here are the ones described for the lpStationName
        parameter to NPLogonNotify().

    StationHandle - Is a 32-bit value whose meaning is dependent upon the
        name (and consequently, the type) of station being logged onto.

        When Microsoft is the primary authenticator, the values that
        may be expected here are the ones described for the lpStationHandle
        parameter to NPLogonNotify().

    dwChangeInfo - This is a set of flags that provide information about the
        change.  Currently the following possible values are defined:

            WN_VALID_LOGON_ACCOUNT - If this flag is set, then the
                password (or, more accurately, the authentication
                information) that was changed will affect future
                logons.  Some authentication information changes
                will only affect connections made in untrusted
                domains.  These are accounts that the user cannot
                use to logon to this machine anyway.  In these
                cases, this flag will not be set.


//***************************************************************************
//   PROVIDER API DESCRIPTIONS
//***************************************************************************

A Credential Manager Provider is similar to a network provider in that they
provide entry points that are to be called when logon, or password (or,
more accurately, authentication information changes) occur.  In fact,
some network providers will also be credential managers.

When a logon process such as winlogon, or the service controller is in
the process of logging on, or changing the password for an
account, it will call the appropriate MPR WNet function.  MPR will then
proceed to call the appropriate entry point for each Credential Manager.
These credential management functions will always be called in the system
context (LocalSystem) rather than user context.


Credential managers must be associated with a driver or service, or
otherwise have an entry in the services section of
the registry (\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services).
The service entry must have an sub-key called "NetworkProvider" which
must contain the following values:

    ProviderPath:  The fully qualified path name for the provider dll.
    Name: The name of the provider for display purposes.
    Class: The class (or type) of provider
           (WN_NETWORK_CLASS and/or WN_CREDENTIAL_CLASS and/or
            WN_PRIMARY_AUTHENT_CLASS).

Providers that are NOT credential managers are not required to have a
Class value.  It is assumed that providers without the Class value are
network providers only.

The provider dll exports the NPxxx functions that the provider supports.
Providers identified as credential managers are expected to export
the following credential management functions:

    NPLogonNofity()
    NPChangePassword()

Network Providers identify the functions they support via the NPGetCaps
function.

Credential Manager Providers should support the NPGetCaps(WNNC_Start)
functionality.  This function tells the multiple provider router if it needs
to wait before calling the provider's credential management entry point.
And it it knows, it can tell the provider how long to wait before timing out.



DWORD APIENTRY
NPLogonNotify
    PLUID               lpLogonId,
    LPCWSTR             lpAuthentInfoType,
    LPVOID              lpAuthentInfo,
    LPCWSTR             lpPreviousAuthentInfoType,
    LPVOID              lpPreviousAuthentInfo,
    LPWSTR              lpStationName,
    LPVOID              StationHandle,
    LPWSTR              *lpLogonScript
    );

    This function provides notification to a particular provider that must
    handle log-on events.

    Each Credential Manager is allowed to return a single command line
    string which will execute a logon script.  The buffer for this string
    is allocated by the provider.  MPR is responsible for freeing it.

Arguments:

    lpLogonId - The logon ID of the session just logged on.

    lpAuthentInfoType - This points to a string that identifies the
        AuthentInfo structure type.  When Microsoft is the primary
        authenticator, this will be "MSV1_0:Interactive".

    lpAuthentInfo - This points to a structure that contains the
        credentials used to successfully log the user on via the
        primary authenticator.  The structures that may be specified when
        using Micosoft's primary authenticator are:

        lpAuthentInfoType  == "MSV1_0:Interactive"
        ------------------------------------------

        This value will always be returned for either interactive
        logon (via WinLogon) or service controller logons when
        using Microsoft's provider as the primary authenticator.

        Corresponding data structure:

            typedef struct _MSV1_0_INTERACTIVE_LOGON {
                MSV1_0_LOGON_SUBMIT_TYPE MessageType, //An enumerated type
                UNICODE_STRING           LogonDomainName,
                UNICODE_STRING           UserName,
                UNICODE_STRING           Password,
            } MSV1_0_INTERACTIVE_LOGON;

            where:

                MessageType - is an enumerated type for use by Microsoft.
                    Effectively, the lpAuthentInfoType this field is used
                    by other Microsoft components to determine the format
                    of the remainder of the structure.  Since this
                    information is provided by lpAuthentInfoType parameter,
                    there is no need to utilize this field here.

                LogonDomainName - is the as-typed name of the domain the
                    user wishes to logon to.

                UserName - is the as-typed user account name the user
                    wishes to logon to.

                Password - is the as-typed password for use in authenticating
                    the user.


    lpPreviousAuthentInfoType - This is pointer to a string that identifies
        the PreviousAuthentInfo structure.  If this pointer is NULL, then
        no PreviousAuthentInfo is available.
        The values that may be expected here are the same as the values that
        may be expected for the lpAuthentInfoType parameter.

    lpPreviousAuthentInfo - If the user was forced to change the password
        (or other authentication info) prior to logging on, this parameter
        points to a structure that contains the credential information used
        prior to the authentication information change.  If the user was not
        forced to change authentication information prior to logging on, then
        this pointer is NULL.
        The structures that may be expected here are the same as the
        structures that may be expected for the lpAuthentInfo parameter.


    lpStationName - This parameter contains the name of the station the
        user has logged onto.  This may be used to determine whether or
        not interaction with the user to obtain additional (provider-specific)
        credentials is possible.  This information will also have a bearing
        on the meaning and use of the StationHandle parameter.

        Microsoft primary authenticators will pass one of the following
        values for this string:

                "WinSta_0" - Implies this is an interactive logon via
                    the window station.  The StationHandle parameter
                    value is an hwnd to the parent dialoge.

                "SvcCtl" - Implies this is a logon initiated by the
                    Service controller.  The StationHandle parameter
                    is not used in this case.

    StationHandle - Is a 32-bit value whose meaning is dependent upon the
        name (and consequently, the type) of station being logged onto.

        The meaning and use of this parameter for the Microsoft-defined
        station names are:

                "WinSta_0" - This parameter contains a handle to the owner
                    dialoge (hwndOwner) currently displayed on the screen.

                "SvcCtl" - This parameter is not used and contains random
                    data.


    lpLogonScript - This is a pointer to a location where a pointer to
        a null terminated string may be returned.  The null terminated
        string is assumed to contain the name of a program to execute
        and parameters to pass to the program.  LocalAlloc() should be used
        to allocate the memory for the returned string.  This memory will be
        freed by MPR when no longer needed.


DWORD APIENTRY
NPPasswordChangeNotify(
    LPCWSTR             lpAuthentInfoType,
    LPVOID              lpAuthentInfo,
    LPCWSTR             lpPreviousAuthentInfoType,
    LPVOID              lpPreviousAuthentInfo,
    LPWSTR              lpStationName,
    LPVOID              StationHandle,
    DWORD               dwChangeInfo
    );

Description:

    This function is used to notify a credential manager provider of a
    password change (or, more accurately, an authentication information
    change) for an account.

Arguments:

    lpAuthentInfoType - This points to a string that identifies the
        lpAuthentInfo structure type.

        When Microsoft is the primary authenticator, the values that
        may be expected here are the ones described for the
        lpAuthentInfoType parameter to WNetLogonNotify().


    lpAuthentInfo - This points to a structure that contains the
        new credentials.

        When Microsoft is the primary authenticator, the structures that
        may be expected here are the ones described for the lpAuthentInfo
        parameter to WNetLogonNotify().

    lpPreviousAuthentInfoType - This points to the string that identifies
        the PreviousAuthentInfo structure type.

        The values that may be expected here are the same as the values that
        may be expected for the lpAuthentInfoType parameter.

    lpPreviousAuthentInfo - If the user was forced to change the password
        (or other authentication info) prior to logging on, this parameter
        points to a structure that contains the credential information used
        prior to the authentication information change.  If the user was not
        forced to change authentication information prior to logging on, then
        this pointer is NULL.

        The structures that may be expected here are the same as the
        structures that may be expected for the lpAuthentInfo parameter.

    lpStationName - This parameter contains the name of the station the
        user performed the authentication information change from.
        This may be used to determine whether or not interaction with the
        user to obtain additional (provider-specific) information is possible.
        This information will also have a bearing on the meaning and use of
        the StationHandle parameter.

        When Microsoft is the primary authenticator, the values that
        may be expected here are the ones described for the lpStationName
        parameter to NPLogonNotify().

    StationHandle - Is a 32-bit value whose meaning is dependent upon the
        name (and consequently, the type) of station being logged onto.

        When Microsoft is the primary authenticator, the values that
        may be expected here are the ones described for the lpStationHandle
        parameter to NPLogonNotify().


    dwChangeInfo - This is a set of flags that provide information about the
        change.  Currently the following possible values are defined:

            WN_VALID_LOGON_ACCOUNT - If this flag is set, then the
                password (or, more accurately, the authentication
                information) that was changed will affect future
                logons.  Some authentication information changes
                will only affect connections made in untrusted
                domains.  These are accounts that the user cannot
                use to log onto this machine anyway.  In these
                cases, this flag will not be set.


//***************************************************************************
//   WINLOGON and LOGON SCRIPTS
//***************************************************************************

Providers can pass back instructions for running logon scripts from calls
to WNetLogonNotify.
The string describing the logon script should contain all the information
necessary to run that script as a command line passed to CreateProcess.
If the string requires the command processor to process it
as in the case of command or batch files, then the string should be prefixed
with "cmd /C".

If MyFile is a command (or batch file),

    "cmd /C MyFile"     - Will run as...

                          MyFile.bat on DOS
                          MyFile.cmd on OS/2
                          MyFile.bat on NT

Logon scripts will be run in user context when the user profile is available.
However, environment variables that are set will not be global and will not
be available to the initial shell (e.g., program manager) or other programs
run on the user's behalf.

//***************************************************************************
// Notes of hwndOwners
//***************************************************************************

hwndOwner is a handle to the owner window.  If this is used in displaying
a modal dialog box, the dialog will exhibit the correct behavior and not
allow any other window to have the focus until the dialog is answered.  When
this handle is NULL, and it is used in displaying a modal dialog box, the
dialog box will not exhibit the expected modal behavior because the desktop
is used to display the dialog.

//***************************************************************************
// Notes on registry usage
//***************************************************************************
New fields that will be added to the registry to support credential manager
providers are noted by a leading asterisk.


Until we fully support switching primary authenticators,
MicrosoftWindowsNetwork will always be the primary authenticator.
Thus the registry might look like this:

\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control
    NetworkProvider
        Order
            ProviderOrder = REG_SZ:LanmanWorkstation,BanyanVines

\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services
    LanmanWorkstation
        NetworkProvider
            DeviceName = REG_SZ:\Device\LanmanWorkstation
            Name = REG_SZ:MicrosoftWindowsNetwork
            ProviderPath = REG_EXPAND_SZ:%SystemRoot%\System32\ntlanman.dll
         *  Class = REG_DWORD:0x00000001 (WN_NETWORK_CLASS)

\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services
    BanyanVines
        NetworkProvider
            DeviceName = REG_SZ:\Device\BanyanVines
            Name = REG_SZ:BanyanVinesNetwork
            ProviderPath = REG_EXPAND_SZ:%SystemRoot%\System32\NtVines.dll
         *  Class = REG_DWORD:0x00000005
                (WN_NETWORK_CLASS | WN_CREDENTIAL_CLASS)
         *  AuthentProviderPath =
REG_EXPAND_SZ:%SystemRoot%\System32\BanyanCM.dll


Class - This identifies the class (or type) of provider functionality that
    this provider supports.  Although a provider may support the primary
    authenticator functionality, it may not be selected to be a primary
    authenticator.

AuthentProviderPath - This is the fully qualified file name for the dll which
    exports the winnet credential manager api functions.  This value is only
    useful (but not required) when the provider is identified as being
    a CREDENTIAL_CLASS or PRIMARY_AUTHENT_CLASS provider.  If this value is
    not present for a provider of this class, the credential management
    functions will be expected to be exported from the dll identified by
    the ProviderPath value.

NOTE:  All providers (credential managers and network) must be listed
    in the ProviderOrder string.  If a provider is not listed, MPR will not
    know about it.  All references to providers in the "Control" portion
    of the registry are made with the registry key name for the service or
    driver that is associated with that provider in the "Services" section
    of the registry.

