home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / msdn_vcb / samples / vc98 / sdk / winbase / security / winnt / subauth / readme.txt < prev    next >
Encoding:
Text File  |  1996-09-05  |  7.1 KB  |  171 lines
  1. Portable Systems Group
  2. MSV1_0 SubAuthentication DLL Design Note
  3. Revision 1.3, March 7, 1996
  4.  
  5. 1. INTRODUCTION
  6. 2. INTERFACE TO A SUBAUTHENTICATION DLL
  7. 3. REGISTERING A SUBAUTHENTICATION DLL
  8. 4. REQUESTING A SUBAUTHENTICATION DLL
  9.  
  10. 1. Introduction
  11.  
  12. This document describes  the purpose of and the interface to a
  13. SubAuthentication DLL for the MSV1_0 authentication package.
  14.  
  15. The MSV1_0 authentication package is the standard LSA authentication
  16. package for Windows NT.  It provides or supports:
  17.  
  18.   Authentication of users in the SAM database.
  19.   Pass-Thru authentication of users in trusted domains.
  20.  
  21. Windows NT allows SubAuthentication DLLs to be used in conjunction
  22. with the MSV1_0 authentication package.  A SubAuthentication DLL
  23. allows the authentication and validation criteria stored in SAM to be
  24. replaced for particular subsystems that use the MSV1_0 authentication
  25. package.  For instance, a particular server might supply a SubAuthentication
  26. DLL that validates a userÆs password via a different algorithm, uses a
  27. different granularity of logon hours, and/or specifies workstation restrictions
  28. in a different format.
  29.  
  30. All of this can be accomplished using SubAuthentication DLLs without
  31. sacrificing use of the SAM database (and losing its administration tools) or
  32. losing pass-thru authentication.
  33.  
  34. 2. Interface to a SubAuthentication DLL
  35.  
  36. There are two interfaces that may be supported by SubAuthentication DLLs.
  37. The first is Msv1_0SubAuthenticationRoutine, which is called for
  38. SubAuthentication packages other than package zero. These
  39. SubAuthentication DLLs are called after the correct Domain Controller has
  40. been located and the user to be authenticated has been looked up in the
  41. SAM database.  No attributes of the user will be validated by the MSV1_0
  42. authentication package.  That is the responsibility of the SubAuthentication
  43. DLL.  The SubAuthentication DLL must contain a procedure named
  44. Msv1_0SubAuthenticationRoutine with the following interface:
  45.  
  46. NTSTATUS
  47. NTAPI
  48. Msv1_0SubAuthenticationRoutine(
  49.     IN NETLOGON_LOGON_INFO_CLASS LogonLevel,
  50.     IN PVOID LogonInformation,
  51.     IN ULONG Flags,
  52.     IN PUSER_ALL_INFORMATION UserAll,
  53.     OUT PULONG WhichFields,
  54.     OUT PULONG UserFlags,
  55.     OUT PBOOLEAN Authoritative,
  56.     OUT PLARGE_INTEGER LogoffTime,
  57.     OUT PLARGE_INTEGER KickoffTime
  58. );
  59.  
  60. The second SubAuthentication interface is Msv1_0SubAuthenticationFilter,
  61. which is only called for SubAuthentication DLL zero.  In this case, after the
  62. MSV1_0 authentication package has validated a logon (including network,
  63. interactive, service, and batch logons) it will call the filter routine to do
  64. additional validation. The filter routine may return success, indicating that
  65. the logon should proceed, or failure, indicating that the the additional
  66. validation failed.  In addition, the filter routine may modify the
  67. UserParameters field in the USER_ALL_INFORMATION structure and set
  68. the USER_ALL_PARAMETRS flag in the WhichFields parameter to
  69. indicate that the change should be written to the user object.
  70.  
  71. NTSTATUS
  72. NTAPI
  73. Msv1_0SubAuthenticationFilter(
  74.     IN NETLOGON_LOGON_INFO_CLASS LogonLevel,
  75.     IN PVOID LogonInformation,
  76.     IN ULONG Flags,
  77.     IN PUSER_ALL_INFORMATION UserAll,
  78.     OUT PULONG WhichFields,
  79.     OUT PULONG UserFlags,
  80.     OUT PBOOLEAN Authoritative,
  81.     OUT PLARGE_INTEGER LogoffTime,
  82.     OUT PLARGE_INTEGER KickoffTime
  83. );
  84.  
  85.  
  86. 3. Registering a SubAuthentication DLL
  87. Each SubAuthentication DLL is assigned a DLL number in the range 0
  88. through 255.  The DLL number is used to associate the subsystem calling
  89. LsaLogonUser with the appropriate SubAuthentication DLL.
  90.  
  91. DLL number 0 is reserved to indicate that the
  92. SubAuthentication Filter is to be used. It allows the package to
  93. do additional password or logon validation on top of what
  94. MSV1_0 normally provides. DLL numbers 1 through 127 are reserved for Microsoft.
  95. DLL numbers 128 through 255 are available to ISVs.  ISVs can be assigned a DLL
  96. number by Microsoft by sending email to subauth@microsoft.com.  Registering
  97. your subauthentication pacakge with Microsoft prevents collision of package IDs
  98. when multiple subauthentication packages are installed on a system.
  99.  
  100. Microsoft will not assign the value of 255 for any subauthentication DLL.
  101. If you are developing a subauthentication DLL for use only within your company
  102. or facility, you can use the subauthentication ID number 255.  In this case,
  103. it is not necessary to register your subauthentication package with
  104. Microsoft.
  105.  
  106. Once the ISV has picked a DLL number, the DLL can be registered
  107. under the registry key
  108. HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0.
  109. If the key doesn't exist, the ISV's installation procedure
  110. should create it.  Under that key, the ISV should create a value named
  111. AuthN where N is the DLL number (e.g., Auth128).
  112.  
  113. The value should be a REG_SZ and specify the name of the DLL
  114. which must be in the default DLL load path.  For instance,
  115.  
  116.   Auth128=SubAuth
  117.  
  118. The MSV1_0 authentication package will load the named DLL
  119. the first time the SubAuthentication DLL is requested.
  120.  
  121. 4. Requesting a SubAuthentication DLL
  122.  
  123. A subsystem can request a particular SubAuthentication DLL when calling
  124. LsaLogonUser.  The subsystem calls the MSV1_0 authentication package
  125. (as described in the LSAAUTH.HLP file in the Windows NT DDK) passing
  126. in the MSV1_0_LM20_LOGON structure.
  127.  
  128. typedef struct _MSV1_0_LM20_LOGON {
  129.     MSV1_0_LOGON_SUBMIT_TYPE MessageType;
  130.     UNICODE_STRING LogonDomainName;
  131.     UNICODE_STRING UserName;
  132.     UNICODE_STRING Workstation;
  133.     UCHAR ChallengeToClient[MSV1_0_CHALLENGE_LENGTH];
  134.     STRING CaseSensitiveChallengeResponse;
  135.     STRING CaseInsensitiveChallengeResponse;
  136.     ULONG ParameterControl;
  137. } MSV1_0_LM20_LOGON, * PMSV1_0_LM20_LOGON;
  138.  
  139. The MessageType field must be set to MsV1_0NetworkLogon (Interactive
  140. logons may not be authenticated by a SubAuthentication DLL).
  141.  
  142. The LogonDomainName field should be set to the domain name of the
  143. domain containing the SAM database to be used for authentication.  The
  144. MSV1_0 authentication package and the Netlogon Service will pass thru the
  145. authentication request to that domain.  The SubAuthentication DLL will be
  146. called on a domain controller in the domain.
  147.  
  148. The UserName field must specify the name of a user in the SAM database
  149. on that domain.
  150.  
  151. The Workstation, ChallengeToClient, CaseSensitiveChallengeResponse,
  152. and CaseInsensitiveChallengeResponse fields may be set to any
  153. SubAuthentication DLL specific values.  They will be ignored by the
  154. MSV1_0 authentication package.
  155.  
  156. The ParameterControl field should be set as follows.  Set the various control
  157. flags as appropriate.  Set the most significant byte of Parameter control to
  158. the DLL number of the SubAuthentication DLL to use.
  159.  
  160. #define MSV1_0_CLEARTEXT_PASSWORD_ALLOWED    0x02
  161. #define MSV1_0_UPDATE_LOGON_STATISTICS       0x04
  162. #define MSV1_0_RETURN_USER_PARAMETERS        0x08
  163. #define MSV1_0_DONT_TRY_GUEST_ACCOUNT        0x10
  164.  
  165. //
  166. // The high order byte is a value indicating the SubAuthentication DLL.
  167. //  Zero indicates no SubAuthentication DLL.
  168. //
  169. #define MSV1_0_SUBAUTHENTICATION_DLL             0xFF000000
  170. #define MSV1_0_SUBAUTHENTICATION_DLL_SHIFT       24
  171.