[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

            CIFS Domain Logon and Pass Through Autentication


Network Working Group                           Paul J. Leach, Microsoft
INTERNET-DRAFT                                  Dilip C. Naik, Microsoft
draft-leach-cifs-logon-spec-00.txt
Category: Informational
Expires June 3, 1997                         January 3, 1997


               CIFS Logon and Pass Through Authentication

                           Preliminary Draft




STATUS OF THIS MEMO

THIS IS A PRELIMINARY DRAFT OF AN INTERNET-DRAFT.  IT DOES NOT REPRESENT
THE CONSENSUS OF  ANY WORKING GROUP.

This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas, and
its working groups. Note that other groups may also distribute working
documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as "work in progress".

To learn the current status of any Internet-Draft, please check the
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
ftp.isi.edu (US West Coast).

Distribution of this document is unlimited.  Please send comments to the
authors or the CIFS mailing list at <cifs@listserv.msn.com>.
Discussions of the mailing list are archived at
<URL:http://microsoft.ease.lsoft.com/archives/cifs.html>.


ABSTRACT

This specification defines how a certain Common Internet File Systems
(CIFS) client accomplishes logging on to a CIFS server. The
specification also details how a CIFS server may accomplish pass through
authentication.


Table of Contents


1. PREREQUISITES AND SUGGESTED READING.................................2


Leach, Naik                                                            1


            CIFS Domain Logon and Pass Through Autentication


2. CIFS DOMAIN LOGON...................................................3

 2.1 DOMAIN CONTROLLER DISCOVERY ......................................3
  2.1.1 NetBIOS Name Notation .........................................3
  2.1.2 Mailslot Protocol Specification ...............................3
  2.1.3 Primary Domain Controller Location Protocol ...................4
 2.2 SESSION SETUP ....................................................6
 2.3 REMOTE API EXECUTION .............................................6
 2.4 NETWKSTAUSERLOGON ................................................6
 2.5 NETWKSTAUSERLOGOFF ..............................................11
 2.6 NETUSERGETINFO ..................................................13

3. CIFS PASS THROUGH AUTHENTICATION...................................17


4. APPENDIX A - REMOTE ADMINISTRATION PROTOCOL........................18

 4.1 NOTATION ........................................................18
 4.2 DESCRIPTORS .....................................................19
  4.2.1 Request Parameter Descriptors ................................19
  4.2.2 Response Parameter Descriptors ...............................20
  4.2.3 Data Descriptors .............................................20
 4.3 TRANSACTION REQUEST PARAMETERS SECTION ..........................21
 4.4 TRANSACTION REQUEST DATA SECTION ................................21
 4.5 TRANSACTION RESPONSE PARAMETERS SECTION .........................21
 4.6 TRANSACTION RESPONSE DATA SECTION ...............................22

5. AUTHOR'S ADDRESSES.................................................22


Objective

This document details :
. how a CIFS client logs on to a domain
. how a CIFS client logs on to a CIFS server where the CIFS server
  performs pass through authentication , verifying the client
  credentials with a Domain Controller.

For convenience, some sections from the CIFS specification have been
reproduced in part within this document. Note that the CIFS
specification should be considered to be the authoritative reference, in
case of any doubts, rather than this document.


1. Prerequisites and suggested reading

. Familiarity with Common Internet File Systems specification (CIFS)
. Familiarity with the CIFS Remote Administration Protocol (RAP)
  specification.






Leach, Naik                                                            2


            CIFS Domain Logon and Pass Through Autentication


2. CIFS Domain Logon

CIFS domain logon is a mechanism by which a CIFS server validates a
user's credentials with a Domain Controller (DC). For the purposes of
this document, a domain is simply a logical grouping of resources such
as CIFS servers, user accounts, etc. A Domain Controller is a CIFS
server that coordinates synchronization and management activities within
a domain.  Specific Microsoft products implement the concept of domains
with much greater richness and detail, but that is beyond the scope of
this document.

A CIFS client logs onto a domain in 3 logical steps:
. Domain Controller Discovery
. Session Setup
. Remote API execution

Each of these are discussed in greater detail in the following sections.


2.1 Domain Controller Discovery

Domain Controller Discovery is the process by means of which a CIFS
client locates a Domain Controller (DC). This
functionality is implemented using mailslots and special NETBIOS names.
Before proceeding to explain the Domain Controller Discovery mechanism,
it would be appropriate to discuss NETBIOS names and Mailslots.

Mailslots provide an easy to use mechanism for fast, unreliable
unidirectional data transfer. With Microsoft implementations of
mailslots, once an application has obtained a handle to a mailslot, the
application can write to the mailslot in a fashion very similar to
writing to a file. Mailslot writes are implemented using the CIFS
Transact SMB which is sent via a datagram to some special Netbios names.
Various data structures, which are detailed  subsequently within this
document, flow as the data portion of the Transact SMB.

2.1.1 NetBIOS Name Notation

NAME(xx) denotes the ASCII string "NAME," padded with spaces (0x20) to
15 bytes, with a hex xx value in the 16th byte.  For example, the
notation "FOOBAR(xx)" indicates a NetBIOS name consisting of the bytes:
    [69,79,79,65,64,82,20,20,20,20,20,20,20,20,20, xx]

String literals that are placeholders and that need to be substituted
with their actual values are bracketed within <>. Thus the string
<Domain> would become _Redmond_ if the domain under consideration is
named _Redmond_.
Details of the various NETBIOS names used for browsing are described in
Appendix  C

2.1.2 Mailslot Protocol Specification

Mailslots provide an easy to use mechanism for fast, unreliable
unidirectional data transfer. With Microsoft implementations of

Leach, Naik                                                            3


            CIFS Domain Logon and Pass Through Autentication


mailslots, once an application has obtained a handle to a mailslot, the
application can write to the mailslot in a fashion very similar to
writing to a file. Mailslot writes are implemented using the CIFS
Transact SMB which is sent via a datagram to some special Netbios names.
Various data structures, which are detailed  subsequently within this
document, flow as the data portion of the CIFS Transact SMB.

The only transaction allowed to a mailslot is a mailslot write.
Mailslot writes requests are encapsulated in CIFS TRANSACT SMBs. The
following table shows the interpretation of the TRANSACT SMB parameters
for a mailslot transaction:
 Name       Value                Description
 Command    SMB_COM_TRANSACTION
 Name       \MAILSLOT\<name>      STRING Name of mail slot to  write
 SetupCount 3                    Always 3 for mailslot writes
 Setup[0]   1                    Command code == write mailslot
 Setup[1]   Ignored
 Setup[2]   Ignored
            n                    Size of data in bytes to write to the
TotalDataCo                      mailslot
unt
Data[n]                          The data to write to the mailslot


2.1.3 Primary Domain Controller Location Protocol

This appendix details how a client goes about locating a Primary Domain
Controller (PDC). The process is rather involved, because different
versions of the Primary Domain Controller have used different versions
of the protocol, and hence a client that does not know what protocol is
supported by its Primary Domain Controller has to try them all.

A Primary Domain Controller (PDC) for a domain "D" is located by sending
a mailslot message containing a NETLOGON_QUERY frame to a NETBIOS name
and mailslot "\NET\NETLOGON" and then waiting for a reply mailslot
message, which will be sent to the mailslot name specified by the client
in the NETLOGON_QUERY structure., and which will contain a
NETLOGON_RESPONSE structure. If there is no response after a delay, the
message may be retransmitted. The delay MUST be at least twice the
expected service time, and the delay should be doubled after each time-
out.

If a reply is received, the name of the Primary Domain Controller SHOULD
be cached for future use, so as time minimize network traffic. If no
reply is received after several retransmissions, the Primary Domain
Controller may be declared to be unreachable, and no further attempt to
locate it should be made for a while (exactly how long depends on the
expected recovery time for a Primary Domain Controller and/or for the
network; typically a minute or so, but should be increased after each
failure).

The only difference between versions of the protocol is the NETBIOS name
to which the message is sent, as follows:


Leach, Naik                                                            4


            CIFS Domain Logon and Pass Through Autentication


NETBIOS     name      PDC's OS version
name        type      =============
=========== ========
D(1b)       unique    Windows NT 3.51 or later or compatible
D(1c)       group     Windows NT 3.1 or later or compatible
D(00)       group     all

Clients which are configured to know or are willing to assume what
version of the protocol their Primary Domain Controller is running may
directly use the appropriate NETBIOS name for that version. Otherwise,
they SHOULD first attempt D(1b), since it is unicast and creates the
least network traffic; if there is no response, then they SHOULD try the
others. They MAY try them in parallel.

The NETLOGON_QUERY structure is defined as :

    struct NETLOGON_QUERY{
        unsigned char   Opcode;
        char            ComputerName[];
        char            MailslotName[];
        unsigned short  Lm20Token;
    } ;

    Opcode __Identifies this structure as a NETLOGON_QUERY and has a
        value of 0x07.

    ComputerName __Specifies the ASCII name of the computer sending the
        query, and is up to 16 bytes in length. The response is sent to
        NETBIOS unique name <ComputerName>(00).

    MailslotName __Specifies the ASCII name of the mailslot to which the
        response is to be sent, and is up to 256 bytes in length; cannot
        be _\MAILSLOT\LANMAN_ or _\MAILSLOT\MSBROWSE_ or
        "\NET\NETLOGON".

    Lm20Token - has a value of 0xFFFF.


The response mailslot message contains a NETLOGON_RESPONSE data
structure that is defined as the following :

    struct NETLOGON_RESPONSE
    {
        unsigned char   Opcode;
        char            PrimaryDCName[16];
        unsigned short  Lm20Token;
    };

where
    Opcode __Identifies this structure as a NETLOGON_RESPONSE and has a
        value of 0x12.

    PrimaryDCName __Specifies the ASCII name of the Primary Domain
        Controller and is up to 16 bytes in length.

Leach, Naik                                                            5


            CIFS Domain Logon and Pass Through Autentication


    Lm20Token - has a value of 0xFFFF

Note that this procedure to locate a Primary Domain Controller is
expensive in terms of network traffic. The Microsoft implementations
attempt to alleviate this by caching the PDC Name. Before using the
cached PDC Name, a NetServerEnum2 API is remoted to the PDC and a sanity
check is performed to ensure that the server type returned indicates a
Primary Domain Controller



2.2 Session Setup

The objective of this phase is to validate the client credentials. The
CIFS client sends a SessionSetupAndX SMB to the Domain Controller whose
identity has just been dicovered, along with a challenge response that
is computed as detailed in the CIFS specification. The SessionSetupAndX
SMB response indicates whether the Domain Controller was satisfied with
the challenge response. The SessiopnSetupAndX SMB response will also
indicate if the Domain Controller is dissatisfied with the challenge
response, but permits guest access. Obviously, the SessionSetupAndX SMB
must be preceded by a Negotiate SMB as detailed in the CIFS
specification.

The Negotiate and Session Setup SMBs are detailed in the CIFS document.
All of these SMBs are sent to the Domain Controller.

2.3 Remote API execution

Persons unfamiliar with the RAP specification are strongly advised to
read the CIFS specification or at least Appendix A at this stage.
Sections that follow describe how a CIFS client logs on, logs off and
retrieves other significant information such as home directory, etc
about a particular user.

2.4 NetwkstaUserLogon

This is a function executed on a remote CIFS server to log on a user.
The purpose is to perform checks such as whether the specified user is
permitted to logon from the specified computer, whether the specified
user is permitted to log on at the given moment, etc. as well as perform
housekeeping and statistics updates.

There is a password field in the parameters for this function. However,
this field is always set to null before the function is sent on the
wire, in order to preserve security. The remote CIFS server ignores this
meaningless password that is sent. The remote CIFS server ensures
security by checking that the user name and computer name that are in
the request parameters are the same used to establish the session and
connection to the IPC$ share on the remote CIFS server.

The definition is:

 unsigned short NetWkstaUserLogon(

Leach, Naik                                                            6


            CIFS Domain Logon and Pass Through Autentication


   char        *reserved1;
   char        *reserved2;
   unsigned short    sLevel;
   BYTE        bReqBuffer[54];
   unsigned short   cbReqBuffer;
   RCVBUF      pbBuffer;
   RCVBUFLEN   cbBuffer;
   unsigned short   *pcbTotalAvail;
 );

 where:

   reserved1 and reserved2 are reserved fields and must be null.

   sLevel specifies the level of detail returned. The only legal
   value is 1.

   pbReqBuffer points to the request buffer. This buffer contains
   parameters that need to be sent to the server. The actual value
   and structure is defined in the Transaction Request Parameters
   section.

   cbReqBuffer specifies the size, in bytes, of the buffer pointed to
   by the pbReqBuffer parameter.  The value must be decimal 54.

   pbBuffer points to the buffer to receive the returned data.

   cbBuffer specifies the size, in bytes, of the buffer pointed to by
   the pbBuffer parameter.

   pcbTotalAvail is a pointer to an unsigned short which gets filled
   with the total number of data bytes available if the function
   succeeds.

Transaction Request Parameters section

The Transaction request parameters section in this instance contains:

. The 16 bit function number for NetWkstaUserLogon which is 132.
. The parameter descriptor string which is "zzWb54WrLh"
. The data descriptor string for the (returned) data which is
  "WB21BWDWWDDDDDDDzzzD"
. The actual parameters as described by the parameter descriptor
  string.

The parameters are:
. A null pointer
. Another null pointer
. A 16 bit integer with a value of 1 (corresponding to the "W" in the
  parameter descriptor string. This represents the level of detail the
  server is expected to return)
. a byte array of length 54 bytes. These 54 bytes are defined as



Leach, Naik                                                            7


            CIFS Domain Logon and Pass Through Autentication


    char    wlreq1_name[21];        // User Name
    char    wlreq1_pad1;            //Pad next field to a word boundary
    char    wlreq1_password[15];    //Password, set to null, ignored by
    server
    char    wlreq1_pad2;            //Pad next field to word boundary
    char    wlreq1_workstation[16]; //ASCII name of computer
. A 16 bit integer with a value of 54
. A 16 bit integer that contains the size of the receive buffer


Transaction Request Data section

There is no data or auxiliary data to send as part of the request.

Transaction Response Parameters section

The transaction response parameters section consists of:
. A 16 bit word indicating the return status. The possible values are:

Code                    Value  Description
NERR_Success            0      No errors encountered
ERROR_ACCESS_DENIED     5      User has insufficient privilege
NERR_LogonScriptError   2212   An error occurred while loading or
                               running the logon script
NERR_StandaloneLogon    2214   The logon was not validated by any
                               server
NERR_NonValidatedLogon  2217   The logon server is running an
                               older software version and cannot
                               validate the logon
NERR_InvalidWorkstation 2240   The user is not allowed to logon
                               from this computer
NERR_InvalidLogonHours  2241   The user is not allowed to logon at
                               this time
NERR_PasswordExpired    2242   The user password has expired

. A 16 bit "converter" word.
. A 16 bit number representing the total number of available bytes.
  This has meaning only if the return status is NERR_Success or
  ERROR_MORE_DATA. Upon success, this number indicates the number of
  useful bytes available. Upon failure, this indicates how big the
  receive buffer needs to be.

Transaction Response Data section

The Transaction response data section contains a data structure
user_logon_info_1 which is defined as:









Leach, Naik                                                            8


            CIFS Domain Logon and Pass Through Autentication


    struct user_logon_info_1 {
        unsigned short      usrlog1_code;
        char                usrlog1_eff_name[21];
        char                usrlog1_pad_1;
        unsigned short      usrlog1_priv;
        unsigned long       usrlog1_auth_flags;
        unsigned short      usrlog1_num_logons;
        unsigned short      usrlog1_bad_pw_count;
        unsigned long       usrlog1_last_logon;
        unsigned long       usrlog1_last_logoff;
        unsigned long       usrlog1_logoff_time;
        unsigned long       usrlog1_kickoff_time;
        long                usrlog1_password_age;
        unsigned long       usrlog1_pw_can_change;
        unsigned long       usrlog1_pw_must_change;
        char            *usrlog1_computer;
        char            *usrlog1_domain;
        char                *usrlog1_script_path;
        unsigned long       usrlog1_reserved1;
    };

where:

  usrlog1_code specifies the result and can have the following values:

Code                    Value  Description
NERR_Success            0      No errors encountered
ERROR_ACCESS_DENIED     5      User has insufficient privilege
NERR_LogonScriptError   2212   An error occurred while loading or
                               running the logon script
NERR_StandaloneLogon    2214   The logon was not validated by any
                               server
NERR_NonValidatedLogon  2217   The logon server is running an
                               older software version and cannot
                               validate the logon
NERR_InvalidWorkstation 2240   The user is not allowed to logon
                               from this computer
NERR_InvalidLogonHours  2241   The user is not allowed to logon at
                               this time
NERR_PasswordExpired    2242   Administrator privilege


  usrlog1_eff_name specifies the account to which the user was logged on

  usrlog1_pad1 aligns the next data structure element to a word boundary

  usrlog1_priv specifies the user's privilege level. The possible values
       are:

Name             Value  Description
USER_PRIV_GUEST  0      Guest privilege
USER_PRIV_USER   1      User privilege
USER_PRV_ADMIN   2      Administrator privilege


Leach, Naik                                                            9


            CIFS Domain Logon and Pass Through Autentication


  usrlog1_auth_flags specifies the account operator privileges. The
       possible values are:

Name            Value   Description
AF_OP_PRINT     0       Print operator
AF_OP_COMM      1       Communications operator
AF_OP_SERVER    2       Server operator
AF_OP_ACCOUNTS  3       Accounts operator

  usrlog1_num_logons specifies the number of times this user has logged
       on. A value of -1 means the number of logons is unknown.

  usrlog1_bad_pw_count specifies the number of incorrect passwords
       entered since the last successful logon.

  usrlog1_last_logon specifies the time when the user last logged on.
       This value is stored as the number of seconds elapsed since
       00:00:00, January 1, 1970.

  usrlog1_last_logoff specifies the time when the user last logged off.
       This value is stored as the number of seconds elapsed since
       00:00:00, January 1, 1970. A value of 0 means the last logoff
       time is unknown.

  usrlog1_logoff_time specifies the time when the user should logoff.
       This value is stored as the number of seconds elapsed since
       00:00:00, Jan 1, 1970. A value of -1 means the user never has to
       logoff.

  usrlog1_kickoff_time specifies the time when the user will be logged
       off by the system. This value is stored as the number of seconds
       elapsed since 00:00:00, Jan 1, 1970. A value of -1 means the
       system will  never logoff the user.

   usrlog1_password_age specifies the time in seconds since the user
       last changed his/her password.

  usrlog1_password_can_change specifies the time when the user can
       change the password. This value is stored as the number of
       seconds elapsed since 00:00:00, Jan 1, 1970. A value of -1 means
       the user can never change the password.

  usrlog1_password_must_change specifies the time when the user must
       change the password. This value is stored as the number of
       seconds elapsed since 00:00:00, Jan 1, 1970.

  usrlog1_computer specifies the computer where the user is logged on.

  usrlog1_script_path specifies the relative path to the user logon
       script.

  usrlog1_reserved is reserved with an undefined value.



Leach, Naik                                                           10


            CIFS Domain Logon and Pass Through Autentication


The following table defines the valid fields in the user_logon_info_1
structure based upon the return values::

function return code  usrlog1_code element     Valid elements of
                                               logoff_info_1
NERR_Success          NERR_Success             All
NERR_Success          NERR_StandaloneLogon     None except usrlog1_code
ERROR_ACCESS_DENIED   NERR_PasswordExpired     None except usrlog1_code
ERROR_ACCESS_DENIED   NERR_InvalidWorkstation  None except usrlog1_code
ERROR_ACCESS_DENIED   NERR_InvalidLogonhours   None except usrlog1_code
ERROR_ACCESS_DENIED   NERR_LogonScriptError    None except usrlog1_code
ERROR_ACCESS_DENIED   ERROR_ACCESS_DENIED      None except usrlog1_code
All other errors      None; the code is        None
                      meaningless

All of the pointers in this data structure need to be treated
specially. The  pointer is a 32 bit pointer. The higher 16 bits need
to be ignored. The converter word returned in the parameters section
needs to be subtracted from the lower 16 bits to calculate an offset
into the return buffer where this ASCII string resides.

There is no auxiliary data in the response.
2.5 NetwkstaUserLogoff

This is a function executed on a remote CIFS server to log on a user.
The purpose is to perform some checks and accomplish housekeeping and
statistics updates.

The definition is:

 unsigned short NetWkstaUserLogoff(
   char        *reserved1;
   char        *reserved2;
   unsigned short   sLevel;
   BYTE        bReqBuffer[54];
   unsigned short   cbReqBuffer;
   REQBUF      pbBuffer;
   REQBUFLEN   cbBuffer;
   unsigned short   *pcbTotalAvail;
 );

 where:

   reserved1 and reserved2 are reserved fields and must be null.

   sLevel specifies the level of detail returned. The only legal
   value is 1.

   pbReqBuffer points to the request buffer. This buffer contains
   parameters that need to be sent to the server. The actual value
   and structure is defined in the Transaction Request Parameters
   section.



Leach, Naik                                                           11


            CIFS Domain Logon and Pass Through Autentication


   cbReqBuffer specifies the size, in bytes, of the buffer pointed to
   by the pbReqBuffer parameter.  The value must be decimal 54.

   pbBuffer points to the buffer to receive the returned data.

   cbBuffer specifies the size, in bytes, of the buffer pointed to by
   the pbBuffer parameter.

   pcbTotalAvail is a pointer to an unsigned short which gets filled
   with the total number of data bytes available if the function
   succeeds.

Transaction Request Parameters section

The Transaction request parameters section in this instance contains:

. The 16 bit function number for NetWkstaUserLogoff which is 133.
. The parameter descriptor string which is "zzWb38WrLh"
. The data descriptor string for the (returned) data which is "WDW"
. The actual parameters as described by the parameter descriptor
  string.

The parameters are:
. A null pointer
. Another null pointer
. A 16 bit integer with a value of 1 (corresponding to the "W" in the
  parameter descriptor string. This represents the level of detail the
  server is expected to return)
. An array of  length 38 bytes. These 38 bytes are defined as
    char            wlreq1_name[21];        // User Name
    char            wlreq1_pad1;        //Pad next field to a word
    boundary
    char            wlreq1_workstation[16];     //ASCII name of computer
. A 16 bit integer with a value of decimal 38.
. A 16 bit integer that contains the size of the receive buffer

Transaction Request Data section

There is no data or auxiliary data to send as part of the request.

Transaction Response Parameters section

The transaction response parameters section consists of:
. A 16 bit word indicating the return status. The possible values are:

Code                   Value  Description
NERR_Success           0      No errors encountered
NERR_StandaloneLogon   2214   The logon was not validated by any
                              server
NERR_NonValidatedLogon 2217   The logon server is running an older
                              software version and cannot validate the
                              logoff

. A 16 bit "converter" word.

Leach, Naik                                                           12


            CIFS Domain Logon and Pass Through Autentication


. A 16 bit number representing the total number of available bytes.
  This has meaning only if the return status is NERR_Success or
  ERROR_MORE_DATA. Upon success, this number indicates the number of
  useful bytes available. Upon failure, this indicates how big the
  receive buffer needs to be.

Transaction Response Data section

The Transaction response data section contains a data structure
user_logoff_info_1 which is defined as:

    struct user_logoff_info_1 {
            unsigned short  usrlogf1_code;
            unsigned long   usrlogf1_duration;
            unsigned short  usrlogf1_num_logons;
    };

where:

  usrlogf1_code specifies the result and can have the following values:

Code                    Value  Description
NERR_Success            0      No errors encountered
ERROR_ACCESS_DENIED     5      User has insufficient privilege
NERR_InvalidWorkstation 2240   The user is not allowed to logon from
                               this computer

  usrlogf1_duration specifies the time in number of seconds for which
       the user was logged

  usrlogf1_num_logons specifies the number of times this user has logged
       on. A value of -1 indicates the number is unknown.

The following table defines the valid fields in the logoff_info_1
structure based upon the return values::

function       usrlogf11_code         Valid elements of  logoff_info_1
return code    element
NERR_Success   NERR_Success           All
NERR_Success   NERR_StandaloneLogon   None except usrlogf1_code
All other      None; the code is      None
errors         meaningless

There is no auxiliary data in the response.

2.6 NetUserGetInfo

This is a function executed on a remote CIFS server to obtain detailed
information about a particular user.

The definition is:

 unsigned short NetUserGetInfo(
   char        *pszUser;

Leach, Naik                                                           13


            CIFS Domain Logon and Pass Through Autentication


   unsigned short    sLevel;
   RCVBUF pBuffer;
   RCVBUFLEN   cbBuffer;
   unsigned short   *pcbTotalAvail;
 );

 where:

   pszUser points to a null terminated ASCII string signifying the
   name of the user for which information should be retrieved.

   sLevel specifies the level of detail returned. The only legal
   value is 11.

   pbBuffer points to the buffer to receive the returned data.

   cbBuffer specifies the size, in bytes, of the buffer pointed to by
   the pbBuffer parameter.

   pcbTotalAvail is a pointer to an unsigned short which gets filled
   with the total number of data bytes available if the function
   succeeds.

Transaction Request Parameters section

The Transaction request parameters section in this instance contains:

. The 16 bit function number for NetUserGetInfo which is 56.
. The parameter descriptor string which is "zWrLh"
. The data descriptor string for the (returned) data which is
  "B21BzzzWDDzzDDWWzWzDWb21W"
. The actual parameters as described by the parameter descriptor
  string.

The parameters are:
. A null terminated ASCII string indicating the user for which
  information should be retrieved.
. A 16 bit integer with a value of decimal 11 (corresponding to the "W"
  in the parameter descriptor string. This represents the level of
  detail the server is expected to return)
. A 16 bit integer that contains the size of the receive buffer


Transaction Request Data section

There is no data or auxiliary data to send as part of the request.

Transaction Response Parameters section

The transaction response parameters section consists of:
. A 16 bit word indicating the return status. The possible values are:

Code                    Value  Description
NERR_Success            0      No errors encountered

Leach, Naik                                                           14


            CIFS Domain Logon and Pass Through Autentication


ERROR_ACCESS_DENIED     5      User has insufficient privilege
ERROR_MORE_DATA         234    additional data is available
NERR_BufTooSmall        2123   The supplied buffer is too small
NERR_UserNotFound       2221   The user name was not found
. A 16 bit "converter" word.
. A 16 bit number representing the total number of available bytes.
  This has meaning only if the return status is NERR_Success or
  ERROR_MORE_DATA. Upon success, this number indicates the number of
  useful bytes available. Upon failure, this indicates how big the
  receive buffer needs to be.

Transaction Response Data section

The Transaction response data section contains a data structure
user_logon_info_1 which is defined as:

    struct user_info_11 {
        char                usri11_name[21];
        char                usri11_pad;
        char                *usri11_comment;
        char            *usri11_usr_comment;
        unsigned short      usri11_priv;
        unsigned long       usri11_auth_flags;
        long                usri11_password_age;
        char                *usri11_homedir;
        char            *usri11_parms;
        long                usri11_last_logon;
        long                usri11_last_logoff;
        unsigned short      usri11_bad_pw_count;
        unsigned short      usri11_num_logons;
        char                *usri11_logon_server;
        unsigned short      usri11_country_code;
        char            *usri11_workstations;
        unsigned long       usri11_max_storage;
        unsigned short      usri11_units_per_week;
        unsigned char       *usri11_logon_hours;
        unsigned short      usri11_code_page;
    };

where:

  usri11_name specifies the user name for which information is retireved

  usri11_pad aligns the next data structure element to a word boundary

  usri11_comment is a null terminated ASCII comment

  usri11_user_comment is a null terminated ASCII comment about the user

  usri11_priv specifies the level of the privilege assigned to the user.
       The possible values are:

Name             Value  Description
USER_PRIV_GUEST  0      Guest privilege

Leach, Naik                                                           15


            CIFS Domain Logon and Pass Through Autentication


USER_PRIV_USER   1      User privilege
USER_PRV_ADMIN   2      Administrator privilege

  usri11_auth_flags specifies the account operator privileges. The
       possible values are:

Name            Value   Description
AF_OP_PRINT     0       Print operator
AF_OP_COMM      1       Communications operator
AF_OP_SERVER    2       Server operator
AF_OP_ACCOUNTS  3       Accounts operator


  usri11_password_age specifies how many seconds have elapsed since the
       password was last changed.

  usri11_home_dir points to a null terminated ASCII string that contains
       the path name of the user's home directory.

  usri11_parms points to a null terminated ASCII string that is set
       aside for use by applications.

  usri11_last_logon specifies the time when the user last logged on.
       This value is stored as the number of seconds elapsed since
       00:00:00, January 1, 1970.

  usri11_last_logoff specifies the time when the user last logged off.
       This value is stored as the number of seconds elapsed since
       00:00:00, January 1, 1970. A value of 0 means the last logoff
       time is unknown.

  usri11_bad_pw_count specifies the number of incorrect passwords
       entered since the last successful logon.

  usri11_log1_num_logons specifies the number of times this user has
       logged on. A value of -1 means the number of logons is unknown.

  usri11_logon_server points to a null terminated ASCII string that
       contains the name of the server to which logon requests are sent.
       A null string indicates logon requests should be sent to the
       domain controller.

  usri11_country_code specifies the country code for the user's language
       of choice.

  usri11_workstations points to a null terminated ASCII string that
       contains the names of workstations the user may log on from.
       There may be up to 8 workstations, with the names separated by
       commas. A null strings indicates there are no restrictions.

  usri11_max_storage specifies the maximum amount of disk space the user
       can occupy. A value of 0xffffffff indicates there are no
       restrictions.


Leach, Naik                                                           16


            CIFS Domain Logon and Pass Through Autentication


  usri11_units_per_week specifies the equal number of time units into
       which a week is divided. This value must be equal to 168.

  usri11_logon_hours points to a 21 byte (168 bits) string that
       specifies the time during which the user can log on. Each bit
       represents one unique hour in a week. The first bit (bit 0, word
       0) is Sunday, 0:00 to 0:59, the second bit (bit 1, word 0) is
       Sunday, 1:00 to 1:59 and so on. A null pointer indicates there
       are no restrictions.

  usri11_code_page specifies the code page for the user's language of
       choice

All of the pointers in this data structure need to be treated
specially. The  pointer is a 32 bit pointer. The higher 16 bits need
to be ignored. The converter word returned in the parameters section
needs to be subtracted from the lower 16 bits to calculate an offset
into the return buffer where this ASCII string resides.

There is no auxiliary data in the response.



3. CIFS pass through authentication

CIFS pass through authentication is a mechanism employed by a CIFS
server to validate user credentials with a Domain Controller and the
grant the user access to a resource on the CIFS server, based upon
successful validation of the user credentials by the Domain Controller.

Note that a CIFS server can do pass through authentication to only a
single domain. Thus the name of the domain is essentially known before a
user even attempts to connect to the CIFS server. The CIFS server
locates the Domain Controller of this single domain of interest using
the mechanism described in section 3.1.3. This mechanism is expensive in
terms of network traffic, so the CIFS server caches the name of the
Domain Controller. The CIFS server can verify this cached information by
sending a NetServerEnum2 RAP request to the Domain Controller and
checking that the returned information still indicates the server to be
a Domain Controller. Complete details of the RAP specification as well
as details of the NetServerEnum2 RAP request may be found in the CIFS
Remote Administration Protocol specification.

Consider the case of a CIFS server running with user level security. The
CIFS document describes a user level (security) server as a server that
requires clients to provide a user name and corresponding password to
connect to any resources shared by the server.

Consider a CIFS client seeking to connect to this CIFS server. The
client is prepared to submit it's credentials (user name and challenge
response). The CIFS server does not have an accounts database that can
establish the validity of the user credentials. This is the situation in
which a CIFS server resorts to pass through authentication. The steps
involved in pass through authentication are:

Leach, Naik                                                           17


            CIFS Domain Logon and Pass Through Autentication


. The CIFS client sends a negotiate SMB to the CIFS server
. The CIFS server verifies the cached Domain Controller name (as
  described above)
. If the cached name is invalid, the CIFS server does a Domain
  Controller Discovery
. The CIFS server  sends a NEGOTIATE SMB to the Domain Controller
. The NEGOTIATE response along with the challenge is saved by the CIFS
  server
. The CIFS server sends a NEGOTIATE response (to client) using the
  saved challenge
. The CIFS client computes the challenge response as detailed in the
  CIFS specification, and then challenge response is sent as part of a
  SessionSetupAndX SMB
. The CIFS server extracts the challenge response from above SMB
. The CIFS server sends it's own SessionSetupAndX SMB to the domain
  controller using the extracted challenge response
. The Domain Controller sends a SessionSetupAndX response to the CIFS
  server. This response will be successful if the CIFS client had
  provided the correct response.
. The CIFS server tears down the session with the Domain Controller
  that was established using user credentials. This is accomplished by
  means of a LogOffAndX SMB.
. The CIFS server sends a SessionSetupAndX response to the CIFS client.
  This response is based upon the response from the Domain Controller.

4. Appendix A - Remote Administration Protocol
A RAP service request is sent to the server encapsulated in a Transact2
request SMB and the server sends back a Transact2 SMB response. An
attribute of the Transact2 SMB is that it divides the payload of request
and response messages into two sections: a parameters section and a data
section. As might be expected from the nomenclature, RAP service
parameters are sent in the parameters section of a Transact2 SMB, and
the data buffer in the data section. Therefore, to define a service
protocol, it is necessary to define the formats of the parameter and
data sections of the Transact2 request and response.

This is done in two stages. First, a C-like declaration notation is used
to define descriptor strings, and then the descriptor strings define the
formats of the  parameter and data sections.. Note well: even though the
declarations may look like a programming interface, they are not: they
are a notation for describing the contents of RAP requests and
responses; an implementation on any particular system can use any
programming interface to RAP services that is appropriate to that
system.
4.1 Notation

Parameter descriptor strings are defined using a C-like function
declaration; data descriptor and auxiliary data descriptor strings are
defined using a C-like structure declaration.

Parameter descriptor strings are defined with the following C-like
function declaration syntax:



Leach, Naik                                                           18


            CIFS Domain Logon and Pass Through Autentication


    rap-service     = "unsigned short" service-name "(" parameters ");"
    service-name        = <upper and lower case alpha and numeric>
The return type of the function is always "unsigned short", and
represents the status code from the function. The service-name is for
documentation purposes.
    parameters      = parameter [ ";" parameter ]
The parameter descriptor string for the service is the concatenation of
the descriptor characters for the parameters.
    parameter       = [ "const" ] param-data-type parameter-name
                      [ "[" size "]" ]
    param-data-type = <from parameter descriptor tables below>
    parameter-name      = <upper and lower case alpha and numeric>
    size                = <string of ASCII 0-9>
The descriptor character for a parameter is determined by looking up the
data-type in the tables below for request or response parameter
descriptors. The parameter-name is for documentation purposes. If there
is a size following the parameter-name, then it is placed in the
descriptor string following the descriptor character.

Data and auxiliary data descriptor strings are defined  with the
following C-like structure declaration syntax:
    rap-struct      = "struct" struct-name "{" members "}"
The descriptor string for the struct is the concatenation of the
descriptor characters for the members. The struct-name is for
documentation purposes.
    members         = member [  ";" member ]
    member          = member-data-type member-name [ "[" size "]" ]
    member-data-type    = <from data descriptor tables below>
The descriptor character for a member is determined by looking up the
data-type in the tables below for data descriptors. The member-name is
for documentation purposes. If there is a size following the member-
name, then it is placed in the descriptor string following the
descriptor character.
4.2 Descriptors

The following section contain tables that specify the descriptor
character and the notation for each data type for that data type.
4.2.1 Request Parameter Descriptors


Descriptor  Data Type        Format
==========  =========        =====
W           unsigned short   indicates parameter type of 16 bit integer
                             (word).
D           unsigned long    indicates parameter type of 32 bit integer
                             (dword).
b           BYTE             indicates bytes (octets). May be followed
                             by an ASCII number indicating number of
                             bytes..
O           NULL             indicates a NULL pointer
z           char             indicates a NULL terminated ASCII string
                             present in the parameter area
F           PAD              indicates Pad bytes (octets). May be
                             followed by an ASCII number indicating the

Leach, Naik                                                           19


            CIFS Domain Logon and Pass Through Autentication


                             number of bytes
r           RCVBUF           pointer to receive data buffer in response
                             parameter section
L           RCVBUFLEN        16 bit integer containing length of
                             receive data buffer in (16 bit) words
s           SNDBUF           pointer to send data buffer in request
                             parameter section
T           SNDBUFLEN        16 bit integer containing length of send
                             data buffer in words

4.2.2 Response Parameter Descriptors


Descriptor  Data Type        Format
==========  =========        =====
g           BYTE *           indicates a byte is  to be received. May
                             be followed by an ASCII number indicating
                             number of bytes to receive
h           unsigned short * indicates a word is to be received
i           unsigned long *  indicates  a dword is to be received
e           ENTCOUNT         indicates a word is to be received  which
                             indicates the number of entries returned

4.2.3 Data Descriptors


Descriptor  Data Type        Format
==========  =========        =====
W           unsigned short   indicates data type of 16 bit integer
                             (word). Descriptor char may be followed by
                             an ASCII number indicating the number of
                             16 bit words present
D           unsigned long    indicates data type of 32 bit integer
                             (dword). Descriptor char may be followed
                             by an ASCII number indicating the number
                             of 32 bit words present
B           BYTE             indicates item of data type 8 bit byte
                             (octet). The indicated number of bytes are
                             present  in the data. Descriptor char may
                             be followed by an ASCII number indicating
                             the number of 8 bit bytes present
O           NULL             indicates a NULL pointer
z           char *           indicates a 32 bit pointer to a NULL
                             terminated ASCII string is present in the
                             response parameter area. The actual string
                             is in the response data area and the
                             pointer in the parameter area points to
                             the string in the data area. The high word
                             of the pointer should be ignored. The
                             converter word present in the response
                             parameter section should be subtracted
                             from the low 16 bit value to obtain an
                             offset into the data area indicating where
                             the data area resides.

Leach, Naik                                                           20


            CIFS Domain Logon and Pass Through Autentication


N           AUXCOUNT         indicates number of auxiliary data
                             structures. The transaction response data
                             section contains an unsigned 16 bit number
                             corresponding to this data item.

4.3 Transaction Request Parameters section

The parameters and data being sent and received are described by ASCII
descriptor strings. These descriptor strings are described in section
4.2.

The parameters section of the Transact2 SMB request contains the
following (in the order described)
. The function number: an unsigned short 16 bit integer identifying the
  function being remoted
. The parameter descriptor string: a null terminated ASCII string
. The data descriptor string: a null terminated ASCII string.
. The request parameters, as described by the parameter descriptor
  string, in the order that the request parameter descriptor characters
  appear in the parameter descriptor string
. An optional auxiliary data descriptor string: a null terminated ASCII
  string. It will be present if there is an auxiliary data structure
  count in the primary data struct (an "N" descriptor in the data
  descriptor string).

RAP requires that the length of the return parameters be less than or
equal to the length of the parameters being sent; this requirement is
made to simply buffer management in implementations. This is reasonable
as the functions were designed to return data in the data section and
use the return parameters for items like data length, handles, etc. If
need be, this restriction can be circumvented by filling in some pad
bytes into the parameters being sent.
4.4 Transaction Request Data section

The Data section for the transaction request is present if the parameter
description string contains an "s" (SENDBUF) descriptor. If present, it
contains:
. A primary data struct, as described by the data descriptor string
. Zero or more instances of the auxiliary data struct, as described by
  the auxiliary data descriptor string. The number of instances is
  determined by the value of the an auxiliary data structure count
  member of the primary data struct, indicated by the "N" (AUXCOUNT)
  descriptor. The auxiliary data is present only if the auxiliary data
  descriptor string is non null.
. Possibly some pad bytes
. The heap: the data referenced by pointers in the primary and
  auxiliary data structs.
4.5 Transaction Response Parameters section

The response sent by the server contains a parameter section which
consists of:
. A 16 bit integer indicating the status or return code. The possible
  values for different functions are different.


Leach, Naik                                                           21


            CIFS Domain Logon and Pass Through Autentication


. A 16 bit converter word, used adjust pointers to information in the
  response data section. Pointers returned within the response buffer
  are 32 bit pointers. The high order 16 bit word should be ignored.
  The converter word needs to be subtracted from the low order  16 bit
  word to arrive at an offset into the response buffer.
. The response parameters, as described by the parameter descriptor
  string, in the order that the response parameter descriptor
  characters appear in the parameter descriptor string.
4.6 Transaction Response Data section

The Data section for the transaction response is present if the
parameter description string contains an "r" (RCVBUF) descriptor. If
present, it contains:
. Zero or more entries. The number of entries is determined by the
  value of the entry count parameter, indicated by the "e"(ENTCOUNT)
  descriptor. Each entry contains:
        . A primary data struct, as described by the data descriptor
          string
        . Zero or more instances of the auxiliary data struct, as
          described by the auxiliary data descriptor string. The number
          of instances is determined by the value of the AUXCOUNT
          member of the primary data struct (whose descriptor is "N").
          The auxiliary data is present only if the auxiliary data
          descriptor string is non null.
. Possibly some pad bytes
. The heap: the data referenced by pointers in the primary and
  auxiliary data structs.


5. Author's Addresses

Paul Leach
Dilip Naik
Microsoft
1 Microsoft Way
Redmond, WA  98052
 paulle@microsoft.com
v-dilipn@microsoft.com

















Leach, Naik                                                           22


Html markup produced by rfcmarkup 1.111, available from https://tools.ietf.org/tools/rfcmarkup/