path: root/doc/cifsrap2.txt

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.











































Leach, Naik                                        [Page 38]