windows-server-2003/ds/security/protocols/msv_sspi/test/msvsubauth/readme.txt

Portable Systems Group
MSV1_0 SubAuthentication DLL Design Note
Revision 1.3, March 7, 1996

1. INTRODUCTION
2. INTERFACE TO A SUBAUTHENTICATION DLL
3. REGISTERING A SUBAUTHENTICATION DLL
4. REQUESTING A SUBAUTHENTICATION DLL

1. Introduction

This document describes  the purpose of and the interface to a
SubAuthentication DLL for the MSV1_0 authentication package.

The MSV1_0 authentication package is the standard LSA authentication
package for Windows NT.  It provides or supports:

  Authentication of users in the SAM database.
  Pass-Thru authentication of users in trusted domains.

Windows NT allows SubAuthentication DLLs to be used in conjunction
with the MSV1_0 authentication package.  A SubAuthentication DLL
allows the authentication and validation criteria stored in SAM to be
replaced for particular subsystems that use the MSV1_0 authentication
package.  For instance, a particular server might supply a SubAuthentication
DLL that validates a user�s password via a different algorithm, uses a
different granularity of logon hours, and/or specifies workstation restrictions
in a different format.

All of this can be accomplished using SubAuthentication DLLs without
sacrificing use of the SAM database (and losing its administration tools) or
losing pass-thru authentication.

2. Interface to a SubAuthentication DLL

There are two interfaces that may be supported by SubAuthentication DLLs.
The first is Msv1_0SubAuthenticationRoutine, which is called for
SubAuthentication packages other than package zero. These
SubAuthentication DLLs are called after the correct Domain Controller has
been located and the user to be authenticated has been looked up in the
SAM database.  No attributes of the user will be validated by the MSV1_0
authentication package.  That is the responsibility of the SubAuthentication
DLL.  The SubAuthentication DLL must contain a procedure named
Msv1_0SubAuthenticationRoutine with the following interface:

NTSTATUS
NTAPI
Msv1_0SubAuthenticationRoutine(
    IN NETLOGON_LOGON_INFO_CLASS LogonLevel,
    IN PVOID LogonInformation,
    IN ULONG Flags,
    IN PUSER_ALL_INFORMATION UserAll,
    OUT PULONG WhichFields,
    OUT PULONG UserFlags,
    OUT PBOOLEAN Authoritative,
    OUT PLARGE_INTEGER LogoffTime,
    OUT PLARGE_INTEGER KickoffTime
);

The second SubAuthentication interface is Msv1_0SubAuthenticationFilter,
which is only called for SubAuthentication DLL zero.  In this case, after the
MSV1_0 authentication package has validated a logon (including network,
interactive, service, and batch logons) it will call the filter routine to do
additional validation. The filter routine may return success, indicating that
the logon should proceed, or failure, indicating that the the additional
validation failed.  In addition, the filter routine may modify the
UserParameters field in the USER_ALL_INFORMATION structure and set
the USER_ALL_PARAMETRS flag in the WhichFields parameter to
indicate that the change should be written to the user object.

NTSTATUS
NTAPI
Msv1_0SubAuthenticationFilter(
    IN NETLOGON_LOGON_INFO_CLASS LogonLevel,
    IN PVOID LogonInformation,
    IN ULONG Flags,
    IN PUSER_ALL_INFORMATION UserAll,
    OUT PULONG WhichFields,
    OUT PULONG UserFlags,
    OUT PBOOLEAN Authoritative,
    OUT PLARGE_INTEGER LogoffTime,
    OUT PLARGE_INTEGER KickoffTime
);


3. Registering a SubAuthentication DLL
Each SubAuthentication DLL is assigned a DLL number in the range 0
through 255.  The DLL number is used to associate the subsystem calling
LsaLogonUser with the appropriate SubAuthentication DLL.

DLL number 0 is reserved to indicate that the
SubAuthentication Filter is to be used. It allows the package to
do additional password or logon validation on top of what
MSV1_0 normally provides. DLL numbers 1 through 127 are reserved for Microsoft.
DLL numbers 128 through 255 are available to ISVs.  ISVs can be assigned a DLL
number by Microsoft by sending email to [email protected].  Registering
your subauthentication pacakge with Microsoft prevents collision of package IDs
when multiple subauthentication packages are installed on a system.

Microsoft will not assign the value of 255 for any subauthentication DLL.
If you are developing a subauthentication DLL for use only within your company
or facility, you can use the subauthentication ID number 255.  In this case,
it is not necessary to register your subauthentication package with
Microsoft.

Once the ISV has picked a DLL number, the DLL can be registered
under the registry key
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0.
If the key doesn't exist, the ISV's installation procedure
should create it.  Under that key, the ISV should create a value named
AuthN where N is the DLL number (e.g., Auth128).

The value should be a REG_SZ and specify the name of the DLL
which must be in the default DLL load path.  For instance,

  Auth128=SubAuth

The MSV1_0 authentication package will load the named DLL
the first time the SubAuthentication DLL is requested.

4. Requesting a SubAuthentication DLL

A subsystem can request a particular SubAuthentication DLL when calling
LsaLogonUser.  The subsystem calls the MSV1_0 authentication package
(as described in the LSAAUTH.HLP file in the Windows NT DDK) passing
in the MSV1_0_LM20_LOGON structure.

typedef struct _MSV1_0_LM20_LOGON {
    MSV1_0_LOGON_SUBMIT_TYPE MessageType;
    UNICODE_STRING LogonDomainName;
    UNICODE_STRING UserName;
    UNICODE_STRING Workstation;
    UCHAR ChallengeToClient[MSV1_0_CHALLENGE_LENGTH];
    STRING CaseSensitiveChallengeResponse;
    STRING CaseInsensitiveChallengeResponse;
    ULONG ParameterControl;
} MSV1_0_LM20_LOGON, * PMSV1_0_LM20_LOGON;

The MessageType field must be set to MsV1_0NetworkLogon (Interactive
logons may not be authenticated by a SubAuthentication DLL).

The LogonDomainName field should be set to the domain name of the
domain containing the SAM database to be used for authentication.  The
MSV1_0 authentication package and the Netlogon Service will pass thru the
authentication request to that domain.  The SubAuthentication DLL will be
called on a domain controller in the domain.

The UserName field must specify the name of a user in the SAM database
on that domain.

The Workstation, ChallengeToClient, CaseSensitiveChallengeResponse,
and CaseInsensitiveChallengeResponse fields may be set to any
SubAuthentication DLL specific values.  They will be ignored by the
MSV1_0 authentication package.

The ParameterControl field should be set as follows.  Set the various control
flags as appropriate.  Set the most significant byte of Parameter control to
the DLL number of the SubAuthentication DLL to use.

#define MSV1_0_CLEARTEXT_PASSWORD_ALLOWED    0x02
#define MSV1_0_UPDATE_LOGON_STATISTICS       0x04
#define MSV1_0_RETURN_USER_PARAMETERS        0x08
#define MSV1_0_DONT_TRY_GUEST_ACCOUNT        0x10

//
// The high order byte is a value indicating the SubAuthentication DLL.
//  Zero indicates no SubAuthentication DLL.
//
#define MSV1_0_SUBAUTHENTICATION_DLL             0xFF000000
#define MSV1_0_SUBAUTHENTICATION_DLL_SHIFT       24