summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rwxr-xr-xdoc/cifsrap2.txt2427
1 files changed, 2427 insertions, 0 deletions
diff --git a/doc/cifsrap2.txt b/doc/cifsrap2.txt
new file mode 100755
index 0000000..64a2cd7
--- /dev/null
+++ b/doc/cifsrap2.txt
@@ -0,0 +1,2427 @@
1
2
3
4
5
6
7Network Working Group Paul J. Leach, Microsoft
8INTERNET-DRAFT Dilip C. Naik, Microsoft
9draft-leach-cifs-rap-spec-00.txt
10Category: Informational
11Expires August 26, 1997 February 26, 1997
12
13 CIFS Remote Administration Protocol
14 Preliminary Draft
15
16STATUS OF THIS MEMO
17
18THIS IS A PRELIMINARY DRAFT OF AN INTERNET-DRAFT. IT DOES NOT REPRESENT
19THE CONSENSUS OF THE ANY WORKING GROUP.
20
21This document is an Internet-Draft. Internet-Drafts are working
22documents of the Internet Engineering Task Force (IETF), its areas, and
23its working groups. Note that other groups may also distribute working
24documents as Internet-Drafts.
25
26Internet-Drafts are draft documents valid for a maximum of six months
27and may be updated, replaced, or obsoleted by other documents at any
28time. It is inappropriate to use Internet-Drafts as reference material
29or to cite them other than as "work in progress".
30
31To learn the current status of any Internet-Draft, please check the
32"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
33Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
34munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
35ftp.isi.edu (US West Coast).
36
37Distribution of this document is unlimited. Please send comments to the
38authors or the CIFS mailing list at <cifs@listserv.msn.com>.
39Discussions of the mailing list are archived at
40<URL:http://microsoft.ease.lsoft.com/archives/cifs.html>.
41
42
43ABSTRACT
44
45This specification defines how an RPC like mechanism may be implemented
46using the Common Internet File System (CIFS) Transact SMB. Specific
47examples are provided of how a CIFS client may request a CIFS server to
48execute a function. The examples show complete details of the request
49sent by the CIFS client and the response from the CIFS server.
50
51
52Table of Contents
53
54
551.OBJECTIVE...........................................................2
56
572.PREREQUISITES AND SUGGESTED READING.................................2
58
593.REMOTE ADMINISTRATION PROTOCOL OVERVIEW.............................3
60
61
62
63
64Leach, Naik [Page 1]
65
66
67INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
68
69
704.REMOTE ADMINISTRATION PROTOCOL......................................3
71
72 4.1 NOTATION.........................................................4
73 4.2 DESCRIPTORS......................................................5
74 4.2.1Request Parameter Descriptors.................................5
75 4.2.2Response Parameter Descriptors................................5
76 4.2.3Data Descriptors..............................................6
77 4.3 TRANSACTION REQUEST PARAMETERS SECTION...........................6
78 4.4 TRANSACTION REQUEST DATA SECTION.................................7
79 4.5 TRANSACTION RESPONSE PARAMETERS SECTION..........................7
80 4.6 TRANSACTION RESPONSE DATA SECTION................................7
81
825.NETSHAREENUM........................................................8
83
846.NETSERVERENUM2.....................................................10
85
867.NETSERVERGETINFO...................................................13
87
888.NETSHAREGETINFO....................................................15
89
909.NETWKSTAUSERLOGON..................................................19
91
9210. NETWKSTAUSERLOGOFF...............................................24
93
9411. NETUSERGETINFO...................................................26
95
9612. NETWKSTAGETINFO..................................................30
97
9813. SAMOEMCHANGEPASSWORD.............................................32
99
10014. AUTHOR'S ADDRESSES...............................................34
101
10215. APPENDIX A.......................................................34
103
104 15.1.1...................................................TRANSACTIONS 36
105
10616. APPENDIX B.......................................................38
107
108 16.1MARSHALING AND UNMARSHALING USING DESCRIPTOR STRINGS............38
109
110
111
112
1131. Objective
114
115This document details an RPC like mechanism used by CIFS clients to
116submit requests to CIFS servers and obtain the results of the request
117back from the server.
118
119For convenience, some sections from the CIFS specification have been
120reproduced in part within this document. Note that the CIFS
121specification should be considered to be the authoritative reference, in
122case of any doubts, rather than this document.
123
1242. Prerequisites and suggested reading
125
126
127
128
129Leach, Naik [Page 2]
130
131
132INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
133
134
135@ Familiarity with Common Internet File Systems specification (CIFS)
136
137
1383. Remote Administration Protocol overview
139
140The Remote Administration Protocol (RAP) is similar to an RPC protocol,
141in that:
142@ it is an at-most-once synchronous request-response protocol
143@ it is a framework that can be used for remotely requesting many
144 different kinds of services
145@ it is designed to allow (but not require) the programming interface
146 to the protocol to be that of remotely executed procedure calls –
147 which means that one thinks if the protocol in terms of marshaling
148 and unmarshaling procedure call input and output arguments into
149 messages and reliably transporting the messages to and from the
150 client and server
151Each RAP request is characterized by a set of ASCII descriptor strings
152that are sufficient to be used to interpretively drive the marshaling
153and unmarshaling process, if an implementation wanted to use them for
154that purpose. These descriptor strings are included in each request
155packet, and make the requests self-describing.
156
157RAP is layered on the CIFS Transact SMB, which provides reliable message
158delivery, security, and messages larger than the underlying network
159maximum packet size. When used for RAP, the name field in the Transact
160SMB is always set to "\PIPE\LANMAN". The Transact SMB is sent on a
161session/connection that is established to the remote server using a
162SessionSetupAndX SMB, and using a TID obtained by doing a
163TreeConnectAndX SMB to a share named "IPC$".
164
165[Refer to the CIFS specification for complete details on SMBs in
166general, and the Transact SMB in particular. For convenience, relevant
167portions from the CIFS specification have been reproduced here in
168Appendix A. Note that the CIFS specification should be considered the
169authoritative source of information, rather than Appendix A as far as
170details on the Transact SMB are concerned.]
171
172The model of a RAP service is that there are a few parameters as inputs
173and outputs to the service, exactly one of which may be a buffer
174descriptor that indicates the presence of a potentially much larger
175input or output data buffer. An argument may be a scalar, pointer, fixed
176length small array or struct, or a buffer descriptor. The data buffer
177consists of entries followed by a heap. An entry consists of a primary
178data struct and a sequence of 0 or more auxiliary data structs. An
179input buffer must contain exactly one entry; an output buffer may
180contain 0 or more. The heap is where data is stored that is referenced
181by pointers in the entries. The parameters are described by a parameter
182descriptor string; the primary data struct by a data descriptor string;
183and the auxiliary data structs by an auxiliary data descriptor string.
184
185
1864. Remote Administration Protocol
187
188
189
190
191Leach, Naik [Page 3]
192
193
194INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
195
196
197A RAP service request is sent to the server encapsulated in a Transact
198request SMB and the server sends back a Transact SMB response. An
199attribute of the Transact SMB is that it divides the payload of request
200and response messages into two sections: a parameters section and a data
201section. As might be expected from the nomenclature, RAP service
202parameters are sent in the parameters section of a Transact SMB, and the
203data buffer in the data section. Therefore, to define a service
204protocol, it is necessary to define the formats of the parameter and
205data sections of the Transact request and response.
206
207This is done in two stages. First, a C-like declaration notation is used
208to define descriptor strings, and then the descriptor strings define the
209formats of the parameter and data sections.. Note well: even though the
210declarations may look like a programming interface, they are not: they
211are a notation for describing the contents of RAP requests and
212responses; an implementation on any particular system can use any
213programming interface to RAP services that is appropriate to that
214system.
215
2164.1 Notation
217
218Parameter descriptor strings are defined using a C-like function
219declaration; data descriptor and auxiliary data descriptor strings are
220defined using a C-like structure declaration.
221
222Parameter descriptor strings are defined with the following C-like
223function declaration syntax:
224
225 rap-service = "unsigned short" service-name "(" parameters ");"
226 service-name = <upper and lower case alpha and numeric>
227The return type of the function is always "unsigned short", and
228represents the status code from the function. The service-name is for
229documentation purposes.
230
231 parameters = parameter [ ";" parameter ]
232The parameter descriptor string for the service is the concatenation of
233the descriptor characters for the parameters.
234
235 parameter = [ "const" ] param-data-type parameter-name
236 [ "[" size "]" ]
237 param-data-type = <from parameter descriptor tables below>
238 parameter-name = <upper and lower case alpha and numeric>
239 size = <string of ASCII 0-9>
240The descriptor character for a parameter is determined by looking up the
241data-type in the tables below for request or response parameter
242descriptors. The parameter-name is for documentation purposes. If there
243is a size following the parameter-name, then it is placed in the
244descriptor string following the descriptor character.
245
246Data and auxiliary data descriptor strings are defined with the
247following C-like structure declaration syntax:
248
249 rap-struct = "struct" struct-name "{" members "}"
250The descriptor string for the struct is the concatenation of the
251descriptor characters for the members. The struct-name is for
252documentation purposes.
253
254 members = member [ ";" member ]
255 member = member-data-type member-name [ "[" size "]" ]
256
257
258Leach, Naik [Page 4]
259
260
261INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
262
263
264
265 member-data-type = <from data descriptor tables below>
266The descriptor character for a member is determined by looking up the
267data-type in the tables below for data descriptors. The member-name is
268for documentation purposes. If there is a size following the member-
269name, then it is placed in the descriptor string following the
270descriptor character.
271
2724.2 Descriptors
273
274The following section contain tables that specify the descriptor
275character and the notation for each data type for that data type.
276
2774.2.1 Request Parameter Descriptors
278
279
280Descriptor Data Type Format
281========== ========= =====
282W unsigned short indicates parameter type of 16 bit integer
283 (word).
284D unsigned long indicates parameter type of 32 bit integer
285 (dword).
286b BYTE indicates bytes (octets). May be followed
287 by an ASCII number indicating number of
288 bytes..
289O NULL indicates a NULL pointer
290z char indicates a NULL terminated ASCII string
291 present in the parameter area
292F PAD indicates Pad bytes (octets). May be
293 followed by an ASCII number indicating the
294 number of bytes
295r RCVBUF pointer to receive data buffer in response
296 parameter section
297L RCVBUFLEN 16 bit integer containing length of
298 receive data buffer in (16 bit) words
299s SNDBUF pointer to send data buffer in request
300 parameter section
301T SNDBUFLEN 16 bit integer containing length of send
302 data buffer in words
303
304
3054.2.2 Response Parameter Descriptors
306
307
308Descriptor Data Type Format
309========== ========= =====
310g BYTE * indicates a byte is to be received. May
311 be followed by an ASCII number indicating
312 number of bytes to receive
313h unsigned short * indicates a word is to be received
314i unsigned long * indicates a dword is to be received
315e ENTCOUNT indicates a word is to be received which
316 indicates the number of entries returned
317
318
319
320
321Leach, Naik [Page 5]
322
323
324INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
325
326
3274.2.3 Data Descriptors
328
329
330Descriptor Data Type Format
331========== ========= =====
332W unsigned short indicates data type of 16 bit integer
333 (word). Descriptor char may be followed by
334 an ASCII number indicating the number of
335 16 bit words present
336D unsigned long indicates data type of 32 bit integer
337 (dword). Descriptor char may be followed
338 by an ASCII number indicating the number
339 of 32 bit words present
340B BYTE indicates item of data type 8 bit byte
341 (octet). The indicated number of bytes are
342 present in the data. Descriptor char may
343 be followed by an ASCII number indicating
344 the number of 8 bit bytes present
345O NULL indicates a NULL pointer
346z char * indicates a 32 bit pointer to a NULL
347 terminated ASCII string is present in the
348 response parameter area. The actual string
349 is in the response data area and the
350 pointer in the parameter area points to
351 the string in the data area. The high word
352 of the pointer should be ignored. The
353 converter word present in the response
354 parameter section should be subtracted
355 from the low 16 bit value to obtain an
356 offset into the data area indicating where
357 the data area resides.
358N AUXCOUNT indicates number of auxiliary data
359 structures. The transaction response data
360 section contains an unsigned 16 bit number
361 corresponding to this data item.
362
363
3644.3 Transaction Request Parameters section
365
366The parameters and data being sent and received are described by ASCII
367descriptor strings. These descriptor strings are described in section
3684.2.
369
370The parameters section of the Transact SMB request contains the
371following (in the order described)
372@ The function number: an unsigned short 16 bit integer identifying the
373 function being remoted
374@ The parameter descriptor string: a null terminated ASCII string
375@ The data descriptor string: a null terminated ASCII string.
376@ The request parameters, as described by the parameter descriptor
377 string, in the order that the request parameter descriptor characters
378 appear in the parameter descriptor string
379@ An optional auxiliary data descriptor string: a null terminated ASCII
380 string. It will be present if there is an auxiliary data structure
381
382
383Leach, Naik [Page 6]
384
385
386INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
387
388
389 count in the primary data struct (an "N" descriptor in the data
390 descriptor string).
391
392RAP requires that the length of the return parameters be less than or
393equal to the length of the parameters being sent; this requirement is
394made to simply buffer management in implementations. This is reasonable
395as the functions were designed to return data in the data section and
396use the return parameters for items like data length, handles, etc. If
397need be, this restriction can be circumvented by filling in some pad
398bytes into the parameters being sent.
399
4004.4 Transaction Request Data section
401
402The Data section for the transaction request is present if the parameter
403description string contains an "s" (SENDBUF) descriptor. If present, it
404contains:
405@ A primary data struct, as described by the data descriptor string
406@ Zero or more instances of the auxiliary data struct, as described by
407 the auxiliary data descriptor string. The number of instances is
408 determined by the value of the an auxiliary data structure count
409 member of the primary data struct, indicated by the "N" (AUXCOUNT)
410 descriptor. The auxiliary data is present only if the auxiliary data
411 descriptor string is non null.
412@ Possibly some pad bytes
413@ The heap: the data referenced by pointers in the primary and
414 auxiliary data structs.
415
4164.5 Transaction Response Parameters section
417
418The response sent by the server contains a parameter section which
419consists of:
420@ A 16 bit integer indicating the status or return code. The possible
421 values for different functions are different.
422@ A 16 bit converter word, used adjust pointers to information in the
423 response data section. Pointers returned within the response buffer
424 are 32 bit pointers. The high order 16 bit word should be ignored.
425 The converter word needs to be subtracted from the low order 16 bit
426 word to arrive at an offset into the response buffer.
427@ The response parameters, as described by the parameter descriptor
428 string, in the order that the response parameter descriptor
429 characters appear in the parameter descriptor string.
430
4314.6 Transaction Response Data section
432
433The Data section for the transaction response is present if the
434parameter description string contains an "r" (RCVBUF) descriptor. If
435present, it contains:
436@ Zero or more entries. The number of entries is determined by the
437 value of the entry count parameter, indicated by the "e"(ENTCOUNT)
438 descriptor. Each entry contains:
439 @ A primary data struct, as described by the data descriptor
440 string
441 @ Zero or more instances of the auxiliary data struct, as
442 described by the auxiliary data descriptor string. The number
443
444
445Leach, Naik [Page 7]
446
447
448INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
449
450
451 of instances is determined by the value of the AUXCOUNT
452 member of the primary data struct (whose descriptor is "N").
453 The auxiliary data is present only if the auxiliary data
454 descriptor string is non null.
455@ Possibly some pad bytes
456@ The heap: the data referenced by pointers in the primary and
457 auxiliary data structs.
458
4595. NetShareEnum
460
461The NetShareEnum RAP function retrieves information about each shared
462resource on a CIFS server. The definition is:
463
464 unsigned short NetShareEnum(
465 unsigned short sLevel;
466 RCVBUF pbBuffer;
467 RCVBUFLEN cbBuffer;
468 ENTCOUNT pcEntriesRead;
469 unsigned short *pcTotalAvail;
470 );
471
472 where:
473
474 sLevel specifies the level of detail returned and must have the
475 value of 1.
476
477 pbBuffer points to the buffer to receive the returned data. If the
478 function is successful, the buffer contains a sequence of
479 SHARE_INFO_1 structures (defined later).
480
481 cbBuffer specifies the size, in bytes, of the buffer pointed to by
482 the pbBuffer parameter.
483
484 pcEntriesRead points to a 16 bit variable that receives a count of
485 the number of shared resources enumerated in the buffer. This
486 count is valid only if NetShareEnum returns the NERR_Success or
487 ERROR_MORE_DATA values.
488
489 pcTotalAvail points to a 16-bit variable that receives a count of
490 the total number of shared resources. This count is valid only if
491 NetShareEnum returns the NERR_Success or ERROR_MORE_DATA values.
492
493Transaction Request Parameters section
494
495The Transaction request parameters section in this instance contains:
496
497@ The 16 bit function number for NetShareEnum which is 0.
498@ The parameter descriptor string which is "WrLeh".
499@ The data descriptor string for the (returned) data which is "B13BWz"
500@ The actual parameters as described by the parameter descriptor
501 string.
502
503The parameters are:
504@ A 16 bit integer with a value of 1 (corresponding to the "W" in the
505 parameter descriptor string. This represents the level of detail the
506 server is expected to return
507
508
509Leach, Naik [Page 8]
510
511
512INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
513
514
515@ A 16 bit integer that contains the size of the receive buffer.
516
517
518Transaction Request Data section
519
520There is no data or auxiliary data to send as part of the request.
521
522
523Transaction Response Parameters section
524
525The transaction response parameters section consists of:
526@ A 16 bit word indicating the return status. The possible values are:
527
528Code Value Description
529NERR_Success 0 No errors encountered
530ERROR_ACCESS_DENIED 5 User has insufficient privilege
531ERROR_NETWORK_ACCESS_DENIED 65 Network access is denied
532ERROR_MORE_DATA 234 Additional data is available
533NERR_ServerNotStarted 2114 The server service on the remote
534 computer is not running
535NERR_BadTransactConfig 2141 The server is not configured for
536 transactions, IPC$ is not shared
537
538@ A 16 bit "converter" word.
539@ A 16 bit number representing the number of entries returned.
540@ A 16 bit number representing the total number of available entries.
541 If the supplied buffer is large enough, this will equal the number of
542 entries returned.
543
544Transaction Response Data section
545
546The return data section consists of a number of SHARE_INFO_1 structures.
547The number of such structures present is determined by the third entry
548(described above) in the return parameters section.
549
550
551The SHARE_INFO_1 structure is defined as:
552
553 struct SHARE_INFO_1 {
554 char shi1_netname[13]
555 char shi1_pad;
556 unsigned short shi1_type
557 char *shi1_remark;
558 }
559
560where:
561
562 shi1_netname contains a null terminated ASCII string that
563 specifies the share name of the resource.
564
565 shi1_pad aligns the next data strructure element to a word
566 boundary.
567
568 shi1_type contains an integer that specifies the type of the
569 shared resource. The possible values are:
570
571
572
573Leach, Naik [Page 9]
574
575
576INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
577
578
579
580
581Name Value Description
582STYPE_DISKTREE 0 Disk Directory Tree
583STYPE_PRINTQ 1 Printer Queue
584STYPE_DEVICE 2 Communications device
585STYPE_IPC 3 Inter process communication (IPC)
586
587 shi1_remark points to a null terminated ASCII string that contains
588 a comment abthe shared resource. The value for shi1_remark is null
589 for ADMIN$ and IPC$ share names. The shi1_remark pointer is a 32
590 bit pointer. The higher 16 bits need to be ignored. The converter
591 word returned in the parameters section needs to be subtracted
592 from the lower 16 bits to calculate an offset into the return
593 buffer where this ASCII string resides.
594
595 In case there are multiple SHARE_INFO_1 data structures to return,
596 the server may put all these fixed length structures in the return
597 buffer, leave some space and then put all the variable length data
598 (the actual value of the shi1_remark strings) at the end of the
599 buffer.
600
601There is no auxiliary data to receive.
602
603
6046. NetServerEnum2
605
606The NetServerEnum2 RAP service lists all computers of the specified
607type or types that are visible in the specified domains. It may also
608enumerate domains. The definition is:
609
610unsigned short NetServerEnum2 (
611 unsigned short sLevel,
612 RCVBUF pbBuffer,
613 RCVBUFLEN cbBuffer,
614 ENTCOUNT pcEntriesRead,
615 unsigned short *pcTotalAvail,
616 unsigned long fServerType,
617 char *pszDomain,
618 );
619
620 where :
621
622 sLevel specifies the level of detail (0 or 1) requested.
623
624 pbBuffer points to the buffer to receive the returned data. If the
625 function is successful, the buffer contains a sequence of
626 server_info_x structures, where x is 0 or 1, depending on the
627 level of detail requested.
628
629 cbBuffer specifies the size, in bytes, of the buffer pointed to by
630 the pbBuffer parameter.
631
632 pcEntriesRead points to a 16 bit variable that receives a count of
633 the number of servers enumerated in the buffer. This count is
634
635
636
637Leach, Naik [Page 10]
638
639
640INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
641
642
643 valid only if NetServerEnum2 returns the NERR_Success or
644 ERROR_MORE_DATA values.
645
646 pcTotal Avail points to a 16 bit variable that receives a count of
647 the total number of available entries. This count is valid only if
648 NetServerEnum2 returns the NERR_Success or ERROR_MORE_DATA values.
649
650 fServerType specifies the type or types of computers to enumerate.
651 Computers that match at least one of the specified types are
652 returned in the buffer. Possible values are defined in the request
653 parameters section.
654
655 pszDomain points to a null-terminated string that contains the
656 name of the workgroup in which to enumerate computers of the
657 specified type or types. If the pszDomain parameter is a null
658 string or a null pointer, servers are enumerated for the current
659 domain of the computer.
660
661Transaction Request Parameters section
662
663The Transaction request parameters section in this instance contains:
664
665@ The 16 bit function number for NetServerEnum2 which is 104.
666@ The parameter descriptor string which is "WrLehDz".
667@ The data descriptor string for the (returned) data which is "B16" for
668 level detail 0 or "B16BBDz" for level detail 1.
669@ The actual parameters as described by the parameter descriptor
670 string.
671
672The parameters are:
673@ A 16 bit integer with a value of 0 or 1 (corresponding to the "W" in
674 the parameter descriptor string. This represents the level of detail
675 the server is expected to return
676@ A 16 bit integer that contains the size of the receive buffer.
677@ A 32 bit integer that represents the type of servers the function
678 should enumerate. The possible values may be any of the following or
679 a combination of the following:
680
681
682SV_TYPE_WORKSTATION 0x00000001 All workstations
683SV_TYPE_SERVER 0x00000002 All servers
684SV_TYPE_SQLSERVER 0x00000004 Any server running with SQL
685 server
686SV_TYPE_DOMAIN_CTRL 0x00000008 Primary domain controller
687SV_TYPE_DOMAIN_BAKCTRL 0x00000010 Backup domain controller
688SV_TYPE_TIME_SOURCE 0x00000020 Server running the timesource
689 service
690SV_TYPE_AFP 0x00000040 Apple File Protocol servers
691SV_TYPE_NOVELL 0x00000080 Novell servers
692SV_TYPE_DOMAIN_MEMBER 0x00000100 Domain Member
693SV_TYPE_PRINTQ_SERVER 0x00000200 Server sharing print queue
694SV_TYPE_DIALIN_SERVER 0x00000400 Server running dialin service.
695SV_TYPE_XENIX_SERVER 0x00000800 Xenix server
696SV_TYPE_NT 0x00001000 NT server
697SV_TYPE_WFW 0x00002000 Server running Windows for
698
699
700
701Leach, Naik [Page 11]
702
703
704INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
705
706
707 Workgroups
708SV_TYPE_SERVER_NT 0x00008000 Windows NT non DC server
709SV_TYPE_POTENTIAL_BROWSER 0x00010000 Server that can run the browser
710 service
711SV_TYPE_BACKUP_BROWSER 0x00020000 Backup browser server
712SV_TYPE_MASTER_BROWSER 0x00040000 Master browser server
713SV_TYPE_DOMAIN_MASTER 0x00080000 Domain Master Browser server
714SV_TYPE_LOCAL_LIST_ONLY 0x40000000 Enumerate only entries marked
715 "local"
716SV_TYPE_DOMAIN_ENUM 0x80000000 Enumerate Domains. The pszServer
717 and pszDomain parameters must be
718 NULL.
719
720@ A null terminated ASCII string representing the pszDomain parameter
721 described above
722
723Transaction Request Data section
724
725There is no data or auxiliary data to send as part of the request.
726
727Transaction Response Parameters section
728
729The transaction response parameters section consists of:
730@ A 16 bit word indicating the return status. The possible values are:
731
732Code Value Description
733NERR_Success 0 No errors encountered
734ERROR_MORE_DATA 234 Additional data is available
735NERR_ServerNotStarted 2114 The RAP service on the remote
736 computer is not running
737NERR_BadTransactConfig 2141 The server is not configured for
738 transactions, IPC$ is not shared
739
740@ A 16 bit "converter" word.
741@ A 16 bit number representing the number of entries returned.
742@ A 16 bit number representing the total number of available entries.
743 If the supplied buffer is large enough, this will equal the number of
744 entries returned.
745
746Transaction Response Data section
747
748The return data section consists of a number of SHARE_INFO_1 structures.
749The number of such structures present is determined by the third entry
750(described above) in the return parameters section.
751
752At level detail 0, the Transaction response data section contains a
753number of SERVER_INFO_0 data structure. The number of such structures is
754equal to the 16 bit number returned by the server in the third parameter
755in the Transaction response parameter section. The SERVER_INFO_0 data
756structure is defined as:
757
758
759 struct SERVER_INFO_0 {
760 char sv0_name[16];
761 };
762
763
764Leach, Naik [Page 12]
765
766
767INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
768
769
770
771 where:
772
773 sv0_name is a null-terminated string that specifies the name of a
774 computer or domain .
775
776At level detail 1, the Transaction response data section contains a
777number of SERVER_INFO_1 data structure. The number of such structures is
778equal to the 16 bit number returned by the server in the third parameter
779in the Transaction response parameter section. The SERVER_INFO_1 data
780structure is defined as:
781
782
783 struct SERVER_INFO_1 {
784 char sv1_name[16];
785 char sv1_version_major;
786 char sv1_version_minor;
787 unsigned long sv1_type;
788 char *sv1_comment_or_master_browser;
789 };
790
791 sv1_name contains a null-terminated string that specifies the name
792 of a computer.
793
794 sv1_version_major specifies the major release version number of
795 the networking software the server is running. This is entirely
796 informational and something the caller of the NetServerEnum2
797 function gets to see.
798
799 sv1_version_minor specifies the minor release version number of
800 the networking software the server is running. This is entirely
801 informational and something the caller of the NetServerEnum2
802 function gets to see.
803
804 sv1_type specifies the type of software the computer is running.
805 The member can be one or a combination of the values defined above
806 in the Transaction request parameters section for fServerType.
807
808 sv1_comment_or_master_browser points to a null-terminated string. If
809 the sv1_type indicates that the entry is for a domain, this
810 specifies the name of the domain master browser; otherwise, it
811 specifies a comment describing the server. The comment can be a null
812 string or the pointer may be a null pointer.
813
814 In case there are multiple SERVER_INFO_1 data structures to
815 return, the server may put all these fixed length structures in
816 the return buffer, leave some space and then put all the variable
817 length data (the actual value of the sv1_comment strings) at the
818 end of the buffer.
819
820There is no auxiliary data to receive.
821
8227. NetServerGetInfo
823
824
825
826
827
828Leach, Naik [Page 13]
829
830
831INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
832
833
834The NetServerGetInfo function returns information about the specified
835server. The definition is:
836
837 unsigned short NetServerGetInfo(
838 unsigned short sLevel;
839 RCVBUF pbBuffer;
840
841 RCVBUFLEN cbBuffer;
842 unsigned short *pcbTotalAvail;
843 );
844
845 where:
846
847 sLevel specifies the level of detail returned. (Legal values are
848 0 and 1)
849
850 pbBuffer points to the buffer to receive the returned data.
851
852 cbBuffer specifies the size, in bytes, of the buffer pointed to by
853 the pbBuffer parameter.
854
855 pcbTotalAvail points to a 16 bit variable that receives a count of
856 the total number of bytes of information available. This count is
857 valid only if NetServerGetInfo returns the
858 NERR_Success or ERROR_MORE_DATA values.
859
860 The return value is one of the following:
861
862Transaction Request Parameters section
863
864The Transaction request parameters section in this instance contains:
865
866@ The 16 bit function number for NetServerGetInfo which is 13.
867@ The parameter descriptor string which is "WrLh"
868@ The data descriptor string for the (returned) data which is "B16" for
869 level detail 0 or "B16BBDz" for level detail 1.
870@ The actual parameters as described by the parameter descriptor
871 string.
872
873The parameters are:
874@ A 16 bit integer with a value of 0 or 1 (corresponding to the "W" in
875 the parameter descriptor string. This represents the level of detail
876 the server is expected to return
877@ A 16 bit integer that contains the size of the receive buffer.
878
879Transaction Request Data section
880
881There is no data or auxiliary data to send as part of the request.
882
883Transaction Response Parameters section
884
885The transaction response parameters section consists of:
886@ A 16 bit word indicating the return status. The possible values are:
887Code Value Description
888NERR_Success 0 No errors encountered
889
890
891
892Leach, Naik [Page 14]
893
894
895INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
896
897
898ERROR_MORE_DATA 234 Additional data is available
899NERR_ServerNotStarted 2114 The RAP service on the remote
900 computer is not running
901NERR_BadTransactConfig 2141 The server is not configured for
902 transactions, IPC$ is not shared
903
904@ A 16 bit "converter" word.
905@ A 16 bit number representing the total number of available bytes.
906 This has meaning only if the return status is NERR_Success or
907 ERROR_MORE_DATA. In case of success, this will indicate the number of
908 useful bytes available. In case of failure, this indicates the
909 required size of the receive buffer.
910
911Transaction Response Data section
912
913At level detail 0, the Transaction response data section contains a
914SERVER_INFO_0 data structure. The SERVER_INFO_0 data structure is
915defined in section 7.4
916
917At level detail 1, the Transaction response data section contains a
918SERVER_INFO_1 data structure. The SERVER_INFO_1 data structure is
919defined in section 7.4
920
921There is no auxiliary data to receive.
922
9238. NetShareGetInfo
924
925 The NetShareGetInfo function retrieves information about a particular
926 shared resource on a CIFS server. The definition is:
927
928 unsigned short NetShareGetInfo(
929 char *pszNetName;
930 unsigned short sLevel;
931 RCVBUF pbBuffer;
932 RCVBUFLEN cbBuffer;
933 unsigned short *pcbTotalAvail;
934 );
935
936 where:
937
938 pszNetName points to an ASCII null-terminated string specifying
939 the name of the shared resource for which information should be
940 retrieved.
941
942 sLevel specifies the level of detail returned. (Legal values are
943 0, 1 and 2)
944
945 pbBuffer points to the buffer to receive the returned data.
946
947 cbBuffer specifies the size, in bytes, of the buffer pointed to by
948 the pbBuffer parameter.
949
950 pcbTotalAvail points to a 16 bit variable that receives a count of
951 the total number of bytes of information available. This count is
952
953
954
955
956Leach, Naik [Page 15]
957
958
959INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
960
961
962 valid only if NetShareGetInfo returns the NERR_Success or
963 ERROR_MORE_DATA values.
964
965Transaction Request Parameters section
966
967The Transaction request parameters section in this instance contains:
968
969@ The 16 bit function number for NetServerGetInfo which is 1.
970@ The parameter descriptor string which is "zWrLh"
971@ The data descriptor string for the (returned) data which is "B13" for
972 level detail 0 or "B13BWz" for level detail 1 or "B13BWzWWWzB9B"
973 for level detail 2.
974@ The actual parameters as described by the parameter descriptor
975 string.
976
977The parameters are:
978@ A null terminated ASCII string indicating the share for which
979 information should be retrieved.
980@ A 16 bit integer with a value of 0, 1 or 2 (corresponding to the "W"
981 in the parameter descriptor string. This represents the level of
982 detail the server is expected to return
983@ A 16 bit integer that contains the size of the receive buffer.
984
985Transaction Request Data section
986
987There is no data or auxiliary data to send as part of the request.
988
989Transaction Response Parameters section
990
991The transaction response parameters section consists of:
992@ A 16 bit word indicating the return status. The possible values are:
993Code Value Description
994NERR_Success 0 No errors encountered
995ERROR_MORE_DATA 234 Additional data is available
996NERR_ServerNotStarted 2114 The RAP service on the remote
997 computer is not running
998NERR_BadTransactConfig 2141 The server is not configured for
999 transactions, IPC$ is not shared
1000
1001@ A 16 bit "converter" word.
1002@ A 16 bit number representing the total number of available bytes.
1003 This has meaning only if the return status is NERR_Success or
1004 ERROR_MORE_DATA. Upon success, this number indicates the number of
1005 useful bytes available. Upon failure, this indicates how big the
1006 receive buffer needs to be.
1007
1008Transaction Response Data section
1009
1010At level detail 0, the Transaction response data section contains a
1011SHARE_INFO_0 data structure, which is defined as:
1012
1013
1014 struct SHARE_INFO_0 {
1015 char shi1_netname[13]
1016 }
1017
1018
1019
1020Leach, Naik [Page 16]
1021
1022
1023INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1024
1025
1026
1027
1028where:
1029
1030 shi0_netname contains an ASCIIZ string that specifies the share
1031 name of the resource.
1032
1033At level detail 1, the Transaction response data section contains a
1034SHARE_INFO_1 data structure, which is defined as:
1035
1036
1037 struct SHARE_INFO_1 {
1038 char shi1_netname[13]
1039 char shi1_pad;
1040 unsigned short shi1_type
1041 char *shi1_remark;
1042 }
1043
1044
1045where
1046
1047 shi1_netname contains an ASCIIZ string that specifies the share
1048 name of the resource.
1049
1050 shi1_pad aligns the next data structure element to a word
1051 boundary.
1052
1053 shi1_type contains an integer that specifies the type of the
1054 shared resource. The possible values are:
1055
1056Name Value Description
1057STYPE_DISKTREE 0 Disk Directory Tree
1058STYPE_PRINTQ 1 Printer Queue
1059STYPE_DEVICE 2 Communications device
1060STYPE_IPC 3 Inter process communication (IPC)
1061
1062
1063 shi1_remark points to a null-terminated string that specifies a
1064 comment describing the share. The comment can be a null string or
1065 the pointer may be a null pointer.
1066 The shi1_remark pointer is a 32 bit pointer. The higher 16 bits
1067 must be ignored. The converter word returned in the parameters
1068 section needs to be subtracted from the lower 16 bits to calculate
1069 an offset into the return buffer where this ASCII string resides.
1070
1071At level detail 2, the Transaction response data section contains a
1072SHARE_INFO_2 data structure, which is defined as:
1073
1074
1075 struct SHARE_INFO_2 {
1076 char shi2_netname[13]
1077 char shi2_pad;
1078 unsigned short shi2_type
1079 char * shi2_remark;
1080 unsigned short shi2_permissions;
1081 unsigned short shi2_max_uses;
1082 unsigned short shi2_current_uses;
1083 unsigned short shi2_path;
1084 unsigned short shi2_passwd[9]
1085
1086
1087
1088Leach, Naik [Page 17]
1089
1090
1091INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1092
1093
1094
1095 unsigned short shi2_pad2;
1096 }
1097
1098where
1099
1100 shi2_netname contains a null terminated ASCII string that
1101 specifies the share name of the resource.
1102
1103 shi2_pad aligns the next data strructure element to a word
1104 boundary.
1105
1106 shi2_type contains an integer that specifies the type of the
1107 shared resource. The possible values are:
1108
1109
1110Name Value Description
1111STYPE_DISKTREE 0 Disk Directory Tree
1112STYPE_PRINTQ 1 Printer Queue
1113STYPE_DEVICE 2 Communications device
1114STYPE_IPC 3 Inter process
1115 communication (IPC)
1116
1117
1118 shi2_remark is a pointer to a null terminated ASCII string
1119 specifying a comment for the share
1120
1121 shi2_permissions specifies the permissions on the shared resource
1122 if the CIFS server is operating with share level security. The
1123 values are this element can take are defined as a series of bit
1124 masks that may be OR’ed with each other. The bit mask values are:
1125
1126
1127Name Bit Mask Value Description
1128ACCESS_READ 0x01 Permission to read & execute from resource
1129ACCESS_WRITE 0x02 Permission to write data to resource
1130ACCESS_CREATE 0x04 Permission to create an instance of the
1131 resource
1132ACCESS_EXEC 0x08 Permission to execute from resource
1133ACCESS_DELETE 0x10 Permission to delete the resource
1134ACCESS_ATRIB 0x20 Permission to modify the resource
1135 attributes such as date & time of last
1136 modification, etc
1137ACCESS_PERM 0x40 Permission to change permissions on the
1138 resource
1139ACCESS_ALL 0x7F All of the above permissions
1140
1141 shi2_max_uses specifies the maximum number of current uses the
1142 shared resource can accommodate. A Value of -1 indicates there is
1143 no limit.
1144
1145 shi2_current_uses specifies the current number of connections to
1146 the resource
1147
1148 shi2_path point to an ASCIIZ string that contains the local (on
1149 the remote CIFS server) path name of the shared resource.
1150
1151
1152
1153
1154Leach, Naik [Page 18]
1155
1156
1157INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1158
1159
1160 @ For printer resources, shi2_path specifies the name of the
1161 printer queue being shared
1162 @ For disk devices, shi2_path specifies the path being shared
1163 @ For communication device queues, shi2_path specifies the name of
1164 the of the communication device
1165 @ For ADMIN$ or IPC$ resources, shi2_path must be a null pointer
1166
1167 shi2_passwd specifies the password for the resource in case the
1168 CIFS server is running with share level security. For CIFS servers
1169 running with user level security, this field is set to null and is
1170 ignored.
1171
1172 shi2_pad2 is just a pad byte
1173
1174 All of the pointers to an ASCII string in this data structure
1175 (shi2_remark and shi2_path) need to be treated specially. The
1176 pointer is a 32 bit pointer. The higher 16 bits need to be
1177 ignored. The converter word returned in the parameters section
1178 needs to be subtracted from the lower 16 bits to calculate an
1179 offset into the return buffer where this ASCII string resides.
1180
1181
1182There is no auxiliary data in the response.
1183
11849. NetwkstaUserLogon
1185
1186This is a function executed on a remote CIFS server to log on a user.
1187The purpose is to perform checks such as whether the specified user is
1188permitted to logon from the specified computer, whether the specified
1189user is permitted to log on at the given moment, etc. as well as perform
1190housekeeping and statistics updates.
1191
1192There is a password field in the parameters for this function. However,
1193this field is always set to null before the function is sent on the
1194wire, in order to preserve security. The remote CIFS server ignores this
1195meaningless password that is sent. The remote CIFS server ensures
1196security by checking that the user name and computer name that are in
1197the request parameters are the same used to establish the session and
1198connection to the IPC$ share on the remote CIFS server.
1199
1200The definition is:
1201
1202 unsigned short NetWkstaUserLogon(
1203 char *reserved1;
1204 char *reserved2;
1205 unsigned short sLevel;
1206 BYTE bReqBuffer[54];
1207 unsigned short cbReqBuffer;
1208 RCVBUF pbBuffer;
1209 RCVBUFLEN cbBuffer;
1210 unsigned short *pcbTotalAvail;
1211 );
1212
1213 where:
1214
1215
1216
1217
1218Leach, Naik [Page 19]
1219
1220
1221INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1222
1223
1224 reserved1 and reserved2 are reserved fields and must be null.
1225
1226 sLevel specifies the level of detail returned. The only legal
1227 value is 1.
1228
1229 pbReqBuffer points to the request buffer. This buffer contains
1230 parameters that need to be sent to the server. The actual value
1231 and structure is defined in the Transaction Request Parameters
1232 section.
1233
1234 cbReqBuffer specifies the size, in bytes, of the buffer pointed to
1235 by the pbReqBuffer parameter. The value must be decimal 54.
1236
1237 pbBuffer points to the buffer to receive the returned data.
1238
1239 cbBuffer specifies the size, in bytes, of the buffer pointed to by
1240 the pbBuffer parameter.
1241
1242 pcbTotalAvail is a pointer to an unsigned short which gets filled
1243 with the total number of data bytes available if the function
1244 succeeds.
1245
1246Transaction Request Parameters section
1247
1248The Transaction request parameters section in this instance contains:
1249
1250@ The 16 bit function number for NetWkstaUserLogon which is 132.
1251@ The parameter descriptor string which is "OOWb54WrLh"
1252@ The data descriptor string for the (returned) data which is
1253 "WB21BWDWWDDDDDDDzzzD"
1254@ The actual parameters as described by the parameter descriptor
1255 string.
1256
1257The parameters are:
1258@ A 16 bit integer with a value of 1 (corresponding to the "W" in the
1259 parameter descriptor string. This represents the level of detail the
1260 server is expected to return)
1261@ a byte array of length 54 bytes. These 54 bytes are defined as
1262
1263 char wlreq1_name[21]; // User Name
1264 char wlreq1_pad1; //Pad next field to a word boundary
1265 char wlreq1_password[15]; //Password, set to null, ignored by
1266 server
1267 char wlreq1_pad2; //Pad next field to word boundary
1268 char wlreq1_workstation[16]; //ASCII name of computer
1269@ A 16 bit integer with a value of 54
1270@ A 16 bit integer that contains the size of the receive buffer
1271
1272
1273Transaction Request Data section
1274
1275There is no data or auxiliary data to send as part of the request.
1276
1277Transaction Response Parameters section
1278
1279
1280
1281
1282Leach, Naik [Page 20]
1283
1284
1285INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1286
1287
1288The transaction response parameters section consists of:
1289@ A 16 bit word indicating the return status. The possible values are:
1290
1291Code Valu Description
1292 e
1293NERR_Success 0 No errors encountered
1294ERROR_ACCESS_DENIED 5 User has insufficient privilege
1295NERR_LogonScriptError 2212 An error occurred while loading or
1296 running the logon script
1297NERR_StandaloneLogon 2214 The logon was not validated by any
1298 server
1299NERR_NonValidatedLogon 2217 The logon server is running an
1300 older software version and cannot
1301 validate the logon
1302NERR_InvalidWorkstation 2240 The user is not allowed to logon
1303 from this computer
1304NERR_InvalidLogonHours 2241 The user is not allowed to logon at
1305 this time
1306NERR_PasswordExpired 2242 The user password has expired
1307
1308@ A 16 bit "converter" word.
1309@ A 16 bit number representing the total number of available bytes.
1310 This has meaning only if the return status is NERR_Success or
1311 ERROR_MORE_DATA. Upon success, this number indicates the number of
1312 useful bytes available. Upon failure, this indicates how big the
1313 receive buffer needs to be.
1314
1315Transaction Response Data section
1316
1317The Transaction response data section contains a data structure
1318user_logon_info_1 which is defined as:
1319
1320
1321 struct user_logon_info_1 {
1322 unsigned short usrlog1_code;
1323 char usrlog1_eff_name[21];
1324 char usrlog1_pad_1;
1325 unsigned short usrlog1_priv;
1326 unsigned long usrlog1_auth_flags;
1327 unsigned short usrlog1_num_logons;
1328 unsigned short usrlog1_bad_pw_count;
1329 unsigned long usrlog1_last_logon;
1330 unsigned long usrlog1_last_logoff;
1331 unsigned long usrlog1_logoff_time;
1332 unsigned long usrlog1_kickoff_time;
1333 long usrlog1_password_age;
1334 unsigned long usrlog1_pw_can_change;
1335 unsigned long usrlog1_pw_must_change;
1336 char *usrlog1_computer;
1337 char *usrlog1_domain;
1338 char *usrlog1_script_path;
1339 unsigned long usrlog1_reserved1;
1340 };
1341
1342where:
1343
1344
1345Leach, Naik [Page 21]
1346
1347
1348INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1349
1350
1351
1352 usrlog1_code specifies the result and can have the following values:
1353
1354Code Valu Description
1355 e
1356NERR_Success 0 No errors encountered
1357ERROR_ACCESS_DENIED 5 User has insufficient privilege
1358NERR_LogonScriptError 2212 An error occurred while loading or
1359 running the logon script
1360NERR_StandaloneLogon 2214 The logon was not validated by any
1361 server
1362NERR_NonValidatedLogon 2217 The logon server is running an
1363 older software version and cannot
1364 validate the logon
1365NERR_InvalidWorkstation 2240 The user is not allowed to logon
1366 from this computer
1367NERR_InvalidLogonHours 2241 The user is not allowed to logon at
1368 this time
1369NERR_PasswordExpired 2242 Administrator privilege
1370
1371
1372 usrlog1_eff_name specifies the account to which the user was logged on
1373
1374 usrlog1_pad1 aligns the next data structure element to a word boundary
1375
1376 usrlog1_priv specifies the user’s privilege level. The possible values
1377 are:
1378
1379Name Value Description
1380USER_PRIV_GUEST 0 Guest privilege
1381USER_PRIV_USER 1 User privilege
1382USER_PRV_ADMIN 2 Administrator privilege
1383
1384 usrlog1_auth_flags specifies the account operator privileges. The
1385 possible values are:
1386
1387Name Value Description
1388AF_OP_PRINT 0 Print operator
1389AF_OP_COMM 1 Communications operator
1390AF_OP_SERVER 2 Server operator
1391AF_OP_ACCOUNTS 3 Accounts operator
1392
1393 usrlog1_num_logons specifies the number of times this user has logged
1394 on. A value of -1 means the number of logons is unknown.
1395
1396 usrlog1_bad_pw_count specifies the number of incorrect passwords
1397 entered since the last successful logon.
1398
1399 usrlog1_last_logon specifies the time when the user last logged on.
1400 This value is stored as the number of seconds elapsed since
1401 00:00:00, January 1, 1970.
1402
1403 usrlog1_last_logoff specifies the time when the user last logged off.
1404 This value is stored as the number of seconds elapsed since
1405
1406
1407Leach, Naik [Page 22]
1408
1409
1410INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1411
1412
1413 00:00:00, January 1, 1970. A value of 0 means the last logoff
1414 time is unknown.
1415
1416 usrlog1_logoff_time specifies the time when the user should logoff.
1417 This value is stored as the number of seconds elapsed since
1418 00:00:00, Jan 1, 1970. A value of -1 means the user never has to
1419 logoff.
1420
1421 usrlog1_kickoff_time specifies the time when the user will be logged
1422 off by the system. This value is stored as the number of seconds
1423 elapsed since 00:00:00, Jan 1, 1970. A value of -1 means the
1424 system will never logoff the user.
1425
1426 usrlog1_password_age specifies the time in seconds since the user
1427 last changed his/her password.
1428
1429 usrlog1_password_can_change specifies the time when the user can
1430 change the password. This value is stored as the number of
1431 seconds elapsed since 00:00:00, Jan 1, 1970. A value of -1 means
1432 the user can never change the password.
1433
1434 usrlog1_password_must_change specifies the time when the user must
1435 change the password. This value is stored as the number of
1436 seconds elapsed since 00:00:00, Jan 1, 1970.
1437
1438 usrlog1_computer specifies the computer where the user is logged on.
1439
1440 usrlog1_script_path specifies the relative path to the user logon
1441 script.
1442
1443 usrlog1_reserved is reserved with an undefined value.
1444
1445The following table defines the valid fields in the user_logon_info_1
1446structure based upon the return values::
1447
1448function return code usrlog1_code element Valid elements of
1449 logoff_info_1
1450NERR_Success NERR_Success All
1451NERR_Success NERR_StandaloneLogon None except usrlog1_code
1452ERROR_ACCESS_DENIED NERR_PasswordExpired None except usrlog1_code
1453ERROR_ACCESS_DENIED NERR_InvalidWorkstation None except usrlog1_code
1454ERROR_ACCESS_DENIED NERR_InvalidLogonhours None except usrlog1_code
1455ERROR_ACCESS_DENIED NERR_LogonScriptError None except usrlog1_code
1456ERROR_ACCESS_DENIED ERROR_ACCESS_DENIED None except usrlog1_code
1457All other errors None; the code is None
1458 meaningless
1459
1460All of the pointers in this data structure need to be treated
1461specially. The pointer is a 32 bit pointer. The higher 16 bits need
1462to be ignored. The converter word returned in the parameters section
1463needs to be subtracted from the lower 16 bits to calculate an offset
1464into the return buffer where this ASCII string resides.
1465
1466There is no auxiliary data in the response.
1467
1468
1469Leach, Naik [Page 23]
1470
1471
1472INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1473
1474
147510. NetwkstaUserLogoff
1476
1477This is a function executed on a remote CIFS server to log on a user.
1478The purpose is to perform some checks and accomplish housekeeping and
1479statistics updates.
1480
1481The definition is:
1482
1483 unsigned short NetWkstaUserLogoff(
1484 char *reserved1;
1485 char *reserved2;
1486 unsigned short sLevel;
1487 BYTE bReqBuffer[54];
1488 unsigned short cbReqBuffer;
1489 REQBUF pbBuffer;
1490 REQBUFLEN cbBuffer;
1491 unsigned short *pcbTotalAvail;
1492 );
1493
1494 where:
1495
1496 reserved1 and reserved2 are reserved fields and must be null.
1497
1498 sLevel specifies the level of detail returned. The only legal
1499 value is 1.
1500
1501 pbReqBuffer points to the request buffer. This buffer contains
1502 parameters that need to be sent to the server. The actual value
1503 and structure is defined in the Transaction Request Parameters
1504 section.
1505
1506 cbReqBuffer specifies the size, in bytes, of the buffer pointed to
1507 by the pbReqBuffer parameter. The value must be decimal 54.
1508
1509 pbBuffer points to the buffer to receive the returned data.
1510
1511 cbBuffer specifies the size, in bytes, of the buffer pointed to by
1512 the pbBuffer parameter.
1513
1514 pcbTotalAvail is a pointer to an unsigned short which gets filled
1515 with the total number of data bytes available if the function
1516 succeeds.
1517
1518Transaction Request Parameters section
1519
1520The Transaction request parameters section in this instance contains:
1521
1522@ The 16 bit function number for NetWkstaUserLogoff which is 133.
1523@ The parameter descriptor string which is "zzWb38WrLh"
1524@ The data descriptor string for the (returned) data which is "WDW"
1525@ The actual parameters as described by the parameter descriptor
1526 string.
1527
1528The parameters are:
1529@ A null pointer
1530
1531
1532
1533Leach, Naik [Page 24]
1534
1535
1536INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1537
1538
1539@ Another null pointer
1540@ A 16 bit integer with a value of 1 (corresponding to the "W" in the
1541 parameter descriptor string. This represents the level of detail the
1542 server is expected to return)
1543@ An array of length 38 bytes. These 38 bytes are defined as
1544
1545 char wlreq1_name[21]; // User Name
1546 char wlreq1_pad1; //Pad next field to a word
1547 boundary
1548 char wlreq1_workstation[16]; //ASCII name of computer
1549@ A 16 bit integer with a value of decimal 38.
1550@ A 16 bit integer that contains the size of the receive buffer
1551
1552Transaction Request Data section
1553
1554There is no data or auxiliary data to send as part of the request.
1555
1556Transaction Response Parameters section
1557
1558The transaction response parameters section consists of:
1559@ A 16 bit word indicating the return status. The possible values are:
1560
1561Code Value Description
1562NERR_Success 0 No errors encountered
1563NERR_StandaloneLogon 2214 The logon was not validated by any
1564 server
1565NERR_NonValidatedLogon 2217 The logon server is running an older
1566 software version and cannot validate the
1567 logoff
1568
1569@ A 16 bit "converter" word.
1570@ A 16 bit number representing the total number of available bytes.
1571 This has meaning only if the return status is NERR_Success or
1572 ERROR_MORE_DATA. Upon success, this number indicates the number of
1573 useful bytes available. Upon failure, this indicates how big the
1574 receive buffer needs to be.
1575
1576Transaction Response Data section
1577
1578The Transaction response data section contains a data structure
1579user_logoff_info_1 which is defined as:
1580
1581
1582 struct user_logoff_info_1 {
1583 unsigned short usrlogf1_code;
1584 unsigned long usrlogf1_duration;
1585 unsigned short usrlogf1_num_logons;
1586 };
1587
1588where:
1589
1590 usrlogf1_code specifies the result and can have the following values:
1591
1592Code Value Description
1593NERR_Success 0 No errors encountered
1594ERROR_ACCESS_DENIED 5 User has insufficient privilege
1595
1596
1597Leach, Naik [Page 25]
1598
1599
1600INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1601
1602
1603NERR_InvalidWorkstation 2240 The user is not allowed to logon from
1604 this computer
1605
1606 usrlogf1_duration specifies the time in number of seconds for which
1607 the user was logged
1608
1609 usrlogf1_num_logons specifies the number of times this user has logged
1610 on. A value of -1 indicates the number is unknown.
1611
1612The following table defines the valid fields in the logoff_info_1
1613structure based upon the return values::
1614
1615function usrlogf11_code Valid elements of logoff_info_1
1616return code element
1617NERR_Success NERR_Success All
1618NERR_Success NERR_StandaloneLogon None except usrlogf1_code
1619All other None; the code is None
1620errors meaningless
1621
1622There is no auxiliary data in the response.
1623
1624
162511. NetUserGetInfo
1626
1627This is a function executed on a remote CIFS server to obtain detailed
1628information about a particular user.
1629
1630The definition is:
1631
1632 unsigned short NetUserGetInfo(
1633 char *pszUser;
1634 unsigned short sLevel;
1635 RCVBUF pBuffer;
1636 RCVBUFLEN cbBuffer;
1637 unsigned short *pcbTotalAvail;
1638 );
1639
1640 where:
1641
1642 pszUser points to a null terminated ASCII string signifying the
1643 name of the user for which information should be retrieved.
1644
1645 sLevel specifies the level of detail returned. The only legal
1646 value is 11.
1647
1648 pbBuffer points to the buffer to receive the returned data.
1649
1650 cbBuffer specifies the size, in bytes, of the buffer pointed to by
1651 the pbBuffer parameter.
1652
1653 pcbTotalAvail is a pointer to an unsigned short which gets filled
1654 with the total number of data bytes available if the function
1655 succeeds.
1656
1657Transaction Request Parameters section
1658
1659
1660Leach, Naik [Page 26]
1661
1662
1663INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1664
1665
1666The Transaction request parameters section in this instance contains:
1667
1668@ The 16 bit function number for NetUserGetInfo which is 56.
1669@ The parameter descriptor string which is "zWrLh"
1670@ The data descriptor string for the (returned) data which is
1671 "B21BzzzWDDzzDDWWzWzDWb21W"
1672@ The actual parameters as described by the parameter descriptor
1673 string.
1674
1675The parameters are:
1676@ A null terminated ASCII string indicating the user for which
1677 information should be retrieved.
1678@ A 16 bit integer with a value of decimal 11 (corresponding to the "W"
1679 in the parameter descriptor string. This represents the level of
1680 detail the server is expected to return)
1681@ A 16 bit integer that contains the size of the receive buffer
1682
1683
1684Transaction Request Data section
1685
1686There is no data or auxiliary data to send as part of the request.
1687
1688Transaction Response Parameters section
1689
1690The transaction response parameters section consists of:
1691@ A 16 bit word indicating the return status. The possible values are:
1692
1693Code Valu Description
1694 e
1695NERR_Success 0 No errors encountered
1696ERROR_ACCESS_DENIED 5 User has insufficient privilege
1697ERROR_MORE_DATA 234 additional data is available
1698NERR_BufTooSmall 2123 The supplied buffer is too small
1699NERR_UserNotFound 2221 The user name was not found
1700@ A 16 bit "converter" word.
1701@ A 16 bit number representing the total number of available bytes.
1702 This has meaning only if the return status is NERR_Success or
1703 ERROR_MORE_DATA. Upon success, this number indicates the number of
1704 useful bytes available. Upon failure, this indicates how big the
1705 receive buffer needs to be.
1706
1707Transaction Response Data section
1708
1709The Transaction response data section contains a data structure
1710user_logon_info_1 which is defined as:
1711
1712
1713 struct user_info_11 {
1714 char usri11_name[21];
1715 char usri11_pad;
1716 char *usri11_comment;
1717 char *usri11_usr_comment;
1718 char *usri11_full_name;
1719 unsigned short usri11_priv;
1720 unsigned long usri11_auth_flags;
1721
1722
1723
1724Leach, Naik [Page 27]
1725
1726
1727INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1728
1729
1730
1731 long usri11_password_age;
1732 char *usri11_homedir;
1733 char *usri11_parms;
1734 long usri11_last_logon;
1735 long usri11_last_logoff;
1736 unsigned short usri11_bad_pw_count;
1737 unsigned short usri11_num_logons;
1738 char *usri11_logon_server;
1739 unsigned short usri11_country_code;
1740 char *usri11_workstations;
1741 unsigned long usri11_max_storage;
1742 unsigned short usri11_units_per_week;
1743 unsigned char *usri11_logon_hours;
1744 unsigned short usri11_code_page;
1745 };
1746
1747where:
1748
1749 usri11_name specifies the user name for which information is retireved
1750
1751 usri11_pad aligns the next data structure element to a word boundary
1752
1753 usri11_comment is a null terminated ASCII comment
1754
1755 usri11_user_comment is a null terminated ASCII comment about the user
1756
1757 usri11_full_name is a null terminated ASCII specifying the full name
1758 of the user
1759
1760 usri11_priv specifies the level of the privilege assigned to the user.
1761 The possible values are:
1762
1763Name Value Description
1764USER_PRIV_GUEST 0 Guest privilege
1765USER_PRIV_USER 1 User privilege
1766USER_PRV_ADMIN 2 Administrator privilege
1767
1768 usri11_auth_flags specifies the account operator privileges. The
1769 possible values are:
1770
1771Name Value Description
1772AF_OP_PRINT 0 Print operator
1773AF_OP_COMM 1 Communications operator
1774AF_OP_SERVER 2 Server operator
1775AF_OP_ACCOUNTS 3 Accounts operator
1776
1777
1778 usri11_password_age specifies how many seconds have elapsed since the
1779 password was last changed.
1780
1781 usri11_home_dir points to a null terminated ASCII string that contains
1782 the path name of the user's home directory.
1783
1784
1785
1786
1787Leach, Naik [Page 28]
1788
1789
1790INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1791
1792
1793 usri11_parms points to a null terminated ASCII string that is set
1794 aside for use by applications.
1795
1796 usri11_last_logon specifies the time when the user last logged on.
1797 This value is stored as the number of seconds elapsed since
1798 00:00:00, January 1, 1970.
1799
1800 usri11_last_logoff specifies the time when the user last logged off.
1801 This value is stored as the number of seconds elapsed since
1802 00:00:00, January 1, 1970. A value of 0 means the last logoff
1803 time is unknown.
1804
1805 usri11_bad_pw_count specifies the number of incorrect passwords
1806 entered since the last successful logon.
1807
1808 usri11_log1_num_logons specifies the number of times this user has
1809 logged on. A value of -1 means the number of logons is unknown.
1810
1811 usri11_logon_server points to a null terminated ASCII string that
1812 contains the name of the server to which logon requests are sent.
1813 A null string indicates logon requests should be sent to the
1814 domain controller.
1815
1816 usri11_country_code specifies the country code for the user's language
1817 of choice.
1818
1819 usri11_workstations points to a null terminated ASCII string that
1820 contains the names of workstations the user may log on from.
1821 There may be up to 8 workstations, with the names separated by
1822 commas. A null strings indicates there are no restrictions.
1823
1824 usri11_max_storage specifies the maximum amount of disk space the user
1825 can occupy. A value of 0xffffffff indicates there are no
1826 restrictions.
1827
1828 usri11_units_per_week specifies the equal number of time units into
1829 which a week is divided. This value must be equal to 168.
1830
1831 usri11_logon_hours points to a 21 byte (168 bits) string that
1832 specifies the time during which the user can log on. Each bit
1833 represents one unique hour in a week. The first bit (bit 0, word
1834 0) is Sunday, 0:00 to 0:59, the second bit (bit 1, word 0) is
1835 Sunday, 1:00 to 1:59 and so on. A null pointer indicates there
1836 are no restrictions.
1837
1838 usri11_code_page specifies the code page for the user's language of
1839 choice
1840
1841All of the pointers in this data structure need to be treated
1842specially. The pointer is a 32 bit pointer. The higher 16 bits need
1843to be ignored. The converter word returned in the parameters section
1844needs to be subtracted from the lower 16 bits to calculate an offset
1845into the return buffer where this ASCII string resides.
1846
1847
1848
1849Leach, Naik [Page 29]
1850
1851
1852INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1853
1854
1855There is no auxiliary data in the response.
1856
185712. NetWkstaGetInfo
1858
1859This is a function executed on a remote CIFS server to obtain detailed
1860information about a workstation.
1861
1862The definition is:
1863
1864 unsigned short NetWkstaGetInfo(
1865 unsigned short sLevel;
1866 RCVBUF pBuffer;
1867 RCVBUFLEN cbBuffer;
1868 unsigned short *pcbTotalAvail;
1869 );
1870
1871 where:
1872
1873 sLevel specifies the level of detail returned. The only legal
1874 value is 10.
1875
1876 pbBuffer points to the buffer to receive the returned data.
1877
1878 cbBuffer specifies the size, in bytes, of the buffer pointed to by
1879 the pbBuffer parameter.
1880
1881 pcbTotalAvail is a pointer to an unsigned short which gets filled
1882 with the total number of data bytes available if the function
1883 succeeds.
1884
1885Transaction Request Parameters section
1886
1887The Transaction request parameters section in this instance contains:
1888
1889@ The 16 bit function number for NetWkstaGetInfo which is 63.
1890@ The parameter descriptor string which is "WrLh"
1891@ The data descriptor string for the (returned) data which is
1892 "zzzBBzz".
1893@ The actual parameters as described by the parameter descriptor
1894 string.
1895
1896The parameters are:
1897@ A 16 bit integer with a value of decimal 10 (corresponding to the "W"
1898 in the parameter descriptor string. This represents the level of
1899 detail the server is expected to return)
1900@ A 16 bit integer that contains the size of the receive buffer
1901
1902
1903Transaction Request Data section
1904
1905There is no data or auxiliary data to send as part of the request.
1906
1907Transaction Response Parameters section
1908
1909The transaction response parameters section consists of:
1910
1911
1912
1913Leach, Naik [Page 30]
1914
1915
1916INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1917
1918
1919@ A 16 bit word indicating the return status. The possible values are:
1920
1921Code Valu Description
1922 e
1923NERR_Success 0 No errors encountered
1924ERROR_ACCESS_DENIED 5 User has insufficient privilege
1925ERROR_MORE_DATA 234 additional data is available
1926NERR_BufTooSmall 2123 The supplied buffer is too small
1927NERR_UserNotFound 2221 The user name was not found
1928@ A 16 bit "converter" word.
1929@ A 16 bit number representing the total number of available bytes.
1930 This has meaning only if the return status is NERR_Success or
1931 ERROR_MORE_DATA. Upon success, this number indicates the number of
1932 useful bytes available. Upon failure, this indicates how big the
1933 receive buffer needs to be.
1934
1935Transaction Response Data section
1936
1937The Transaction response data section contains a data structure
1938user_logon_info_1 which is defined as:
1939
1940
1941 struct user_info_11 {
1942 char *wki10_computername;
1943 char *wki10_username;
1944 char *wki10_langroup;
1945 unsigned char wki10_ver_major;
1946 unsigned char wki10_ver_minor;
1947 char *wki10_logon_domain;
1948 char *wki10_oth_domains;
1949 };
1950
1951where:
1952
1953 wki10_computername is a pointer to a NULL terminated ASCII string that
1954 specifies the name of the workstation.
1955
1956 wki10_username is a pointer to a NULL terminated ASCII string that
1957 specifies the user who is logged on at the workstation.
1958
1959 wki10_langroup is a pointer to a NULL terminated ASCII string that
1960 specifies the domain to which the workstation belongs.
1961
1962 wki10_ver_major specifies the major version number of the networking
1963 software the workstation is running.
1964
1965 wki10_ver_minor specifies the minor version number of the networking
1966 software the workstation is running.
1967
1968 wki10_logon domain is a pointer to a NULL terminated ASCII string that
1969 specifies the domain for which a user is logged on.
1970
1971 wki10_oth domain is a pointer to a NULL terminated ASCII string that
1972 specifies all domains in which the computer is enlisted.
1973
1974
1975
1976Leach, Naik [Page 31]
1977
1978
1979INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
1980
1981
1982All of the pointers in this data structure need to be treated
1983specially. The pointer is a 32 bit pointer. The higher 16 bits need
1984to be ignored. The converter word returned in the parameters section
1985needs to be subtracted from the lower 16 bits to calculate an offset
1986into the return buffer where this ASCII string resides.
1987
1988There is no auxiliary data in the response.
1989
1990
199113. SamOemChangePassword
1992
1993This is a function executed on a remote CIFS server to change a user’s
1994password.
1995
1996The definition is:
1997
1998 unsigned short SamOemChangePassword(
1999 uchar *UserName;
2000 uchar *OldPassword;
2001 uchar *NewPassword;
2002 );
2003
2004 where:
2005
2006 UserName is a pointer to a NULL terminated ASCII string
2007 representing the name of the user for which the password should be
2008 changed.
2009
2010 OldPassword is a pointer to a NULL terminated ASCII string
2011 representing the current password of the user
2012
2013 NewPassword is a pointer to a NULL terminated ASCII string
2014 representing the new password of the
2015
2016Transaction Request Parameters section
2017
2018The Transaction request parameters section in this instance contains:
2019
2020@ The 16 bit function number for SamOEMChangePassword which is 214.
2021@ The parameter descriptor string which is "zsT"
2022@ The actual parameters as described by the parameter descriptor
2023 string.
2024
2025The parameters are:
2026@ A null terminated ASCII string that represents the name of the user
2027 for whom the password is being changed.
2028@ A word with a value of 532 representing the size of the data buffer.
2029
2030
2031Transaction Request Data section
2032
2033The data buffer to be sent consists of 532 bytes of data. The first 516
2034bytes represent the new password in an encrypted form. The last 16 bytes
2035represent the old password in an encrypted form.
2036
2037
2038
2039
2040Leach, Naik [Page 32]
2041
2042
2043INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
2044
2045
2046The new password is represented by the structure
2047
2048
2049 struct {
2050 char NewPasswordBuffer[512];
2051 long LengthofNewPasswordInBytes;
2052 }
2053
2054The new password is stored in plain text form at the end of the buffer
2055and the length of the new password is stored in the second member of the
2056structure. The whole structure is encrypted using RC4. The RC4 key used
2057is the One Way Transformation (described below) of the old password.
2058
2059The RC4 encryption of the One Way Transformation of the old password
2060constitutes the last 16 bytes of the data buffer. The RC4 key used is
2061the One Way Transformation of the new password
2062
2063There is no auxiliary data to send as part of the request.
2064
2065
2066One Way Transformation
2067
2068This section describes the algorithm used by CIFS to apply a one way
2069transformation on data.
2070
2071Let
2072E(K, D)
2073 denote the DES block mode encryption function [5] , which accepts a
2074 seven byte key (K) and an eight byte data block (D) and produces an
2075 eight byte encrypted data block as its value.
2076
2077concat(A, B)
2078 is the result of concatenating A and B
2079
2080Ex(K,D)
2081 denote the extension of DES to longer keys and data blocks. If the
2082 data to be encrypted is longer than eight bytes, the encryption
2083 function is applied to each block of eight bytes in sequence and the
2084 results are concatenated together. If the key is longer than seven
2085 bytes, each 8 byte block of data is first completely encrypted using
2086 the first seven bytes of the key, then the second seven bytes, etc.,
2087 appending the results each time. For example, to encrypt the 16 byte
2088 quantity D0D1 with the 14 byte key K0K1,
2089
2090 Ex(K0K1,D0D1) = concat(E(K0,D0),E(K0,D1),E(K1,D0),E(K1,D1))
2091
2092head(S, B)
2093 denote the first B bytes of the byte string S.
2094
2095swab(S)
2096 denote the byte string obtained by reversing the order of the bits in
2097 each byte of S, i.e., if S is byte string of length one, with the
2098 value 0x37 then swab(S) is 0xEC.
2099
2100
2101
2102
2103Leach, Naik [Page 33]
2104
2105
2106INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
2107
2108
2109
2110
2111The One Way Transformation function is defined as:
2112
2113
2114 OWF = Ex(swab(P14), N8)
2115
2116Where
2117@ P14 is the data to encrypted. If P14 is the user’s password, it is a
2118 clear, upper-cased text string, padded with blanks
2119@ N8 is an 8 byte string whose value is available from Microsoft upon
2120 request
2121
2122
2123
2124Transaction Response Parameters section
2125
2126The transaction response parameters section consists of:
2127@ A 16 bit word indicating the return status. The possible values are:
2128
2129Code Valu Description
2130 e
2131NERR_Success 0 No errors encountered
2132ERROR_ACCESS_DENIED 5 User has insufficient privilege
2133ERROR-INVALID-PASSWORD 86 The specified password is invalid
2134NERR_PasswordCantChange 2243 The password cannot be changed
2135NERR_PasswordTooShort 2246 The password is too short
2136
2137Transaction Response Data section
2138
2139There is no Transaction Response Data to receive
2140
2141There is no auxiliary data in the response.
2142
2143
2144
214514. Author's Addresses
2146
2147Paul Leach
2148Dilip Naik
2149Microsoft
21501 Microsoft Way
2151Redmond, WA 98052
2152paulle@microsoft.com
2153v-dilipn@microsoft.com
2154
2155
215615. Appendix A
2157
2158Transaction SMBs
2159
2160These SMBs are used both to retrieve bulk data from the server (e.g.:
2161enumerate shares, etc.) and to change the server's state (EG: add a new
2162share, change file permissions, etc.) Transaction requests are also
2163unusual because they can have a multiple part request and/or a multiple
2164
2165
2166Leach, Naik [Page 34]
2167
2168
2169INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
2170
2171
2172part response. For this reason, transactions are handled as a set of
2173sequenced commands to the server. Each part of a request is sent as a
2174sequenced command using the same Mid value and an increasing Seq value.
2175The server responds to each request piece except the last one with a
2176response indicating that the server is ready for the next piece. The
2177last piece is responded to with the first piece of the result data. The
2178client then sends a transaction secondary SMB with ParameterDisplacement
2179set to the number of parameter bytes received so far and
2180DataDisplacement set to the number of data bytes received so far and
2181ParameterCount, ParameterOffset, DataCount, and DataOffset set to zero
2182(0). The server responds with the next piece of the transaction result.
2183The process is repeated until all of the response information has been
2184received. When the transaction has been completed, the redirector must
2185send another sequenced command (an echo SMB will do fine) to the server
2186to allow the server to know that the final piece was received and that
2187resources allocated to the transaction command may be released.
2188The flow is as follows, where (S) is the SequenceNumber, (N) is the
2189number of request packets to be sent from the client to the server, and
2190(M) is the number of response packets to be sent by the server to the
2191client:
2192
2193
2194 Client <-> Server
2195 ======================= === ===========================
2196
2197 SMB(S) Transact ->
2198 <- OK (S) send more data
2199 [ repeat N-1 times:
2200 SMB(S+1) Transact ->
2201 secondary
2202 <- OK (S+1) send more data
2203 SMB(S+N-1)
2204 ]
2205 <- OK (S+N-1) transaction
2206 response (1)
2207 [ repeat M-1 times:
2208 SMB(S+N) Transact ->
2209 secondary
2210 <- OK (S+N) transaction
2211 response (2)
2212 SMB(S+N+M-2) Transact ->
2213 secondary
2214 <- OK (S+N+M-2] transaction
2215 response (M)
2216 ]
2217 SMB(S+N+M-1) Echo ->
2218 <- OK (S+N+M-1) echoed
2219
2220
2221In order to allow the server to detect clients which have been powered
2222off, have crashed, etc., the client must send commands to the server
2223periodically if it has resources open on the server. If nothing has
2224been received from a client for awhile, the server will assume that the
2225client is no longer running and disconnect the client. This includes
2226closing any files that the client had open at the time and releasing any
2227resources being used on behalf of the client. Clients should at least
2228
2229
2230
2231Leach, Naik [Page 35]
2232
2233
2234INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
2235
2236
2237send an echo SMB to the server every four (4) minutes if there is
2238nothing else to send. The server will disconnect clients after a
2239configurable amount of time which cannot be less than five (5) minutes.
2240(Note: the NT server has a default timevalue of 15 minutes.)
2241
224215.1.1 TRANSACTIONS
2243
2244SMB_COM_TRANSACTION performs a symbolically named transaction. This
2245transaction is known only by a name (no file handle used).
2246SMB_COM_TRANSACTION2 likewise performs a transaction, but a word
2247parameter is used to identify the transaction instead of a name.
2248SMB_COM_NT_TRANSACTION is used for commands that potentially need to
2249transfer a large amount of data (greater than 64K bytes).
2250
225115.1.1.1 SMB_COM_TRANSACTION AND SMB_COM_TRANSACTION2 FORMATS
2252
2253 Primary Client Request Description
2254 =============================== ==================================
2255
2256 Command SMB_COM_TRANSACTION or
2257 SMB_COM_TRANSACTION2
2258
2259 UCHAR WordCount; Count of parameter words; value
2260 = (14 + SetupCount)
2261 USHORT TotalParameterCount; Total parameter bytes being sent
2262 USHORT TotalDataCount; Total data bytes being sent
2263 USHORT MaxParameterCount; Max parameter bytes to return
2264 USHORT MaxDataCount; Max data bytes to return
2265 UCHAR MaxSetupCount; Max setup words to return
2266 UCHAR Reserved;
2267 USHORT Flags; Additional information:
2268 bit 0 - also disconnect TID in
2269 TID
2270 bit 1 - one-way transaction (no
2271 resp)
2272 ULONG Timeout;
2273 USHORT Reserved2;
2274 USHORT ParameterCount; Parameter bytes sent this buffer
2275 USHORT ParameterOffset; Offset (from header start) to
2276 Parameters
2277 USHORT DataCount; Data bytes sent this buffer
2278 USHORT DataOffset; Offset (from header start) to data
2279 UCHAR SetupCount; Count of setup words
2280 UCHAR Reserved3; Reserved (pad above to word)
2281 USHORT Setup[SetupCount]; Setup words (# = SetupWordCount)
2282 USHORT ByteCount; Count of data bytes
2283 STRING Name[]; Name of transaction (NULL if
2284 SMB_COM_TRANSACTION2)
2285 UCHAR Pad[]; Pad to SHORT or LONG
2286 UCHAR Parameters[ParameterCount]; Parameter bytes (# =
2287 ParameterCount)
2288 UCHAR Pad1[]; Pad to SHORT or LONG
2289 UCHAR Data[ DataCount ]; Data bytes (# = DataCount)
2290
2291
2292 Interim Server Response Description
2293
2294
2295
2296Leach, Naik [Page 36]
2297
2298
2299INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
2300
2301
2302
2303 =============================== =================================
2304
2305 UCHAR WordCount; Count of parameter words = 0
2306 USHORT ByteCount; Count of data bytes = 0
2307
2308
2309 Secondary Client Request Description
2310 =============================== ==================================
2311
2312 Command SMB_COM_TRANSACTION_SECONDARY
2313
2314 UCHAR WordCount; Count of parameter words = 8
2315 USHORT TotalParameterCount; Total parameter bytes being sent
2316 USHORT TotalDataCount; Total data bytes being sent
2317 USHORT ParameterCount; Parameter bytes sent this buffer
2318 USHORT ParameterOffset; Offset (from header start) to
2319 Parameters
2320 USHORT ParameterDisplacement; Displacement of these Parameter
2321 bytes
2322 USHORT DataCount; Data bytes sent this buffer
2323 USHORT DataOffset; Offset (from header start) to data
2324 USHORT DataDisplacement; Displacement of these data bytes
2325 USHORT Fid; FID for handle based requests,
2326 else 0xFFFF. This field is
2327 present only if this is an
2328 SMB_COM_TRANSACTION2 request.
2329 USHORT ByteCount; Count of data bytes
2330 UCHAR Pad[]; Pad to SHORT or LONG
2331 UCHAR Parameters[ParameterCount]; Parameter bytes (# =
2332 ParameterCount)
2333 UCHAR Pad1[]; Pad to SHORT or LONG
2334 UCHAR Data[DataCount]; Data bytes (# = DataCount)
2335
2336
2337 Server Response Description
2338 =============================== ==================================
2339
2340 UCHAR WordCount; Count of data bytes; value = 10 +
2341 SETUPCOUNT
2342 USHORT TotalParameterCount; Total parameter bytes being sent
2343 USHORT TotalDataCount; Total data bytes being sent
2344 USHORT Reserved;
2345 USHORT ParameterCount; Parameter bytes sent this buffer
2346 USHORT ParameterOffset; Offset (from header start) to
2347 Parameters
2348 USHORT ParameterDisplacement; Displacement of these Parameter
2349 bytes
2350 USHORT DataCount; Data bytes sent this buffer
2351 USHORT DataOffset; Offset (from header start) to data
2352 USHORT DataDisplacement; Displacement of these data bytes
2353 UCHAR SetupCount; Count of setup words
2354 UCHAR Reserved2; Reserved (pad above to word)
2355 USHORT Setup[SetupWordCount]; Setup words (# = SetupWordCount)
2356 USHORT ByteCount; Count of data bytes
2357 UCHAR Pad[]; Pad to SHORT or LONG
2358 UCHAR Parameters[ParameterCount]; Parameter bytes (# =
2359 ParameterCount)
2360 UCHAR Pad1[]; Pad to SHORT or LONG
2361
2362
2363
2364Leach, Naik [Page 37]
2365
2366
2367INTERNET-DRAFT CIFS Remote Admin Protocol January 10, 1997
2368
2369
2370 UCHAR Data[DataCount]; Data bytes (# = DataCount)
2371
2372
2373
2374
237516. Appendix B
2376
2377
237816.1 Marshaling and unmarshaling using descriptor strings
2379
2380TBD. This will be a note to explain how the descriptor strings can be
2381used to drive a marshaling engine that can automatically marshal and
2382unmarshal RAP messages and call local APIs whose calling sequences
2383closely match the format of the RAP services.
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427Leach, Naik [Page 38] \ No newline at end of file