Ethereal-dev: Re: [Ethereal-dev] smb-browse
Note: This archive is from the project's previous web site, ethereal.com. This list is no longer active.
From: Guy Harris <guy@xxxxxxxxxx>
Date: Fri, 13 Jul 2001 15:07:19 -0700 (PDT)
> Right now I thought of fixing up packet-smb-pipe.c > Do you know of any draft-drafts for that one as well? There're a whole bunch of things that use that mechanism; I've attached the stuff that showed up at one point on the CIFS list.
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@xxxxxxxxxxxxxxxx>.
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
TotalDataCount mailslot
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@xxxxxxxxxxxxx
v-dilipn@xxxxxxxxxxxxx
Leach, Naik 22
CIFS Printing Specification
Network Working Group Paul J. Leach, Microsoft
INTERNET-DRAFT Dilip C. Naik, Microsoft
draft-leach-cifs-print-spec-00.txt
Category: Informational
Expires June 31, 1997 January 31, 1997
CIFS Printing Specification
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@xxxxxxxxxxxxxxxx>.
Discussions of the mailing list are archived at
<URL:http://microsoft.ease.lsoft.com/archives/cifs.html>.
ABSTRACT
This specification defines how clients may submit print requests to a
server using SMBs . The specification also details how clients may
administer printing of the print requests they create, using SMBs
defined in the Common Internet File System specification.
Table of Contents
1. OBJECTIVE...........................................................3
2. PREREQUISITES AND SUGGESTED READING.................................3
Leach, Naik 1
CIFS Printing Specification
3. PRINTING OVERVIEW...................................................3
4. CREATING A PRINT JOB................................................3
4.1 OPEN_PRINT_FILE: CREATE PRINT SPOOL FILE .........................4
4.2 CLOSE_PRINT_FILE: CLOSE AND SPOOL PRINT JOB .....................5
5. REMOTE ADMINISTRATION PROTOCOL AND DOCUMENTATION CONVENTIONS........5
6. PRINT QUEUES AND RELATED FUNCTIONS..................................6
6.1 DATA STRUCTURES RELATED TO PRINT QUEUES ..........................6
6.1.1 Printer Queue Information (Level 3) ...........................6
6.1.2 Printer Queue Information (Level 4) ...........................7
6.1.3 Printer Queue Information (Level 5) ...........................8
6.2 DOSPRINTQENUM ....................................................8
6.3 DOSPRINTQGETINFO ................................................10
7. PRINT JOBS AND MANIPULATING PRINT JOBS.............................12
7.1 DATA STRUCTURES RELATED TO PRINT JOBS ...........................12
7.2 DOSPRINTJOBENUM .................................................14
7.3 DOSPRINTJOBGETINFO ..............................................16
7.4 DOSPRINTJOBCONTINUE .............................................19
7.5 DOSPRINTJOBDEL ..................................................20
8. AUTHOR'S ADDRESSES.................................................21
9. REMOTE ADMINISTRATION PROTOCOL OVERVIEW............................21
10. APPENDIX A - REMOTE ADMINISTRATION PROTOCOL.......................22
10.1 NOTATION .......................................................23
10.2 DESCRIPTORS ....................................................23
10.2.1 Request Parameter Descriptors ...............................23
10.2.2 Response Parameter Descriptors ..............................24
10.2.3 Data Descriptors ............................................24
10.3 TRANSACTION REQUEST PARAMETERS SECTION .........................25
10.4 TRANSACTION REQUEST DATA SECTION ...............................25
10.5 TRANSACTION RESPONSE PARAMETERS SECTION ........................26
10.6 TRANSACTION RESPONSE DATA SECTION ..............................26
11. APPENDIX B........................................................26
11.1.1 TRANSACTIONS ................................................28
Leach, Naik 2
CIFS Printing Specification
1. Objective
This document describes
. how CIFS clients accomplish printing on CIFS servers acting as print
servers.
. how CIFS clients administer printing on CIFS servers.
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.
2. Prerequisites and suggested reading
. Familiarity with Common Internet File Systems specification (CIFS) in
general and the CIFS Remote Administration Protocol in particular.
3. Printing overview
A CIFS client opens a print file on a CIFS server in a manner similar to
opening an ordinary file, but using a different SMB (described in
section 4.1). The CIFS client then writes to the file. When the CIFS
client closes the file, the CIFS print server considers the file to be a
print job or print request that needs to be printed.
The CIFS print server implements a concept of print queues. A print
queue is simply an ordered set of print requests or print jobs. Every
print job is associated with a print queue. A client can control which
print queue a print job is associated with. A printer queue stores print
jobs and sends them one by one to a printer. A print queue may have
multiple physical printers associated with it. Different queues may
share the same printer. Print queues allow administrative convenience
such as selection of a printer, priority assignment for printing,
controlling times during which jobs may print, etc. .
Section 4 describes how a client may generate a print job.
Section 6 describes how a client may enumerate print queues and retrieve
information about a particular print queue.
Section 7 describes how a client may manipulate print jobs, causing
print jobs to be paused, resumed or deleted.
Print queues and print jobs are manipulated using the CIFS Remote
Administration protocol. The CIFS specification includes details on
Remote Administration protocol. For convenience, details have been
duplicated (from the CIFS specification) into Appendix A and Appendix B.
Note that the CIFS specification should be considered a more
authoriative source of information, as compared to Appendix A and B.
4. Creating a Print Job
A CIFS client creates a print job (or a print request) by opening a
print file, writing to the print file and then closing it. A print file
Leach, Naik 3
CIFS Printing Specification
differs from an ordinary file in that a CIFS server tracks a print file
and deletes it automatically when the printing is complete.
A print job is associcated with a print queue. Different print queues
may have different characteristics and may print on different printers.
A client can control which print queue a print job (created by the
client) is associated with. The CIFS print server shares different
queues. A client first creates a connection via a SessionSetupAndX
followed by a TreConnectAndX SMB, specifying the appropriate print queue
share in the TreeConnectAndX SMB. Refer to the CIFS document for details
on the TreeConnectAndX SMB. The TreeConnectAndX will return a Tree Id
(Tid) if the SMB succeeds. This Tid is used when opening a print file.
4.1 OPEN_PRINT_FILE: Create Print Spool file
This message is sent to create a new printer file which will be deleted
once it has been closed and printed. Complete understanding of this
message requires familiarity with the CIFS specification.
Client Request Description
================================== =================================
UCHAR WordCount; Count of parameter words = 2
USHORT SetupLength; Length of printer setup data
USHORT Mode; 0 = Text mode (DOS expands TABs)
1 = Graphics mode
USHORT ByteCount; Count of data bytes; min = 2
UCHAR BufferFormat; 0x04
STRING IdentifierString[]; Identifier string
TID in the SMB header must refer to a printer resource type.
SETUPLENGTH is the number of bytes in the first part of the resulting
print spool file which contains printer-specific control strings.
MODE can have the following values:
0 Text mode. The server may optionally
expand tabs to a series of spaces.
1 Graphics mode. No conversion of data
should be done by the server.
IDENTIFIERSTRING can be used by the server to provide some sort of per-
client identifying component to the print file.
Server Response Description
================================== =================================
UCHAR WordCount; Count of parameter words = 1
USHORT Fid; File handle
Leach, Naik 4
CIFS Printing Specification
USHORT ByteCount; Count of data bytes = 0
FID is the returned handle which may be used by subsequent write and
close operations. When the file is finally closed, it will be sent to
the spooler and printed.
4.2 CLOSE_PRINT_FILE: Close and Spool Print Job
This message invalidates the specified file handle and queues the file
for printing. Complete understanding of this message requires
familiarity with the CIFS specification.
Client Request Description
================================== =================================
UCHAR WordCount; Count of parameter words = 1
USHORT Fid; File handle
USHORT ByteCount; Count of data bytes = 0
FID refers to a file previously created with SMB_COM_OPEN_PRINT_FILE.
On successful completion of this request, the file is queued for
printing by the server.
Server Response Description
================================== =================================
UCHAR WordCount; Count of parameter words = 0
USHORT ByteCount; Count of data bytes = 0
Servers which negotiate dialects of LANMAN1.0 and newer allow all the
other types of FID closing requests to invalidate the FID and begin
spooling.
5. Remote Administration Protocol and Documentation Conventions
Print queue and print job related management functions are accomplished
using the CIFS Remote Administration Protocol (RAP). Complete details
may be found in the CIFS specification and in Appendix A. 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 queries information about print queues
and print jobs and administers print jobs These descriptions assume
knowledge of the CIFS RAP specification.
Leach, Naik 5
CIFS Printing Specification
6. Print Queues and related functions
A CIFS server can enumerate all print queues on a given server using the
DosPrintQEnum function. Once the CIFS client knows the names of each
print queue, the CIFS client can then obtain information about each
print queue using the DosPrintQGetInfo function. Both of these functions
are executed on the remote print server using the CIFS Remote
Administration Protocol, fully detailed in the CIFS document as well as
Appendix A and Appendix B.
6.1 Data structures related to Print queues
This section describes data structures used to describe print queues.
Data structures corresponding to print queue levels 0 , 1 and 2 are
obsolete.
6.1.1 Printer Queue Information (Level 3)
The PRQINFO_3 data structure describes a particular printer queue. The
DosPrintQEnum and DosPrintQGetInfo functions (described below) return
data in this format when the desired level of information is set to
level 3.
struct PRQINFO_3 {
char *pszName;
unsigned short Priority;
unsigned short Starttime;
unsigned short UntilTime;
unsigned short Pad1;
char *pszSepFile;
char *pszPrProc;
char *pszParms;
char *pszComment;
unsigned short Status;
AUXCOUNT cJobs;
char *pszPrinters;
char *pszDriverName
void *pDriverData;
}
where:
pszName points to a null terminated ASCII string that contains the
queue name.
Priority contains an unsigned short integer specifying the printer
queue priority. The value can range from 1(highest) to 9 (lowest).
When two printer queues print to the same printer, the print jobs
from the one with the higher priority print first.
Untiltime contains an unsigned short integer specifying the time
of day a printer queue becomes inactive and stops sending print
jobs to printers. This value represents the number of minutes
since midnight (00:00).
Leach, Naik 6
CIFS Printing Specification
Starttime contains an unsigned short integer specifying the time
of day a printer queue can start sending print jobs to printers.
This value represents the number of minutes since midnight
(00:00).
pszSepFile points to a null terminated ASCII string that
represents the pathname to a seperator page file. The seperator
page contains formatting information about the pages that separate
print jobs.
pszPrProc points to a null terminated ASCII string that
represents the name of the print preprocessor. A null pointer or
null string inidcates the default print preprocessor.
pszDestinations points to a null terminated ASCII string that
contains a list of print destinations for the print queue. This is
a multi-valued property and the values are separated by spaces.
pszParms points to a null terminated ASCII string that contains
parameters required by printer queues.
pszComment points to a null terminated ASCII string that contains
a comment about the print queue.
Status contains an unsigned short integer that specifies the
status of a printer queue. Possible values are:
Code Value Description
PRQ_ACTIVE 0 Active
PRQ_PAUSE 1 Paused
PRQ_ERROR 2 Error Occurred
PRQ_PENDING 3 Deletion pending
cJobs contains an unsigned short integer representing the number
of print jobs currently in the print queue.
pszDriverName points to a null terminated ASCII string
representing the default device driver for the queue. If this
field is null, the pDriverData field is not used.
pDriverData points to the device driver data for the default
driver.
6.1.2 Printer Queue Information (Level 4)
At this level, the returned information consists of a level 3 print
queue data structure (as described in section 5.1.1) followed by a
PRJINFO_2 data structure for each print job in the queue. The PRJINFO_2
data structure is described in section 7.1.
Leach, Naik 7
CIFS Printing Specification
6.1.3 Printer Queue Information (Level 5)
At level 5, the returned data structure is defined as:
struct PRQINFO_5 {
char *pszName;
}
where:
pszName points to a null terminated ASCII string that contains the
queue name.
6.2 DosPrintQEnum
The DosPrintQEnum function lists all printer queues on a server. The
definition is:
unsigned short DosPrintQEnum(
unsigned short sLevel;
RCVBUF pbBuffer;
RCVBUFLEN cbBuffer;
ENTCOUNT pcReturned;
unsigned short *pcTotalAvail;
);
where:
sLevel specifies the level of detail returned. Legal values are
3, 4 and 5 .
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.
pcReturned points to a 16 bit variable that receives a count of
the total number of entries (queues) returned. This count is valid
only if DosPrintQEnum returns the NERR_Success or ERROR_MORE_DATA
values.
pcTotalAvail points to a 16 bit variable that receives a count of
the total number of entries (queues) available. This count is
valid only if DosPrintQEnum returns the NERR_Success or
ERROR_MORE_DATA values.
Transaction Request Parameters section
The Transaction request parameters section in this instance contains:
. The function number for DosPrintQEnum which is 69.
. The parameter descriptor string which is "WrLeh"
. The data descriptor string for the returned data is "zWWWWzzzzWWzzl"
if sLevel (the level of desired information) is 3. This corresponds
Leach, Naik 8
CIFS Printing Specification
to the data structure PRQINFO_3There is no auxiliary data in the
response when the level of desired information is 3.
. The data descriptor string for the returned data is "zWWWWzzzzWNzzl"
if sLevel (the level of desired information) is 4. This corresponds
to the data structure PRQINFO_3. The descriptor for the auxiliary
data returned is "WWzWWDDzz" when the level of desired information
is 4. This corresponds to the PRJINFO_2 data structure.
. The data descriptor string for the returned data is "z" if sLevel
(the level of desired information) is 5. The "z" indicates a null
terminated ASCII string representing the name of the print queue. .
There is no auxiliary data descriptor for this level of information.
. The actual parameters as described by the parameter descriptor
string. These are:
" A 16 bit integer with a value of 3, 4 or 5 (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
ERROR_ACCESS_DENIED 5 The user does not have required
priveleges
ERROR_MORE_DATA 234 Additional data is available
NERR_SpoolerNotLoaded 2161 The spooler is not started on
the remote server
NERR_BadTransactConfig 2141 The server is not configured
for transactions, IPC$ is not
shared
. A 16 bit "converter" word.
. A 16 bit number representing the number of entries returned.
. A 16 bit number representing the total number of available entries.
If the supplied buffer is large enough, this will equal the number of
entries returned.
Transaction Response Data section
The Transaction response data section consists of a series of data
structures. The number of the data structures is equal to the number or
entries being returned, which is the third value in the Transaction
response parameter section.
At information level 3, a series of PRQINFO_3 data structures are
returned. There is no auxiliary data at this information level.
Leach, Naik 9
CIFS Printing Specification
At information level 4, a series of PRQINFO_3 data structures are
returned. There is also auxiliary data present in this case. For each
print job in each print queue, a PRJINFO_2 structure is returned in the
auxiliary data. For each print queue, the data descriptor string element
"N" denotes the number of PRJINFO_2 data structures present in the
auxiliary data for that queue. This also denotes the number of print
jobs associated with that print queue.
At information level 5, a PRQINFO_5 data structure is returned for each
print queue. There is no auxiliary data in the response when the level
of desired information is 5.
As per the RAP specification, all pointers in any of the data
structures returned need to be treated specially in the prescribed
manner.
6.3 DosPrintQGetInfo
The DosPrintQGetInfo function retrieves information about a particular
print queue on a CIFS server. The definition is:
unsigned short DosPrintQGetInfo(
char *pszQueueName;
short sLevel;
RCVBUF pbBuffer;
RCVBUFLEN cbBuffer;
unsigned short *pcbTotalAvail;
);
where:
pszQueueName points to an ASCII null-terminated string specifying the
name of the queue for which information should be retrieved.
sLevel specifies the level of detail returned. (Legal values are 3,
4, and 5 )
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 points to a 16-bit variable that receives a count of the
total number of bytes of information available. This count is valid
only if DosPrintQGetInfo returns the NERR_Success or ERROR_MORE_DATA
values.
Transaction Request Parameters section
The Transaction request parameters section in this instance contains:
. The function number for DosPrintQGetInfo which is 70.
. The parameter descriptor string which is "zWrLh"
Leach, Naik 10
CIFS Printing Specification
. The data descriptor string for the returned data is "zWWWWzzzzWWzzl"
if sLevel (the level of desired information) is 3. This corresponds
to the data structure PRQINFO_3. There is no auxiliary data in the
response when the level of desired information is 3.
. The data descriptor string for the returned data is "zWWWWzzzzWNzzl"
if sLevel (the level of desired information) is 4. This corresponds
to the data structure PRQINFO_3. The descriptor for the auxiliary
data returned is "WWzWWDDzz" when the level of desired information
is 4. This corresponds to the PRJINFO_2 data structure.
. The data descriptor string for the returned data is "z" if sLevel
(the level of desired information) is 5. The "z" indicates a null
terminated ASCII string representing the name of the print queue. .
There is no auxiliary data descriptor for this level of information.
. The actual parameters as described by the parameter descriptor
string. These are:
. A null terminated ASCII string denoting the name of the print
queue for which information should be retrieved.
. A 16 bit integer with a value of 3, 4 or 5 . 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
ERROR_ACCESS_DENIED 5 User has insufficient
privilege
ERROR_MORE_DATA 234 Additional data is
available
NERR_QNotFound 2150 The specified queue name
is invalid
NERR_SpoolerNotLoaded 2161 The spooler is not started
on the remote server
. A 16 bit "converter" word. The value is up to the server to decide.
. A 16 bit number representing the total number of available bytes.
This has meaning only if the return status is NERR_Success,
ERROR_MORE_DATA or NERR_BufTooSmall
Transaction Response Data Section
The Transaction response data section consists of a single data
structure
Leach, Naik 11
CIFS Printing Specification
At information level 3, a PRQINFO_3 data structure is returned. There
is no auxiliary data at this information level.
At information level 4, a PRQINFO_3 data structure is returned. This
data structure describes the print queue of interest. There is also
auxiliary data present in this case. For each print job in the print
queue, a PRJINFO_2 structure is returned in the auxiliary data. The data
descriptor string element "N" denotes the number of PRJINFO_2 data
structures present in the auxiliary data for that queue. This also
denotes the number of print jobs associated with that print queue.
At information level 5, a PRQINFO_5 data structure is returned for each
print queue. There is no auxiliary data in the response when the level
of desired information is 5.
As per the RAP specification, all pointers in any of the data
structures returned need to be treated specially in the prescribed
manner.
7. Print Jobs and manipulating Print Jobs
Once a CIFS client has located a print queue, the client can then
enumerate jobs within that queue using the DosPrintJobEnum function. A
CIFS client may also obtain print job information by means of the
DosPrintQEnum and DosPrintQGetInfo services, specifying a desired
information level of 4. Once the CIFS client has a list of job
identifiers, it can obtain detailed information about any print job
using the DosPrintJobGetInfo function. For print jobs initiated by the
client, and which are not yet printing, the CIFS client can pause,
resume or delete the print jobs using DosPrintJobPause,
DosPrintJobContinue and DosPrintJobDel functions respectively. All of
these DosPrintJobX services are executed on the remote print server
using the CIFS Remote Administration Protocol described in the CIFS
document as well as in Appendix A and Appendix B.
7.1 Data Structures related to Print Jobs
struct PRJINFO_0 {
unsigned short JobId
}
where:
JobId is a 16 bit integer that uniquely specifies a print job
within a printer queue. The JobID is unique on a server. A
combination of the server name and JobId is sufficient to uniquely
identify a particular print job.
Leach, Naik 12
CIFS Printing Specification
struct PRJINFO_2 {
unsigned short JobId;
unsigned short Priority;
char *pszUserName;
unsigned short Position;
unsigned short Status;
unsigned long Submitted;
unsigned long Size;
char *pszComment;
char *pszDocument;
}
where:
JobId is a 16 bit integer that uniquely specifies a print job
within a printer queue. The JobID is unique on a server. A
combination of the server name and JobId is sufficient to uniquely
identify a particular print job.
Priority is a 16 bit integer that specifies the print job
priority. This varies from a value of 1 (lowest priority) to 99
(highest priority. Higher priority jobs print first. When 2 jobs
have the same priority, the older job prints first.
pszUserName is a pointer to a null terminated ASCII string that
specifies the name of the user who submitted the print job.
Position specifies the position of the print job within the print
queue. If the value is 1, this print job prints next.
Status is an integer used as a status flag. The values and
meanings of the various bits are:
Bits Code Value Description
0-1 PRJ_QS_QUEUED 0 Print job is queued
0-1 PRJ_QS_PAUSED 1 Print job is paused
0-1 PRJ_QS_SPOOLING 2 Print job is spooling
0-1 PRJ_QS_PRINTING 3 Print job is printing,
bits 2-11 are valid
Bit Code Value Description
2 PRJ_COMPLETE 0x0004 Print job is complete
3 PRJ_INTERV 0x0008 an error occurred, pszStatus
may contain a comment explaining
the error
4 PRJ_ERROR 0x0010 Print job is spooling
5 PRJ_DESTOFFLINE 0x0020 The print destination is offline
6 PRJ_DESTPAUSED 0x0040 The print destination is paused
7 PRJ_NOTIFY 0x0080 An alert is raised
8 PRJ_DESTNOPAPER 0x0100 The print destination is out of
paper
9 PRJ_DESTFORMCHG 0x0200 The printer is waiting for a
form change
10 PRJ_DESTCRTCHG 0x0400 The printer is waiting for a
Leach, Naik 13
CIFS Printing Specification
cartridge change
11 PRJ_DESTENCHG 0x0800 The printer is waiting for a pen
change
15 PRJ_ PRINTING 0x8000 An alert indicates the job was
deleted
pszStatus points to an ASCII string that contains a comment about
the status of the job. This element contains valid data only when
the job is printing and an error occurs. This element may be null
or point to a null string.
Submitted contains an unsigned long integer specifying when the
user submitted the job. This is stored as the number of seconds
elapsed since 00:00:00 Jan 1st, 1970.
Size contains an unsigned long integer that specifies the size of
the print job in terms of number of bytes.
pszComment points to a null terminated ASCII string that contains
a comment about the print job.
pszDocument points to a null terminated ASCII string that contains
the name of the document.
7.2 DosPrintJobEnum
The DosPrintJobEnum service lists print jobs in the specified printer
queue. The definition is:
unsigned short DosPrintJobEnum(
char *pszQueueName;
short sLevel;
RCVBUF pbBuffer;
RCVBUFLEN cbBuffer;
unsigned short *pcbTotalAvail;
);
where:
pszQueuename points to a null-terminated string specifying the
name of the print queue for which print jobs should be enumerated.
sLevel specifies the level of detail returned. (Legal values are
0 and 2)
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.
Leach, Naik 14
CIFS Printing Specification
pcbTotalAvail points to a 16 bit variable that receives a count of
the total number of bytes of information available. This count is
valid only if the return value is NERR_Success or ERROR_MORE_DATA .
Transaction Request Parameters section
The Transaction request parameters section in this instance contains:
. The function number for DosPrintJobEnum which is 76.
. The parameter descriptor string which is "zWrLeh"
. The data descriptor string for the returned data is "z" if sLevel
(the level of desired information) is 0. This corresponds to the data
structure PRJINFO_0 already described.
. The data descriptor string for the returned data is "WWzWWDDzz" if
sLevel (the level of desired information) is 2. This corresponds to
the PRJINFO_2 data structure.already described.
. The actual parameters as described by the parameter descriptor
string. These are:
. A null terminated ASCII string denoting the name of the print
queue which contains the print job of interest.
. A 16 bit integer with a value of 0 or 2 . This represents the
level of detail the server is expected to return
. A 16 bit integer that contains the size of the receive
buffer.
There is no data or auxiliary data that is sent as part of the
Transaction request.
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
ERROR_MORE_DATA 234 Additional data is
available
NERR_QNotFound 2150 The specified queue name
is invalid
NERR_SpoolerNotLoaded 2161 The spooler is not started
on the remote server
. A 16 bit "converter" word.
Leach, Naik 15
CIFS Printing Specification
. A 16 bit number representing the total number of available entries.
This has meaning only if the return status is NERR_Success,
ERROR_MORE_DATA or NERR_BufTooSmall
Transaction Response Data Section
The Transaction response data section consists of a data structures.
At information level 0, a series of PRJINFO_0 data structures are
returned. The number of structure is equal to the value in the third
parameter in the response parameter section. There is no auxiliary data
at this information level.
At information level 2, a series of PRJINFO_2 data structures are
returned. The number of such data structures returned is equal to the
value in the third parameter of the response parameter section. There is
no auxiliary data present in this case.
As per the RAP specification, all pointers in any of the data
structures returned need to be treated specially in the prescribed
manner.
There is no auxiliary data in the response.
7.3 DosPrintJobGetInfo
The DosPrintJobGetInfo service retrieves information about a particular
print job. The definition is:
unsigned short DosPrintJobGetInfo(
unsigned short JobId;
unsigned short sLevel;
RCVBUF pbBuffer;
RCVBUFLEN cbBuffer;
unsigned short *pcbTotalAvail;
);
where:
JobId specifies identity of the print job for which information
should be retrieved.
Level specifies the level of detail returned. (Legal values are 0
and 2)
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.
Leach, Naik 16
CIFS Printing Specification
pcbTotalAvail points to a 16 bit variable that receives a count of
the total number of bytes of information available. This count is
valid only if DosPrintJobGetInfo returns the
NERR_Success or ERROR_MORE_DATA values.
Transaction Request Parameters section
The Transaction request parameters section in this instance contains:
. The function number for DosPrintJobGetInfo which is 77.
. The parameter descriptor string which is "WWrLh"
. The data descriptor string for the returned data is "z" if sLevel
(the level of desired information) is 0. This corresponds to the data
structure PRJINFO_0 already described.
. The data descriptor string for the returned data is "WWzWWDDzz" if
sLevel (the level of desired information) is 2. This corresponds to
the PRJINFO_2 data structure.already described.
. The actual parameters as described by the parameter descriptor
string. These are:
. A 16 bit integer specifying the identity of the job for which
information should be retrieved.
. A 16 bit integer with a value of 0 or 2 . This represents the
level of detail the server is expected to return
. A 16 bit integer that contains the size of the receive
buffer.
There is no data or auxiliary data that is sent as part of the
Transaction request.
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 The user does not have required
priveleges
ERROR_MORE_DATA 234 Additional data is available
NERR_SpoolerNotLoaded 2161 The spooler is not started on the
remote server
NERR_BadTransactConfig 2141 The server is not configured for
transactions, IPC$ is not shared
. 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,
ERROR_MORE_DATA or NERR_BufTooSmall
Leach, Naik 17
CIFS Printing Specification
Transaction Response Data Section
The return data section consists of a PRJINFO_0 data structure if the
desired level of information is 0. The return data section consists of a
PRJINFO_2 data structure if the desired level of information is 2. These
have already been detailed.
Note that the pointers in the data structure in data structure PRJINFO_2
need to be treated specially. The high 16 bit word needs to be ignored.
The converter word returned in the response parameters section needs to
be subtracted from the low 16 bit value to locate the actual offset of
the item within the response buffer sent by the server.
There is no auxiliary data to receive.
DosPrintJobPause
DosPrintJobPause pauses a print job in a printer queue. The definition
is:
unsigned short DosPrintJobPause(
unsigned short JobId;
);
where:
JobId specifies the identity of the print job that should be
paused
Transaction Request Parameters section
The Transaction request parameters section in this instance contains:
. The function number for DosPrintJobPause which is 82.
. The parameter descriptor string which is "W"
. The data descriptor string is null.
. The actual parameters as described by the parameter descriptor
string. This consists of just a 16 bit integer representing the
JobId, identifying the job to be paused.
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
Leach, Naik 18
CIFS Printing Specification
privilege
ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied
NERR_BadTransactConfig 2141 The server is not configured
for transactions, IPC$ is not
shared
NERR_JobNotFound 2151 The specified print job could
not be located
NERR_SpoolerNotLoaded 2161 The spooler is not started on
the remote server
NERR_JobInvalidState 2164 The operation cannot be
performed on the job in it's
current state(job is already
printing)
Transaction Response Data Section
There is no data or auxiliary data in the response.
7.4 DosPrintJobContinue
DosPrintJobContinue allows a paused print job to resume printing. The
definition is:
unsigned short DosPrintJobContinue(
unsigned short JobId;
);
where:
JobId specifies the identity of the print job that should resume
printing
Transaction Request Parameters section
The Transaction request parameters section in this instance contains:
. The function number for DosPrintJobContinue which is 83.
. The parameter descriptor string which is "W"
. The data descriptor string is null.
. The actual parameters as described by the parameter descriptor
string. This consists of just a 16 bit integer representing the JobId
(identifies job to be paused)
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:
Leach, Naik 19
CIFS Printing Specification
. 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
ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied
NERR_BadTransactConfig 2141 The server is not configured
for transactions, IPC$ is not
shared
NERR_JobNotFound 2151 The specified print job could
not be located
NERR_SpoolerNotLoaded 2161 The spooler is not started on
the remote server
NERR_JobInvalidStatus 2164 The operation cannot be
performed on the print job in
it's current state
Transaction Response Data Section
There is no data or auxiliary data in the response.
7.5 DosPrintJobDel
DosPrintJobDel deletes a print job from a printer queue. The definition
is:
unsigned short DosPrintJobDel(
unsigned short JobId;
);
where:
JobId specifies the identity of the print job that should be
deleted
Transaction Request Parameters section
The Transaction request parameters section in this instance contains:
. The function number for DosPrintJobDel which is 81.
. The parameter descriptor string which is "W"
. The data descriptor string is null.
. The actual parameters as described by the parameter descriptor
string. This consists of just a 16 bit integer representing the JobId
, identifying the job to be paused.
Transaction Request Data section
There is no data or auxiliary data to send as part of the request.
Transaction Response Parameters section
Leach, Naik 20
CIFS Printing Specification
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
ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied
NERR_BadTransactConfig 2141 The server is not
configured for
transactions, IPC$
is not shared
NERR_JobNotFound 2151 The specified print job
could not be located
NERR_ProcNotRespond 2160 The print process is not
responding
NERR_SpoolerNotLoaded 2161 The spooler is not
started on the
remote server
Transaction Response Data Section
There is no data or auxiliary data in the response.
8. Author's Addresses
Paul Leach
Dilip Naik
Microsoft
1 Microsoft Way
Redmond, WA 98052
paulle@xxxxxxxxxxxxx
v-dilipn@xxxxxxxxxxxxx
9. Remote Administration Protocol overview
The Remote Administration Protocol (RAP) is similar to an RPC protocol,
in that:
. it is an at-most-once synchronous request-response protocol
. it is a framework that can be used for remotely requesting many
different kinds of services
. it is designed to allow (but not require) the programming interface
to the protocol to be that of remotely executed procedure calls -
which means that one thinks if the protocol in terms of marshaling
and unmarshaling procedure call input and output arguments into
messages and reliably transporting the messages to and from the
client and server
Each RAP request is characterized by a set of ASCII descriptor strings
that are sufficient to be used to interpretively drive the marshaling
Leach, Naik 21
CIFS Printing Specification
and unmarshaling process, if an implementation wanted to use them for
that purpose. These descriptor strings are included in each request
packet, and make the requests self-describing.
RAP is layered on the CIFS Transact2 SMB, which provides reliable
message delivery, security, and messages larger than the underlying
network maximum packet size. When used for RAP, the name field in the
Transact2 SMB is always set to "\PIPE\LANMAN". The Transact2 SMB is sent
on a session/connection that is established to the remote server using a
SessionSetupAndX SMB, and using a TID obtained by doing a
TreeConnectAndX SMB to a share named "IPC$".
[Refer to the CIFS specification for complete details on SMBs in
general, and the Transact2 SMB in particular. For convenience, relevant
portions from the CIFS specification have been reproduced here in
Appendix A. Note that the CIFS specification should be considered the
authoritative source of information, rather than Appendix A as far as
details on the Transact2 SMB are concerned.]
The model of a RAP service is that there are a few parameters as inputs
and outputs to the service, exactly one of which may be a buffer
descriptor that indicates the presence of a potentially much larger
input or output data buffer. An argument may be a scalar, pointer, fixed
length small array or struct, or a buffer descriptor. The data buffer
consists of entries followed by a heap. An entry consists of a primary
data struct and a sequence of 0 or more auxiliary data structs. An
input buffer must contain exactly one entry; an output buffer may
contain 0 or more. The heap is where data is stored that is referenced
by pointers in the entries. The parameters are described by a parameter
descriptor string; the primary data struct by a data descriptor string;
and the auxiliary data structs by an auxiliary data descriptor string.
10. 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.
Leach, Naik 22
CIFS Printing Specification
10.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:
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.
10.2 Descriptors
The following section contain tables that specify the descriptor
character and the notation for each data type for that data type.
10.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).
Leach, Naik 23
CIFS Printing Specification
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
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
10.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
10.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
Leach, Naik 24
CIFS Printing Specification
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.
N AUXCOUNT indicates number of auxiliary data
structures. The transaction response data
section contains an unsigned 16 bit number
corresponding to this data item.
10.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.
10.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.
Leach, Naik 25
CIFS Printing Specification
. Possibly some pad bytes
. The heap: the data referenced by pointers in the primary and
auxiliary data structs.
10.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.
. 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.
10.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.
11. Appendix B
Transaction SMBs
These SMBs are used both to retrieve bulk data from the server (e.g.:
enumerate shares, etc.) and to change the server's state (EG: add a new
share, change file permissions, etc.) Transaction requests are also
unusual because they can have a multiple part request and/or a multiple
part response. For this reason, transactions are handled as a set of
sequenced commands to the server. Each part of a request is sent as a
sequenced command using the same Mid value and an increasing Seq value.
The server responds to each request piece except the last one with a
response indicating that the server is ready for the next piece. The
last piece is responded to with the first piece of the result data. The
client then sends a transaction secondary SMB with ParameterDisplacement
set to the number of parameter bytes received so far and
DataDisplacement set to the number of data bytes received so far and
ParameterCount, ParameterOffset, DataCount, and DataOffset set to zero
Leach, Naik 26
CIFS Printing Specification
(0). The server responds with the next piece of the transaction result.
The process is repeated until all of the response information has been
received. When the transaction has been completed, the redirector must
send another sequenced command (an echo SMB will do fine) to the server
to allow the server to know that the final piece was received and that
resources allocated to the transaction command may be released.
The flow is as follows, where (S) is the SequenceNumber, (N) is the
number of request packets to be sent from the client to the server, and
(M) is the number of response packets to be sent by the server to the
client:
Client <-> Server
======================= === ===========================
SMB(S) Transact ->
<- OK (S) send more data
[ repeat N-1 times:
SMB(S+1) Transact ->
secondary
<- OK (S+1) send more data
SMB(S+N-1)
]
<- OK (S+N-1) transaction
response (1)
[ repeat M-1 times:
SMB(S+N) Transact ->
secondary
<- OK (S+N) transaction
response (2)
SMB(S+N+M-2) Transact ->
secondary
<- OK (S+N+M-2] transaction
response (M)
]
SMB(S+N+M-1) Echo ->
<- OK (S+N+M-1) echoed
In order to allow the server to detect clients which have been powered
off, have crashed, etc., the client must send commands to the server
periodically if it has resources open on the server. If nothing has
been received from a client for awhile, the server will assume that the
client is no longer running and disconnect the client. This includes
closing any files that the client had open at the time and releasing any
resources being used on behalf of the client. Clients should at least
send an echo SMB to the server every four (4) minutes if there is
nothing else to send. The server will disconnect clients after a
configurable amount of time which cannot be less than five (5) minutes.
(Note: the NT server has a default timeout value of 15 minutes.)
Leach, Naik 27
CIFS Printing Specification
11.1.1 TRANSACTIONS
SMB_COM_TRANSACTION performs a symbolically named transaction. This
transaction is known only by a name (no file handle used).
SMB_COM_TRANSACTION2 likewise performs a transaction, but a word
parameter is used to identify the transaction instead of a name.
SMB_COM_NT_TRANSACTION is used for commands that potentially need to
transfer a large amount of data (greater than 64K bytes).
11.1.1.1 SMB_COM_TRANSACTION AND SMB_COM_TRANSACTION2 FORMATS
Primary Client Request Description
=============================== ====================================
Command SMB_COM_TRANSACTION or
SMB_COM_TRANSACTION2
UCHAR WordCount; Count of parameter words; value =
(14 + SetupCount)
USHORT TotalParameterCount; Total parameter bytes being sent
USHORT TotalDataCount; Total data bytes being sent
USHORT MaxParameterCount; Max parameter bytes to return
USHORT MaxDataCount; Max data bytes to return
UCHAR MaxSetupCount; Max setup words to return
UCHAR Reserved;
USHORT Flags; Additional information:
bit 0 - also disconnect TID in TID
bit 1 - one-way transaction (no
resp)
ULONG Timeout;
USHORT Reserved2;
USHORT ParameterCount; Parameter bytes sent this buffer
USHORT ParameterOffset; Offset (from header start) to
Parameters
USHORT DataCount; Data bytes sent this buffer
USHORT DataOffset; Offset (from header start) to data
UCHAR SetupCount; Count of setup words
UCHAR Reserved3; Reserved (pad above to word)
USHORT Setup[SetupCount]; Setup words (# = SetupWordCount)
USHORT ByteCount; Count of data bytes
STRING Name[]; Name of transaction (NULL if
SMB_COM_TRANSACTION2)
UCHAR Pad[]; Pad to SHORT or LONG
UCHAR Parameters[ Parameter bytes (# = ParameterCount)
ParameterCount];
UCHAR Pad1[]; Pad to SHORT or LONG
UCHAR Data[ DataCount ]; Data bytes (# = DataCount)
Leach, Naik 28
CIFS Printing Specification
Interim Server Response Description
=============================== ====================================
UCHAR WordCount; Count of parameter words = 0
USHORT ByteCount; Count of data bytes = 0
Secondary Client Request Description
=============================== ====================================
Command SMB_COM_TRANSACTION_SECONDARY
UCHAR WordCount; Count of parameter words = 8
USHORT TotalParameterCount; Total parameter bytes being sent
USHORT TotalDataCount; Total data bytes being sent
USHORT ParameterCount; Parameter bytes sent this buffer
USHORT ParameterOffset; Offset (from header start) to
Parameters
USHORT ParameterDisplacement; Displacement of these Parameter
bytes
USHORT DataCount; Data bytes sent this buffer
USHORT DataOffset; Offset (from header start) to data
USHORT DataDisplacement; Displacement of these data bytes
USHORT Fid; FID for handle based requests, else
0xFFFF. This field is present only
if this is an SMB_COM_TRANSACTION2
request.
USHORT ByteCount; Count of data bytes
UCHAR Pad[]; Pad to SHORT or LONG
UCHAR Parameter bytes (# = ParameterCount)
Parameters[ParameterCount];
UCHAR Pad1[]; Pad to SHORT or LONG
UCHAR Data[DataCount]; Data bytes (# = DataCount)
Leach, Naik 29
CIFS Printing Specification
Server Response Description
=============================== ====================================
UCHAR WordCount; Count of data bytes; value = 10 +
SETUPCOUNT
USHORT TotalParameterCount; Total parameter bytes being sent
USHORT TotalDataCount; Total data bytes being sent
USHORT Reserved;
USHORT ParameterCount; Parameter bytes sent this buffer
USHORT ParameterOffset; Offset (from header start) to
Parameters
USHORT ParameterDisplacement; Displacement of these Parameter
bytes
USHORT DataCount; Data bytes sent this buffer
USHORT DataOffset; Offset (from header start) to data
USHORT DataDisplacement; Displacement of these data bytes
UCHAR SetupCount; Count of setup words
UCHAR Reserved2; Reserved (pad above to word)
USHORT Setup[SetupWordCount]; Setup words (# = SetupWordCount)
USHORT ByteCount; Count of data bytes
UCHAR Pad[]; Pad to SHORT or LONG
UCHAR Parameter bytes (# = ParameterCount)
Parameters[ParameterCount];
UCHAR Pad1[]; Pad to SHORT or LONG
UCHAR Data[DataCount]; Data bytes (# = DataCount)
Leach, Naik 30
Network Working Group Paul J. Leach, Microsoft
INTERNET-DRAFT Dilip C. Naik, Microsoft
draft-leach-cifs-rap-spec-00.txt
Category: Informational
Expires August 26, 1997 February 26, 1997
CIFS Remote Administration Protocol
Preliminary Draft
STATUS OF THIS MEMO
THIS IS A PRELIMINARY DRAFT OF AN INTERNET-DRAFT. IT DOES NOT REPRESENT
THE CONSENSUS OF THE 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@xxxxxxxxxxxxxxxx>.
Discussions of the mailing list are archived at
<URL:http://microsoft.ease.lsoft.com/archives/cifs.html>.
ABSTRACT
This specification defines how an RPC like mechanism may be implemented
using the Common Internet File System (CIFS) Transact SMB. Specific
examples are provided of how a CIFS client may request a CIFS server to
execute a function. The examples show complete details of the request
sent by the CIFS client and the response from the CIFS server.
Table of Contents
1.OBJECTIVE...........................................................2
2.PREREQUISITES AND SUGGESTED READING.................................2
3.REMOTE ADMINISTRATION PROTOCOL OVERVIEW.............................3
Leach, Naik [Page 1]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
4.REMOTE ADMINISTRATION PROTOCOL......................................3
4.1 NOTATION.........................................................4
4.2 DESCRIPTORS......................................................5
4.2.1Request Parameter Descriptors.................................5
4.2.2Response Parameter Descriptors................................5
4.2.3Data Descriptors..............................................6
4.3 TRANSACTION REQUEST PARAMETERS SECTION...........................6
4.4 TRANSACTION REQUEST DATA SECTION.................................7
4.5 TRANSACTION RESPONSE PARAMETERS SECTION..........................7
4.6 TRANSACTION RESPONSE DATA SECTION................................7
5.NETSHAREENUM........................................................8
6.NETSERVERENUM2.....................................................10
7.NETSERVERGETINFO...................................................13
8.NETSHAREGETINFO....................................................15
9.NETWKSTAUSERLOGON..................................................19
10. NETWKSTAUSERLOGOFF...............................................24
11. NETUSERGETINFO...................................................26
12. NETWKSTAGETINFO..................................................30
13. SAMOEMCHANGEPASSWORD.............................................32
14. AUTHOR'S ADDRESSES...............................................34
15. APPENDIX A.......................................................34
15.1.1...................................................TRANSACTIONS 36
16. APPENDIX B.......................................................38
16.1MARSHALING AND UNMARSHALING USING DESCRIPTOR STRINGS............38
1. Objective
This document details an RPC like mechanism used by CIFS clients to
submit requests to CIFS servers and obtain the results of the request
back from the server.
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.
2. Prerequisites and suggested reading
Leach, Naik [Page 2]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
@ Familiarity with Common Internet File Systems specification (CIFS)
3. Remote Administration Protocol overview
The Remote Administration Protocol (RAP) is similar to an RPC protocol,
in that:
@ it is an at-most-once synchronous request-response protocol
@ it is a framework that can be used for remotely requesting many
different kinds of services
@ it is designed to allow (but not require) the programming interface
to the protocol to be that of remotely executed procedure calls -
which means that one thinks if the protocol in terms of marshaling
and unmarshaling procedure call input and output arguments into
messages and reliably transporting the messages to and from the
client and server
Each RAP request is characterized by a set of ASCII descriptor strings
that are sufficient to be used to interpretively drive the marshaling
and unmarshaling process, if an implementation wanted to use them for
that purpose. These descriptor strings are included in each request
packet, and make the requests self-describing.
RAP is layered on the CIFS Transact SMB, which provides reliable message
delivery, security, and messages larger than the underlying network
maximum packet size. When used for RAP, the name field in the Transact
SMB is always set to "\PIPE\LANMAN". The Transact SMB is sent on a
session/connection that is established to the remote server using a
SessionSetupAndX SMB, and using a TID obtained by doing a
TreeConnectAndX SMB to a share named "IPC$".
[Refer to the CIFS specification for complete details on SMBs in
general, and the Transact SMB in particular. For convenience, relevant
portions from the CIFS specification have been reproduced here in
Appendix A. Note that the CIFS specification should be considered the
authoritative source of information, rather than Appendix A as far as
details on the Transact SMB are concerned.]
The model of a RAP service is that there are a few parameters as inputs
and outputs to the service, exactly one of which may be a buffer
descriptor that indicates the presence of a potentially much larger
input or output data buffer. An argument may be a scalar, pointer, fixed
length small array or struct, or a buffer descriptor. The data buffer
consists of entries followed by a heap. An entry consists of a primary
data struct and a sequence of 0 or more auxiliary data structs. An
input buffer must contain exactly one entry; an output buffer may
contain 0 or more. The heap is where data is stored that is referenced
by pointers in the entries. The parameters are described by a parameter
descriptor string; the primary data struct by a data descriptor string;
and the auxiliary data structs by an auxiliary data descriptor string.
4. Remote Administration Protocol
Leach, Naik [Page 3]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
A RAP service request is sent to the server encapsulated in a Transact
request SMB and the server sends back a Transact SMB response. An
attribute of the Transact 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 Transact 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 Transact 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:
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 "]" ]
Leach, Naik [Page 4]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
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
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
Leach, Naik [Page 5]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
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.
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 Transact 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
Leach, Naik [Page 6]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
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.
@ 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
Leach, Naik [Page 7]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
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. NetShareEnum
The NetShareEnum RAP function retrieves information about each shared
resource on a CIFS server. The definition is:
unsigned short NetShareEnum(
unsigned short sLevel;
RCVBUF pbBuffer;
RCVBUFLEN cbBuffer;
ENTCOUNT pcEntriesRead;
unsigned short *pcTotalAvail;
);
where:
sLevel specifies the level of detail returned and must have the
value of 1.
pbBuffer points to the buffer to receive the returned data. If the
function is successful, the buffer contains a sequence of
SHARE_INFO_1 structures (defined later).
cbBuffer specifies the size, in bytes, of the buffer pointed to by
the pbBuffer parameter.
pcEntriesRead points to a 16 bit variable that receives a count of
the number of shared resources enumerated in the buffer. This
count is valid only if NetShareEnum returns the NERR_Success or
ERROR_MORE_DATA values.
pcTotalAvail points to a 16-bit variable that receives a count of
the total number of shared resources. This count is valid only if
NetShareEnum returns the NERR_Success or ERROR_MORE_DATA values.
Transaction Request Parameters section
The Transaction request parameters section in this instance contains:
@ The 16 bit function number for NetShareEnum which is 0.
@ The parameter descriptor string which is "WrLeh".
@ The data descriptor string for the (returned) data which is "B13BWz"
@ The actual parameters as described by the parameter descriptor
string.
The parameters are:
@ 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
Leach, Naik [Page 8]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
@ 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
ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied
ERROR_MORE_DATA 234 Additional data is available
NERR_ServerNotStarted 2114 The server service on the remote
computer is not running
NERR_BadTransactConfig 2141 The server is not configured for
transactions, IPC$ is not shared
@ A 16 bit "converter" word.
@ A 16 bit number representing the number of entries returned.
@ A 16 bit number representing the total number of available entries.
If the supplied buffer is large enough, this will equal the number of
entries returned.
Transaction Response Data section
The return data section consists of a number of SHARE_INFO_1 structures.
The number of such structures present is determined by the third entry
(described above) in the return parameters section.
The SHARE_INFO_1 structure is defined as:
struct SHARE_INFO_1 {
char shi1_netname[13]
char shi1_pad;
unsigned short shi1_type
char *shi1_remark;
}
where:
shi1_netname contains a null terminated ASCII string that
specifies the share name of the resource.
shi1_pad aligns the next data strructure element to a word
boundary.
shi1_type contains an integer that specifies the type of the
shared resource. The possible values are:
Leach, Naik [Page 9]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
Name Value Description
STYPE_DISKTREE 0 Disk Directory Tree
STYPE_PRINTQ 1 Printer Queue
STYPE_DEVICE 2 Communications device
STYPE_IPC 3 Inter process communication (IPC)
shi1_remark points to a null terminated ASCII string that contains
a comment abthe shared resource. The value for shi1_remark is null
for ADMIN$ and IPC$ share names. The shi1_remark 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.
In case there are multiple SHARE_INFO_1 data structures to return,
the server may put all these fixed length structures in the return
buffer, leave some space and then put all the variable length data
(the actual value of the shi1_remark strings) at the end of the
buffer.
There is no auxiliary data to receive.
6. NetServerEnum2
The NetServerEnum2 RAP service lists all computers of the specified
type or types that are visible in the specified domains. It may also
enumerate domains. The definition is:
unsigned short NetServerEnum2 (
unsigned short sLevel,
RCVBUF pbBuffer,
RCVBUFLEN cbBuffer,
ENTCOUNT pcEntriesRead,
unsigned short *pcTotalAvail,
unsigned long fServerType,
char *pszDomain,
);
where :
sLevel specifies the level of detail (0 or 1) requested.
pbBuffer points to the buffer to receive the returned data. If the
function is successful, the buffer contains a sequence of
server_info_x structures, where x is 0 or 1, depending on the
level of detail requested.
cbBuffer specifies the size, in bytes, of the buffer pointed to by
the pbBuffer parameter.
pcEntriesRead points to a 16 bit variable that receives a count of
the number of servers enumerated in the buffer. This count is
Leach, Naik [Page 10]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
valid only if NetServerEnum2 returns the NERR_Success or
ERROR_MORE_DATA values.
pcTotal Avail points to a 16 bit variable that receives a count of
the total number of available entries. This count is valid only if
NetServerEnum2 returns the NERR_Success or ERROR_MORE_DATA values.
fServerType specifies the type or types of computers to enumerate.
Computers that match at least one of the specified types are
returned in the buffer. Possible values are defined in the request
parameters section.
pszDomain points to a null-terminated string that contains the
name of the workgroup in which to enumerate computers of the
specified type or types. If the pszDomain parameter is a null
string or a null pointer, servers are enumerated for the current
domain of the computer.
Transaction Request Parameters section
The Transaction request parameters section in this instance contains:
@ The 16 bit function number for NetServerEnum2 which is 104.
@ The parameter descriptor string which is "WrLehDz".
@ The data descriptor string for the (returned) data which is "B16" for
level detail 0 or "B16BBDz" for level detail 1.
@ The actual parameters as described by the parameter descriptor
string.
The parameters are:
@ A 16 bit integer with a value of 0 or 1 (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.
@ A 32 bit integer that represents the type of servers the function
should enumerate. The possible values may be any of the following or
a combination of the following:
SV_TYPE_WORKSTATION 0x00000001 All workstations
SV_TYPE_SERVER 0x00000002 All servers
SV_TYPE_SQLSERVER 0x00000004 Any server running with SQL
server
SV_TYPE_DOMAIN_CTRL 0x00000008 Primary domain controller
SV_TYPE_DOMAIN_BAKCTRL 0x00000010 Backup domain controller
SV_TYPE_TIME_SOURCE 0x00000020 Server running the timesource
service
SV_TYPE_AFP 0x00000040 Apple File Protocol servers
SV_TYPE_NOVELL 0x00000080 Novell servers
SV_TYPE_DOMAIN_MEMBER 0x00000100 Domain Member
SV_TYPE_PRINTQ_SERVER 0x00000200 Server sharing print queue
SV_TYPE_DIALIN_SERVER 0x00000400 Server running dialin service.
SV_TYPE_XENIX_SERVER 0x00000800 Xenix server
SV_TYPE_NT 0x00001000 NT server
SV_TYPE_WFW 0x00002000 Server running Windows for
Leach, Naik [Page 11]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
Workgroups
SV_TYPE_SERVER_NT 0x00008000 Windows NT non DC server
SV_TYPE_POTENTIAL_BROWSER 0x00010000 Server that can run the browser
service
SV_TYPE_BACKUP_BROWSER 0x00020000 Backup browser server
SV_TYPE_MASTER_BROWSER 0x00040000 Master browser server
SV_TYPE_DOMAIN_MASTER 0x00080000 Domain Master Browser server
SV_TYPE_LOCAL_LIST_ONLY 0x40000000 Enumerate only entries marked
"local"
SV_TYPE_DOMAIN_ENUM 0x80000000 Enumerate Domains. The pszServer
and pszDomain parameters must be
NULL.
@ A null terminated ASCII string representing the pszDomain parameter
described above
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_MORE_DATA 234 Additional data is available
NERR_ServerNotStarted 2114 The RAP service on the remote
computer is not running
NERR_BadTransactConfig 2141 The server is not configured for
transactions, IPC$ is not shared
@ A 16 bit "converter" word.
@ A 16 bit number representing the number of entries returned.
@ A 16 bit number representing the total number of available entries.
If the supplied buffer is large enough, this will equal the number of
entries returned.
Transaction Response Data section
The return data section consists of a number of SHARE_INFO_1 structures.
The number of such structures present is determined by the third entry
(described above) in the return parameters section.
At level detail 0, the Transaction response data section contains a
number of SERVER_INFO_0 data structure. The number of such structures is
equal to the 16 bit number returned by the server in the third parameter
in the Transaction response parameter section. The SERVER_INFO_0 data
structure is defined as:
struct SERVER_INFO_0 {
char sv0_name[16];
};
Leach, Naik [Page 12]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
where:
sv0_name is a null-terminated string that specifies the name of a
computer or domain .
At level detail 1, the Transaction response data section contains a
number of SERVER_INFO_1 data structure. The number of such structures is
equal to the 16 bit number returned by the server in the third parameter
in the Transaction response parameter section. The SERVER_INFO_1 data
structure is defined as:
struct SERVER_INFO_1 {
char sv1_name[16];
char sv1_version_major;
char sv1_version_minor;
unsigned long sv1_type;
char *sv1_comment_or_master_browser;
};
sv1_name contains a null-terminated string that specifies the name
of a computer.
sv1_version_major specifies the major release version number of
the networking software the server is running. This is entirely
informational and something the caller of the NetServerEnum2
function gets to see.
sv1_version_minor specifies the minor release version number of
the networking software the server is running. This is entirely
informational and something the caller of the NetServerEnum2
function gets to see.
sv1_type specifies the type of software the computer is running.
The member can be one or a combination of the values defined above
in the Transaction request parameters section for fServerType.
sv1_comment_or_master_browser points to a null-terminated string. If
the sv1_type indicates that the entry is for a domain, this
specifies the name of the domain master browser; otherwise, it
specifies a comment describing the server. The comment can be a null
string or the pointer may be a null pointer.
In case there are multiple SERVER_INFO_1 data structures to
return, the server may put all these fixed length structures in
the return buffer, leave some space and then put all the variable
length data (the actual value of the sv1_comment strings) at the
end of the buffer.
There is no auxiliary data to receive.
7. NetServerGetInfo
Leach, Naik [Page 13]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
The NetServerGetInfo function returns information about the specified
server. The definition is:
unsigned short NetServerGetInfo(
unsigned short sLevel;
RCVBUF pbBuffer;
RCVBUFLEN cbBuffer;
unsigned short *pcbTotalAvail;
);
where:
sLevel specifies the level of detail returned. (Legal values are
0 and 1)
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 points to a 16 bit variable that receives a count of
the total number of bytes of information available. This count is
valid only if NetServerGetInfo returns the
NERR_Success or ERROR_MORE_DATA values.
The return value is one of the following:
Transaction Request Parameters section
The Transaction request parameters section in this instance contains:
@ The 16 bit function number for NetServerGetInfo which is 13.
@ The parameter descriptor string which is "WrLh"
@ The data descriptor string for the (returned) data which is "B16" for
level detail 0 or "B16BBDz" for level detail 1.
@ The actual parameters as described by the parameter descriptor
string.
The parameters are:
@ A 16 bit integer with a value of 0 or 1 (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 [Page 14]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
ERROR_MORE_DATA 234 Additional data is available
NERR_ServerNotStarted 2114 The RAP service on the remote
computer is not running
NERR_BadTransactConfig 2141 The server is not configured for
transactions, IPC$ is not shared
@ 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. In case of success, this will indicate the number of
useful bytes available. In case of failure, this indicates the
required size of the receive buffer.
Transaction Response Data section
At level detail 0, the Transaction response data section contains a
SERVER_INFO_0 data structure. The SERVER_INFO_0 data structure is
defined in section 7.4
At level detail 1, the Transaction response data section contains a
SERVER_INFO_1 data structure. The SERVER_INFO_1 data structure is
defined in section 7.4
There is no auxiliary data to receive.
8. NetShareGetInfo
The NetShareGetInfo function retrieves information about a particular
shared resource on a CIFS server. The definition is:
unsigned short NetShareGetInfo(
char *pszNetName;
unsigned short sLevel;
RCVBUF pbBuffer;
RCVBUFLEN cbBuffer;
unsigned short *pcbTotalAvail;
);
where:
pszNetName points to an ASCII null-terminated string specifying
the name of the shared resource for which information should be
retrieved.
sLevel specifies the level of detail returned. (Legal values are
0, 1 and 2)
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 points to a 16 bit variable that receives a count of
the total number of bytes of information available. This count is
Leach, Naik [Page 15]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
valid only if NetShareGetInfo returns the NERR_Success or
ERROR_MORE_DATA values.
Transaction Request Parameters section
The Transaction request parameters section in this instance contains:
@ The 16 bit function number for NetServerGetInfo which is 1.
@ The parameter descriptor string which is "zWrLh"
@ The data descriptor string for the (returned) data which is "B13" for
level detail 0 or "B13BWz" for level detail 1 or "B13BWzWWWzB9B"
for level detail 2.
@ The actual parameters as described by the parameter descriptor
string.
The parameters are:
@ A null terminated ASCII string indicating the share for which
information should be retrieved.
@ A 16 bit integer with a value of 0, 1 or 2 (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
ERROR_MORE_DATA 234 Additional data is available
NERR_ServerNotStarted 2114 The RAP service on the remote
computer is not running
NERR_BadTransactConfig 2141 The server is not configured for
transactions, IPC$ is not shared
@ 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
At level detail 0, the Transaction response data section contains a
SHARE_INFO_0 data structure, which is defined as:
struct SHARE_INFO_0 {
char shi1_netname[13]
}
Leach, Naik [Page 16]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
where:
shi0_netname contains an ASCIIZ string that specifies the share
name of the resource.
At level detail 1, the Transaction response data section contains a
SHARE_INFO_1 data structure, which is defined as:
struct SHARE_INFO_1 {
char shi1_netname[13]
char shi1_pad;
unsigned short shi1_type
char *shi1_remark;
}
where
shi1_netname contains an ASCIIZ string that specifies the share
name of the resource.
shi1_pad aligns the next data structure element to a word
boundary.
shi1_type contains an integer that specifies the type of the
shared resource. The possible values are:
Name Value Description
STYPE_DISKTREE 0 Disk Directory Tree
STYPE_PRINTQ 1 Printer Queue
STYPE_DEVICE 2 Communications device
STYPE_IPC 3 Inter process communication (IPC)
shi1_remark points to a null-terminated string that specifies a
comment describing the share. The comment can be a null string or
the pointer may be a null pointer.
The shi1_remark pointer is a 32 bit pointer. The higher 16 bits
must 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.
At level detail 2, the Transaction response data section contains a
SHARE_INFO_2 data structure, which is defined as:
struct SHARE_INFO_2 {
char shi2_netname[13]
char shi2_pad;
unsigned short shi2_type
char * shi2_remark;
unsigned short shi2_permissions;
unsigned short shi2_max_uses;
unsigned short shi2_current_uses;
unsigned short shi2_path;
unsigned short shi2_passwd[9]
Leach, Naik [Page 17]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
unsigned short shi2_pad2;
}
where
shi2_netname contains a null terminated ASCII string that
specifies the share name of the resource.
shi2_pad aligns the next data strructure element to a word
boundary.
shi2_type contains an integer that specifies the type of the
shared resource. The possible values are:
Name Value Description
STYPE_DISKTREE 0 Disk Directory Tree
STYPE_PRINTQ 1 Printer Queue
STYPE_DEVICE 2 Communications device
STYPE_IPC 3 Inter process
communication (IPC)
shi2_remark is a pointer to a null terminated ASCII string
specifying a comment for the share
shi2_permissions specifies the permissions on the shared resource
if the CIFS server is operating with share level security. The
values are this element can take are defined as a series of bit
masks that may be ORed with each other. The bit mask values are:
Name Bit Mask Value Description
ACCESS_READ 0x01 Permission to read & execute from resource
ACCESS_WRITE 0x02 Permission to write data to resource
ACCESS_CREATE 0x04 Permission to create an instance of the
resource
ACCESS_EXEC 0x08 Permission to execute from resource
ACCESS_DELETE 0x10 Permission to delete the resource
ACCESS_ATRIB 0x20 Permission to modify the resource
attributes such as date & time of last
modification, etc
ACCESS_PERM 0x40 Permission to change permissions on the
resource
ACCESS_ALL 0x7F All of the above permissions
shi2_max_uses specifies the maximum number of current uses the
shared resource can accommodate. A Value of -1 indicates there is
no limit.
shi2_current_uses specifies the current number of connections to
the resource
shi2_path point to an ASCIIZ string that contains the local (on
the remote CIFS server) path name of the shared resource.
Leach, Naik [Page 18]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
@ For printer resources, shi2_path specifies the name of the
printer queue being shared
@ For disk devices, shi2_path specifies the path being shared
@ For communication device queues, shi2_path specifies the name of
the of the communication device
@ For ADMIN$ or IPC$ resources, shi2_path must be a null pointer
shi2_passwd specifies the password for the resource in case the
CIFS server is running with share level security. For CIFS servers
running with user level security, this field is set to null and is
ignored.
shi2_pad2 is just a pad byte
All of the pointers to an ASCII string in this data structure
(shi2_remark and shi2_path) 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.
9. 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(
char *reserved1;
char *reserved2;
unsigned short sLevel;
BYTE bReqBuffer[54];
unsigned short cbReqBuffer;
RCVBUF pbBuffer;
RCVBUFLEN cbBuffer;
unsigned short *pcbTotalAvail;
);
where:
Leach, Naik [Page 19]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
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 "OOWb54WrLh"
@ 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 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
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
Leach, Naik [Page 20]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
The transaction response parameters section consists of:
@ A 16 bit word indicating the return status. The possible values are:
Code Valu Description
e
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:
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:
Leach, Naik [Page 21]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
usrlog1_code specifies the result and can have the following values:
Code Valu Description
e
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 users 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
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
Leach, Naik [Page 22]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
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.
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.
Leach, Naik [Page 23]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
10. 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.
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
Leach, Naik [Page 24]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
@ 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.
@ 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
Leach, Naik [Page 25]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
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.
11. 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;
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
Leach, Naik [Page 26]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
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 Valu Description
e
NERR_Success 0 No errors encountered
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;
char *usri11_full_name;
unsigned short usri11_priv;
unsigned long usri11_auth_flags;
Leach, Naik [Page 27]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
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_full_name is a null terminated ASCII specifying the full name
of 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
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.
Leach, Naik [Page 28]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
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.
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.
Leach, Naik [Page 29]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
There is no auxiliary data in the response.
12. NetWkstaGetInfo
This is a function executed on a remote CIFS server to obtain detailed
information about a workstation.
The definition is:
unsigned short NetWkstaGetInfo(
unsigned short sLevel;
RCVBUF pBuffer;
RCVBUFLEN cbBuffer;
unsigned short *pcbTotalAvail;
);
where:
sLevel specifies the level of detail returned. The only legal
value is 10.
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 NetWkstaGetInfo which is 63.
@ The parameter descriptor string which is "WrLh"
@ The data descriptor string for the (returned) data which is
"zzzBBzz".
@ The actual parameters as described by the parameter descriptor
string.
The parameters are:
@ A 16 bit integer with a value of decimal 10 (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:
Leach, Naik [Page 30]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
@ A 16 bit word indicating the return status. The possible values are:
Code Valu Description
e
NERR_Success 0 No errors encountered
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 *wki10_computername;
char *wki10_username;
char *wki10_langroup;
unsigned char wki10_ver_major;
unsigned char wki10_ver_minor;
char *wki10_logon_domain;
char *wki10_oth_domains;
};
where:
wki10_computername is a pointer to a NULL terminated ASCII string that
specifies the name of the workstation.
wki10_username is a pointer to a NULL terminated ASCII string that
specifies the user who is logged on at the workstation.
wki10_langroup is a pointer to a NULL terminated ASCII string that
specifies the domain to which the workstation belongs.
wki10_ver_major specifies the major version number of the networking
software the workstation is running.
wki10_ver_minor specifies the minor version number of the networking
software the workstation is running.
wki10_logon domain is a pointer to a NULL terminated ASCII string that
specifies the domain for which a user is logged on.
wki10_oth domain is a pointer to a NULL terminated ASCII string that
specifies all domains in which the computer is enlisted.
Leach, Naik [Page 31]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
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.
13. SamOemChangePassword
This is a function executed on a remote CIFS server to change a users
password.
The definition is:
unsigned short SamOemChangePassword(
uchar *UserName;
uchar *OldPassword;
uchar *NewPassword;
);
where:
UserName is a pointer to a NULL terminated ASCII string
representing the name of the user for which the password should be
changed.
OldPassword is a pointer to a NULL terminated ASCII string
representing the current password of the user
NewPassword is a pointer to a NULL terminated ASCII string
representing the new password of the
Transaction Request Parameters section
The Transaction request parameters section in this instance contains:
@ The 16 bit function number for SamOEMChangePassword which is 214.
@ The parameter descriptor string which is "zsT"
@ The actual parameters as described by the parameter descriptor
string.
The parameters are:
@ A null terminated ASCII string that represents the name of the user
for whom the password is being changed.
@ A word with a value of 532 representing the size of the data buffer.
Transaction Request Data section
The data buffer to be sent consists of 532 bytes of data. The first 516
bytes represent the new password in an encrypted form. The last 16 bytes
represent the old password in an encrypted form.
Leach, Naik [Page 32]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
The new password is represented by the structure
struct {
char NewPasswordBuffer[512];
long LengthofNewPasswordInBytes;
}
The new password is stored in plain text form at the end of the buffer
and the length of the new password is stored in the second member of the
structure. The whole structure is encrypted using RC4. The RC4 key used
is the One Way Transformation (described below) of the old password.
The RC4 encryption of the One Way Transformation of the old password
constitutes the last 16 bytes of the data buffer. The RC4 key used is
the One Way Transformation of the new password
There is no auxiliary data to send as part of the request.
One Way Transformation
This section describes the algorithm used by CIFS to apply a one way
transformation on data.
Let
E(K, D)
denote the DES block mode encryption function [5] , which accepts a
seven byte key (K) and an eight byte data block (D) and produces an
eight byte encrypted data block as its value.
concat(A, B)
is the result of concatenating A and B
Ex(K,D)
denote the extension of DES to longer keys and data blocks. If the
data to be encrypted is longer than eight bytes, the encryption
function is applied to each block of eight bytes in sequence and the
results are concatenated together. If the key is longer than seven
bytes, each 8 byte block of data is first completely encrypted using
the first seven bytes of the key, then the second seven bytes, etc.,
appending the results each time. For example, to encrypt the 16 byte
quantity D0D1 with the 14 byte key K0K1,
Ex(K0K1,D0D1) = concat(E(K0,D0),E(K0,D1),E(K1,D0),E(K1,D1))
head(S, B)
denote the first B bytes of the byte string S.
swab(S)
denote the byte string obtained by reversing the order of the bits in
each byte of S, i.e., if S is byte string of length one, with the
value 0x37 then swab(S) is 0xEC.
Leach, Naik [Page 33]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
The One Way Transformation function is defined as:
OWF = Ex(swab(P14), N8)
Where
@ P14 is the data to encrypted. If P14 is the users password, it is a
clear, upper-cased text string, padded with blanks
@ N8 is an 8 byte string whose value is available from Microsoft upon
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 Valu Description
e
NERR_Success 0 No errors encountered
ERROR_ACCESS_DENIED 5 User has insufficient privilege
ERROR-INVALID-PASSWORD 86 The specified password is invalid
NERR_PasswordCantChange 2243 The password cannot be changed
NERR_PasswordTooShort 2246 The password is too short
Transaction Response Data section
There is no Transaction Response Data to receive
There is no auxiliary data in the response.
14. Author's Addresses
Paul Leach
Dilip Naik
Microsoft
1 Microsoft Way
Redmond, WA 98052
paulle@xxxxxxxxxxxxx
v-dilipn@xxxxxxxxxxxxx
15. Appendix A
Transaction SMBs
These SMBs are used both to retrieve bulk data from the server (e.g.:
enumerate shares, etc.) and to change the server's state (EG: add a new
share, change file permissions, etc.) Transaction requests are also
unusual because they can have a multiple part request and/or a multiple
Leach, Naik [Page 34]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
part response. For this reason, transactions are handled as a set of
sequenced commands to the server. Each part of a request is sent as a
sequenced command using the same Mid value and an increasing Seq value.
The server responds to each request piece except the last one with a
response indicating that the server is ready for the next piece. The
last piece is responded to with the first piece of the result data. The
client then sends a transaction secondary SMB with ParameterDisplacement
set to the number of parameter bytes received so far and
DataDisplacement set to the number of data bytes received so far and
ParameterCount, ParameterOffset, DataCount, and DataOffset set to zero
(0). The server responds with the next piece of the transaction result.
The process is repeated until all of the response information has been
received. When the transaction has been completed, the redirector must
send another sequenced command (an echo SMB will do fine) to the server
to allow the server to know that the final piece was received and that
resources allocated to the transaction command may be released.
The flow is as follows, where (S) is the SequenceNumber, (N) is the
number of request packets to be sent from the client to the server, and
(M) is the number of response packets to be sent by the server to the
client:
Client <-> Server
======================= === ===========================
SMB(S) Transact ->
<- OK (S) send more data
[ repeat N-1 times:
SMB(S+1) Transact ->
secondary
<- OK (S+1) send more data
SMB(S+N-1)
]
<- OK (S+N-1) transaction
response (1)
[ repeat M-1 times:
SMB(S+N) Transact ->
secondary
<- OK (S+N) transaction
response (2)
SMB(S+N+M-2) Transact ->
secondary
<- OK (S+N+M-2] transaction
response (M)
]
SMB(S+N+M-1) Echo ->
<- OK (S+N+M-1) echoed
In order to allow the server to detect clients which have been powered
off, have crashed, etc., the client must send commands to the server
periodically if it has resources open on the server. If nothing has
been received from a client for awhile, the server will assume that the
client is no longer running and disconnect the client. This includes
closing any files that the client had open at the time and releasing any
resources being used on behalf of the client. Clients should at least
Leach, Naik [Page 35]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
send an echo SMB to the server every four (4) minutes if there is
nothing else to send. The server will disconnect clients after a
configurable amount of time which cannot be less than five (5) minutes.
(Note: the NT server has a default timevalue of 15 minutes.)
15.1.1 TRANSACTIONS
SMB_COM_TRANSACTION performs a symbolically named transaction. This
transaction is known only by a name (no file handle used).
SMB_COM_TRANSACTION2 likewise performs a transaction, but a word
parameter is used to identify the transaction instead of a name.
SMB_COM_NT_TRANSACTION is used for commands that potentially need to
transfer a large amount of data (greater than 64K bytes).
15.1.1.1 SMB_COM_TRANSACTION AND SMB_COM_TRANSACTION2 FORMATS
Primary Client Request Description
=============================== ==================================
Command SMB_COM_TRANSACTION or
SMB_COM_TRANSACTION2
UCHAR WordCount; Count of parameter words; value
= (14 + SetupCount)
USHORT TotalParameterCount; Total parameter bytes being sent
USHORT TotalDataCount; Total data bytes being sent
USHORT MaxParameterCount; Max parameter bytes to return
USHORT MaxDataCount; Max data bytes to return
UCHAR MaxSetupCount; Max setup words to return
UCHAR Reserved;
USHORT Flags; Additional information:
bit 0 - also disconnect TID in
TID
bit 1 - one-way transaction (no
resp)
ULONG Timeout;
USHORT Reserved2;
USHORT ParameterCount; Parameter bytes sent this buffer
USHORT ParameterOffset; Offset (from header start) to
Parameters
USHORT DataCount; Data bytes sent this buffer
USHORT DataOffset; Offset (from header start) to data
UCHAR SetupCount; Count of setup words
UCHAR Reserved3; Reserved (pad above to word)
USHORT Setup[SetupCount]; Setup words (# = SetupWordCount)
USHORT ByteCount; Count of data bytes
STRING Name[]; Name of transaction (NULL if
SMB_COM_TRANSACTION2)
UCHAR Pad[]; Pad to SHORT or LONG
UCHAR Parameters[ParameterCount]; Parameter bytes (# =
ParameterCount)
UCHAR Pad1[]; Pad to SHORT or LONG
UCHAR Data[ DataCount ]; Data bytes (# = DataCount)
Interim Server Response Description
Leach, Naik [Page 36]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
=============================== =================================
UCHAR WordCount; Count of parameter words = 0
USHORT ByteCount; Count of data bytes = 0
Secondary Client Request Description
=============================== ==================================
Command SMB_COM_TRANSACTION_SECONDARY
UCHAR WordCount; Count of parameter words = 8
USHORT TotalParameterCount; Total parameter bytes being sent
USHORT TotalDataCount; Total data bytes being sent
USHORT ParameterCount; Parameter bytes sent this buffer
USHORT ParameterOffset; Offset (from header start) to
Parameters
USHORT ParameterDisplacement; Displacement of these Parameter
bytes
USHORT DataCount; Data bytes sent this buffer
USHORT DataOffset; Offset (from header start) to data
USHORT DataDisplacement; Displacement of these data bytes
USHORT Fid; FID for handle based requests,
else 0xFFFF. This field is
present only if this is an
SMB_COM_TRANSACTION2 request.
USHORT ByteCount; Count of data bytes
UCHAR Pad[]; Pad to SHORT or LONG
UCHAR Parameters[ParameterCount]; Parameter bytes (# =
ParameterCount)
UCHAR Pad1[]; Pad to SHORT or LONG
UCHAR Data[DataCount]; Data bytes (# = DataCount)
Server Response Description
=============================== ==================================
UCHAR WordCount; Count of data bytes; value = 10 +
SETUPCOUNT
USHORT TotalParameterCount; Total parameter bytes being sent
USHORT TotalDataCount; Total data bytes being sent
USHORT Reserved;
USHORT ParameterCount; Parameter bytes sent this buffer
USHORT ParameterOffset; Offset (from header start) to
Parameters
USHORT ParameterDisplacement; Displacement of these Parameter
bytes
USHORT DataCount; Data bytes sent this buffer
USHORT DataOffset; Offset (from header start) to data
USHORT DataDisplacement; Displacement of these data bytes
UCHAR SetupCount; Count of setup words
UCHAR Reserved2; Reserved (pad above to word)
USHORT Setup[SetupWordCount]; Setup words (# = SetupWordCount)
USHORT ByteCount; Count of data bytes
UCHAR Pad[]; Pad to SHORT or LONG
UCHAR Parameters[ParameterCount]; Parameter bytes (# =
ParameterCount)
UCHAR Pad1[]; Pad to SHORT or LONG
Leach, Naik [Page 37]
INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
UCHAR Data[DataCount]; Data bytes (# = DataCount)
16. Appendix B
16.1 Marshaling and unmarshaling using descriptor strings
TBD. This will be a note to explain how the descriptor strings can be
used to drive a marshaling engine that can automatically marshal and
unmarshal RAP messages and call local APIs whose calling sequences
closely match the format of the RAP services.
Leach, Naik [Page 38]
- References:
- Re: [Ethereal-dev] smb-browse
- From: Ronnie Sahlberg
- Re: [Ethereal-dev] smb-browse
- Prev by Date: Re: [Ethereal-dev] mergecap patch: dissimilar frame encapsulation types
- Next by Date: Re: [Ethereal-dev] mergecap patch: dissimilar frame encapsulation types
- Previous by thread: Re: [Ethereal-dev] smb-browse
- Next by thread: Re: [Ethereal-dev] smb-browse
- Index(es):
