home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ftp.microsoft.com
/
2002-07-02_ftp.microsoft.com.zip
/
developr
/
drg
/
CIFS
/
cifslog.txt
< prev
next >
Wrap
Text File
|
1997-01-29
|
53KB
|
1,343 lines
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
