本文档定义了使用Common Internet File System (CIFS) Transact SMB实现远程过程调用(RPC)样式的机制。详细介绍了请求和服务响应的格式，并通过具体示例展示了客户端如何请求服务器执行特定功能。
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@listserv.msn.com>.
Discussions of the mailing list are archived at
<URL:http://microsoft.ease.lsoft.com/archives/cifs.html>.
ABSTRACT
This specification defines how 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 OR�ed 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 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
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 user�s
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 user�s 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@microsoft.com
v-dilipn@microsoft.com
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.
扫一扫
评论
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
查看更多评论
添加红包
