Microsoft Networks SMB FILE SHARING PROTOCOL EXTENSIONS SMB File Sharing Protocol Extensions Version 2.0 Document Version 3.3 November 7, 1988 Microsoft Corporation Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 2 - November 7, 1988 1. INTRODUCTION This document defines the extensions to the OpenNET/Microsoft Networks File Sharing Protocol (Intel PN 136329-001) (sometimes referred to as the "core" protocol) that are required to support Operating Systems richer in function than MS-DOS 3.x. The primary goal of these exten- sions is to allow fully transparent access to remote files for OS/2 systems using the Microsoft OS/2 LAN Manager. How- ever, they are not intended to be specific to OS/2. It is anticipated that other Operating Systems will have many similar requirements and that they will use the same ser- vices and protocols to meet them. This extension, when combined with the core protocol, allows all file oriented OS/2 functions to be performed on remote files using LANMAN 1.0. The extended protocol defined in this document is selected by the dialect string "LANMAN1.0" in the core protocol nego- tiate request. Acronyms used include: VC - Virtual Circuit. A transport level connection (some- times called a session) between two networked machines (nodes). TID - Tree Identifier. A token representing an instance of authenticated use of a network resource (often a shared subdirectory tree structure). UID - User Identifier. A token representing an authenti- cated user of a network resource. PID - Process Identifier. A number which uniquely identi- fies a process on a node. MID - Multiplex Identifier. A number which uniquely iden- tifies a protocol request and response within a pro- cess. FID - File Identifier. A number which identifies an instance of an open file ( sometimes called file han- dle). T.B.D.- To Be Defined. Further detail will be provided at a later time. MBZ - Must Be Zero. All reserved fields must be set to zero by the consumer. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 3 - November 7, 1988 2. MESSAGE FORMAT All messages sent while using the extended protocol (both the core messages used and the additional messages defined in this document) will have the following format. BYTE smb_idf[4]; /* contains 0xFF,'SMB' */ BYTE smb_com; /* command code */ BYTE smb_rcls; /* error class */ BYTE smb_reh; /* reserved for future */ WORD smb_err; /* error code */ BYTE smb_flg; /* flags */ WORD smb_res[7]; /* reserved for future */ WORD smb_tid; /* authenticated resource identifier */ WORD smb_pid; /* caller's process id */ WORD smb_uid; /* unauthenticated user id */ WORD smb_mid; /* multiplex id */ BYTE smb_wct; /* count of 16-bit words that follow */ WORD smb_vwv[]; /* variable number of 16-bit words */ WORD smb_bcc; /* count of bytes that follow */ BYTE smb_buf[]; /* variable number of bytes */ The structure defined from smb_idf through smb_wct is the fixed portion of the SMB structure sometimes referred to as the SMB header. Following the header there is a variable number of words (defined by smb_wct) and following that is smb_bcc which defines an additional variable number of bytes. A BYTE is 8 bits. A WORD is two BYTEs. The BYTEs within a WORD are ordered such that the low BYTE precedes the high BYTE. A DWORD is two WORDs. The WORDs within a DWORD are ordered such that the low WORD precedes the high WORD. smb_com: - command code. smb_rcls: - error class (see below). smb_ret: - error returned (see below). smb_tid: - Used by the server to identify a resource (e.g., a disk sub-tree). (see below) smb_pid: - caller's process id. Generated by the consumer (redirector) to uniquely identify a process within the consumer's system. A response message will always con- tain the same value in smb_pid (and smb_mid) as in the corresponding request message. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 4 - November 7, 1988 smb_mid: - this field is used for multiplexing multiple mes- sages on a single Virtual Circuit (VC) normally when multiple requests are from the same process. The PID (in smb_pid) and the MID (in smb_mid) uniquely identify a request and are used by the consumer to correlate incoming responses to previously sent requests. 3. NOTES: 1. smb_flg can have the following values: bit0 - When set (returned) from the server in the Negotiate response protocol, this bit indicates that the server supports the "sub dialect" consisting of the Lockan- dRead and WriteandUnlock protocols defined later in this document. bit1 - When on (on a protocol request being sent to the server), the consumer guarantees that there is a receive buffer posted such that a "Send.No.Ack" can be used by the server to respond to the consumer's request. The LANMAN 1.0 Redirector for OS/2 will not set this bit. bit2 - Reserved (must be zero). bit3 - When on, all pathnames in the protocol must be treated as caseless. When off, the pathnames are case sensitive. This allows forwarding of the protocol mes- sage on various extended VCs where caseless may not be the norm. The LANMAN 1.0 Redirector for OS/2 will always have this bit on to indicate caseless pathnames. bit4 - When on (on the Session Setup and X protocol defined later in this document), all paths sent to the server by the consumer are already in the canonicalized format used by OS/2. This means that file/directory names are in upper case, are valid characters and backslashes are used as seperators. bit5 - When on (on core protocols Open, Create and Make New), this indicates that the consumer is requesting that the file be "opportunisticly" locked if this pro- cess is the only process which has the file open at the time of the open request. If the server "grants" this oplock request, then this bit should remain set in the coresponding response protocol to indicate to the con- sumer that the oplock request was granted. See the Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 5 - November 7, 1988 discussion of "oplock" in the sections defining the "Open and X" and "Locking and X" protocols later in this document (this bit has the same function as bit 1 of smb_flags of the "Open and X" protocol). bit6 - When on (on core protocols Open, Create and Make New), this indicates that the server should notify the consumer on any action which can modify the file (delete, setattrib, rename, etc.). If not set, the server need only notify the consumer on another open request. See the discussion of "oplock" in the sec- tions defining the "Open and X" and "Locking and X" protocols later in this document (this bit has the same function as bit 2 of smb_flags of the "Open and X" pro- tocol). Bit6 only has meaning if bit5 is set. bit7 - When on, this protocol is being sent from the server in response to a consumer request. The smb_com (com- mand) field usually contains the same value in a proto- col request from the consumer to the server as in the matching response from the server to the consumer. This bit unambiguously distinguishes the command request from the command response. On a multiplexed VC on a node where both server and consumer are active, this bit can be used by the node's SMB delivery system to help identify whether this protocol should be routed to a waiting consumer process or to the server. 2. smb_uid is the user identifier. It is used by the LAN- MAN 1.0 extended protocol when the server is executing in "user level security mode" to validate access on protocols which reference symbolicly named resources (such as file open). Thus differing users accessing the same TID may be granted differing access to the resources defined by the TID based on smb_uid. The UID requested is validated by the server via the Session Set Up protocol. Note that -2 is reserved as an invalid UID. 4. In the LANMAN 1.0 extended protocol environment the TID represents an instance of an authenticated use. This is the result of a successful NET USE to a server using a valid netname and password (if any). If the server is executing in a "share level security mode", the tid is the only thing used to allow access to the shared resource. Thus if the user is able to perform a successful NET USE to the server specifying the appropriate netname and passwd (if any) the Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 6 - November 7, 1988 resource may be accessed according to the access rights associated with the shared resource (same for all who gained access this way). If however the server is executing in "user level secu- rity mode", access to the resource is based on the UID (validated on the Session Set UP protocol) and the TID is NOT associated with access control but rather merely defines the resource (such as the shared directory tree). In most SMB protocols, smb_tid must contain a valid TID. Exceptions include prior to getting a TID esta- blished including NEGOTIATE, TREE CONNECT, SESS_SETUPandX and TREE_CONNandX protocols. Other exceptions include QUERY_SRV_INFO some forms of the TRANSACTION protocol and ECHO. A NULL TID is defined as 0xFFFF. The server is responsible for enforcing use of a valid TID where appropriate. 5. As in the core, smb_pid uniquely identifies a consumer process. Consumers inform servers of the creation of a new process by simply introducing a new smb_pid value into the dialogue (for new processes). In the core protocol however, the "Process Exit" proto- col was used to indicate the catastrophic termination of a process (or session). In the single tasking DOS system, it was possible for hard errors to occur caus- ing the destruction of the process with files remaining open. Thus a Process Exit protocol was used for this occurrence to allow the server to close all files opened by that process. In the LANMAN 1.0 extended protocol, no "Process Exit" protocol will be sent. The operating system will ensure that the "close Protocol" will be sent when the last process referencing the file closes it. From the server's point of view, there is no concept of FIDs "belonging to" processes. A FID returned by the server to one process may be used by any other process using the same VC and TID. There is no "birth announcement" (no "fork" protocol) sent to the server. It is up to the consumer to ensure only valid processes gain access to FIDs (and TIDs). On TREE DISCONNECT (or when the VC environment is terminated) the server may invalidate any files opened by any process within the VC environ- ment using that TID. 6. Systems using the LANMAN 1.0 extended protocol will typically be multi-tasked and will allow multiple asyn- chronous input/output requests per task. Therefore a Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 7 - November 7, 1988 multiplex ID (smb_mid) is used (along with smb_pid) to allow multiplexing the single consumer/server VC among the consumer's multiple processes, threads and requests per thread. The consumer is responsible for ensuring that every request includes a value in the smb_mid field which will allow the response to be associated with the correct request (at least the smb_pid and smb_mid must uniquely identify the request/response relationship system wide). The server is responsible for ensuring that every response contains the same smb_mid value (and smb_pid value) as its request. The consumer may then use the smb_mid value (along with smb_pid value) for associat- ing requests and responses and may have up to the nego- tiated number of requests outstanding at any time on a multiplexed file server VC. 7. The LANMAN 1.0 extended protocol enhances the semantics of the pathname. Two special pathname component values -- "." and ".." -- must be recognized. There may be multiple of these components in a path name. They have the standard meanings -- "." points to its own directory, ".." points to its directory's parent. Note that it is the server's responsibility to ensure that the ".." can not be used to gain access to files/directories above the "virtual root" as defined by the Tree Connect (TID). 8. The new LANMAN 1.0 extended protocol requests and responses are variable length (as was true in "core"). Thus additional words may be added in the smb_vwv[] area in the future as well as additional bytes added within the smb_buf[] area. Servers must be implemented such that additional fields in either of these areas will not cause the command to fail. If additional fields are encountered which are not recognized by the server's level of SMB implementation, they should be ignored. This allows for future upgrade of the protocol and eliminates the need for "reserved fields". 9. The contents of response parameters is not guaranteed in the case of an error return (any protocol response with an error set in the SMB header may have smb_wct of zero and smb_bcc count of zero). Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 8 - November 7, 1988 10. When LANMAN 1.0 extended protocol has been negotiated, the ERRDOS error class has been expanded to include all errors which may be generated by the OS/2 operating system. As such, the error code values defined for error class ERRDOS in this document are a subset of the possible error values. See the OS/2 operating system documentation for the complete set of possible OS/2 (ERRDOS) error codes. These semantic changes apply to all "core" requests used by the extended protocol. Where there are additional changes, they are documented with the new requests. The server hav- ing negotiated LANMAN 1.0 is expected to still support all core protocol requests. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 9 - November 7, 1988 The following are the core protocol requests which must still be supported in the LANMAN 1.0 extended protocol without change. See "File Sharing Protocol" Intel Part number 136329-001 for detailed explanation of each protocol request/response. TREE CONNECT TREE DISCONNECT OPEN FILE CREATE FILE CLOSE FILE FLUSH FILE READ WRITE SEEK CREATE DIRECTORY DELETE DIRECTORY DELETE FILE RENAME FILE GET FILE ATTRIBUTES SET FILE ATTRIBUTES LOCK RECORD UNLOCK RECORD CREATE TEMPORARY FILE (no longer used by LANMAN 1.0 Redirector) PROCESS EXIT (no longer used by LANMAN 1.0 Redirector) MAKE NEW FILE CHECK PATH GET SERVER ATTRIBUTES NEGOTIATE PROTOCOL (additional fields in response if LANMAN 1.0 negotiated) FILE SEARCH CREATE PRINT FILE CLOSE PRINT FILE WRITE PRINT FILE (core Message Commands are also supported) Support of all core requests within the LANMAN 1.0 extended protocol is mandatory. However, the following core requests will no longer be generated by the OS/2 implementation of the redirector when LANMAN 1.0 extended protocol has been negotiated. PROCESS EXIT CREATE TEMPORARY FILE CREATE PRINT FILE CLOSE PRINT FILE WRITE PRINT FILE The only protocol format change to a core protocol service is that the response to the negotiate protocol (NEGOTIATE PROTOCOL) will contain additional fields if the LANMAN1.0 string has been selected by the server thus effectively placing the session into LANMAN 1.0 extended protocol. The additional fields returned will be documented in detail later in this document. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 10 - November 7, 1988 All other protocol requests within the LANMAN 1.0 extended protocol have a new command value from that of a similar function in core protocol. Thus the server need not con- stantly test the protocol version negotiated. The consumer is expected to only submit appropriate requests within the dialect negotiated. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 11 - November 7, 1988 The following are the new LANMAN 1.0 extended protocol requests, each will be defined in detail later in this docu- ment. SESS_SETUPandX (X is another valid protocol request e.g. TREE_CONNandX) TREE_CONNandX (X is another valid protocol request e.g. OPEN) OPENandX (X is another valid protocol request e.g. READ) READandX (X is another valid protocol request e.g. CLOSE) WRITEandX (X is another valid protocol request e.g. READ) FIND (matches OS/2 form of FILE SEARCH) FIND_UNIQUE (matches OS/2 form of FILE SEARCH) FIND_CLOSE (matches OS/2 form of FILE SEARCH) READ_BLOCK_RAW (read larger than negotiated buffer size request raw) READ_BLOCK_MPX (read larger than negotiated buffer size request multiplexed) WRITE_BLOCK_RAW (write larger than negotiated buffer size request raw) WRITE_BLOCK_MPX (write larger than negotiated buffer size request multiplexed) GET_E_FILE_ATTR (accommodate new OS/2 system call) SET_E_FILE_ATTR (accommodate new OS/2 system call) LOCKINGandX (accommodate new OS/2 system call) COPY_FILE (used when both source and target are remote) MOVE_FILE (used when both source and target are remote) IOCTL (pass IOCTL request on to server and retrieve results) TRANSACTION (allows bytes in/out associated with name) ECHO (echo sent data back) WRITEandCLOSE (write final bytes then close file) LOCKandREAD (Lock bytes then Read locked bytes) WRITEandUnlock (Write bytes then Unlock bytes) On every new command ending in "and_X" above, the following rules apply: o The embedded command does not repeat the SMB header information. Rather it starts at the smb_wct field. o All multiple (chained) requests must fit within the negotiated transmit size. For example, if TREE_CONNandX included OPENandX which included WRITE were sent, they would all have to fit within the nego- tiated buffer size. This would limit the size of the write. o There is one (negotiated buffer size max) message sent containing the chained requests and there is one (nego- tiated buffer size max) response message to the chained requests. The server may NOT elect to send separate responses to each of the chained requests. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 12 - November 7, 1988 o All multiple (chained) responses must fit within the negotiated transmit size. This limits the maximum value on an embedded READ for example. It is the consumer's responsibility to not request more bytes than will fit within the multiple response. o The server will implicitly use the result of the first command in the "X" command. For example the TID obtained via TCONandX would be used in the embedded OPENandX and the FID obtained in the OPENandX would be used in the embedded READ. o If multiple (chained) requests reference a FID, the smb_fid field must contain the same FID value in each request. In other words, each request can only refer- ence the same FID (and TID) as the other commands in the combined request. The chained requests can be thought of as performing a single (multi-part) opera- tion on the same resource. This simplifies the han- dling by the worker process on the server node. o The first function (command) to encounter an error will stop all further processing of embedded commands. The server will NOT back out commands that succeeded. Thus if and OPENandRead was being performed and the server was able to open the file successfully but the read encountered an error, the file would remain open. This is exactly the same as if the requests had been sent separately. o If an error occurs while processing chained requests, the last response (of the chained responses in the buffer) will be the one which encountered the error. Other unprocessed chained requests will have been ignored when the server encountered the error and will not be represented in the chained response. Actually the last valid smb_com2 (if any) will represent the protocol on which the error occurred. If no valid smb_com2 is present, then the error occurred on the first request/response and smb_com contains the command which failed. In all cases the error class and code is returned in the smb_rcls and smb_err fields of the SMB header at the start of the response buffer. o Each chained request and response contains the offset (from the start of the SMB header) to the next chained request/response (in the field smb_off2 in the various "and X" protocols defined later e.g. Open and X). This allows building the requests unpacked. There may be Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 13 - November 7, 1988 space between the end of the previous request (as defined by smb_wct and smb_bcc) and the start of the next chained request. This simplifies the building of chained protocol requests. Note that because the con- sumer must know the size of the data being returned in order to post the correct number of receives (e.g. Transaction, Read Block MPX), the data in each response protocol is expected to be truncated to the maximum number of 512 byte blocks (sectors) which will fit (starting at a DWORD boundary) in the negotiated buffer size with the odd bytes remaining (if any) in the final buffer. 4. ARCHITECTURAL MODEL The Network File Access system described in this document deals with two types of systems on the network -- consumers and servers. A consumer is a system that requests network file services (commonly referred to as the redirector in DOS) and a server is a system that delivers network file services. Consumers and servers are logical systems; a con- sumer and server may coexist in a single physical system. Consumers are responsible for directing their requests to the appropriate server. The network addressing mechanism or naming convention through which the server is identified is outside the scope of this document. Each server makes available to the network a self-contained file structure (or other resource). The resource being shared may be a directory tree, spooled device, I/O device, named pipe, etc.. There are no storage or service dependen- cies on any other servers. A file (or other resource) must be entirely contained by a single server. The LANMAN 1.0 extended (like the core) file sharing proto- col requires server authentication of users before file accesses are allowed. Each server processor authenticates its own users. This authentication model assumes that the LAN connects autonomous systems that are willing to make some subset of their local files (or other resource) available to remote users. The LANMAN 1.0 extended protocol however defines two methods which can be selected by the server for security. A "share level security mode" server makes some directory on a disk device (or other resource) sharable (accessible from any consumer on the network). An optional password may be required to gain access. Thus any user on the network who knows the name of the server, the name ("netname") of the Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 14 - November 7, 1988 resource and the password (if any) has full access to all files and directories under the shared "tree" ("full" access as defined by the access level specified for the share). A "user level security mode" server also makes some direc- tory on a disk device (or other resource) sharable but in addition requires the user to provide an account (user) name (and optional account (user) password) in order to gain access. The consumer also supplies the UID value it wishes to represent this user (see Session Set Up protocol defini- tion). Thus the server is now able to allow differing access rights depending on the validated UID (in smb_uid) on each resource. One account may have full access, another read only and perhaps another no access to differing files and directories within the shared "tree". Access implementa- tions are server dependent and outside the scope of this document, however user level security mode allows validating access based on account-name (and password) access control lists associated with each resource. The server is expected to be in either "user level security mode" or "share level security mode" (not in some combina- tion). The security mode of the server is returned in the response on the negotiate command if LANMAN 1.0 extended dialect is selected by the server. This allows the consumer to easily select the appropriate protocols to be used. The following environments exist in the LANMAN 1.0 extended file sharing protocol environment. a) Virtual Circuit Environment. This consists of one or more VC(s) established between a consumer system and server system. Thus it is the logical session between the server node and consumer node which is implemented with the use of one or more Virtual Circuits. Each of these VC(s) may be a multiplex VC in that any number of tasks and any number of requests may be active on the VC at the same time. Additional VC(s) are used primarily to support optional LANMAN 1.0 extended protocols which allow rapid data movement if only one process is active on the VC. Con- sumers using additional VC(s) would normally have only a single request active on the VC at any time, in order to receive data directly into user space for example. Additional VC(s) when used are to be considered a logi- cal extension of the first VC. A smb_tid field in a protocol received on an additional VC should be authen- ticated to the one established on the first VC, etc.. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 15 - November 7, 1988 All of the VCs are the same as far as the server is concerned. Support for more than one VC between the consumer and server is optional. If more than one VC is in use, the server must ensure that all responses are sent on the same VC which received the request. A VC is formed using transport services. b) Resource Environment. As in the core protocol, this is represented by a Tree ID (TID). A TID uniquely identi- fies a resource sharing connection between a consumer and server. The resource being shared may be a direc- tory tree, spooled device, I/O device, named pipe, etc.. In a server executing in "share level security mode" (and also in servers which do not support these extended protocols), the TID also identifies the scope and type of accesses allowed across the connection. In most SMB protocols, smb_tid must contain a valid TID. Exceptions include prior to getting a TID esta- blished including NEGOTIATE, TREE CONNECT, SESS_SETUPandX and TREE_CONNandX protocols. Other exceptions include QUERY_SRV_INFO some forms of the TRANSACTION protocol and ECHO. A NULL TID is defined as 0xFFFF. The server is responsible for enforcing use of a valid TID where appropriate. There may be any number of resource sharing connections (TIDs) per VC set. c) User Environment. This is represented by a User ID (UID). A UID in (smb_uid) uniquely identifies a user within a given VC environment. A server (executing in "user level security mode") uses this to identify the scope and type of access allowed this user. c) Process Environment. This is represented by a process ID (PID). A PID uniquely identifies a consumer process (thread) within a given VC environment. From the server's point of view, a new process (new value in smb_pid) may be introduced at any time. There is no "fork" protocol and files opened by another process may be manipulated by the new process (provided the appropriate smb_tid is supplied). d) File Environment. This is represented by a File Handle (FID). A FID identifies an open file and is unique within a given VC environment (same File Handle (FID) Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 16 - November 7, 1988 may be used in additional VC(s)). Note that the File Handle (FID) is logon environment wide in scope. A file may be opened and its Handle passed to another process for use without being opened by that process. The smb_tid field must contain the same value as that used when the file was opened. If a VC environment (all VC(s)) is terminated all PIDs, TIDs and FIDs within it will be invalidated. Note - additional VC(s) may be terminated without terminating the "VC environ- ment". If a Resource Environment is terminated (TID invalidated via Tree Disconnect protocol) all PIDS and FIDs within it will be invalidated. 4.1. Process Management How and when servers create and destroy processes is, of course, an implementation issue and there is no requirement that this be tied in any way to the consumer's process management. Because a file handle may be obtained by one consumer pro- cess and passed to another (e.g. child) process for use, the server can not release resources such as locks or FIDs on process exit (Note that process exit is no longer sent). Rather the server must wait until the lock is removed or the file closed by the consumer. Consumer implementations should close handles and free locks as soon as possible to prevent server resource problems. When the server receives a tree disconnect protocol, all processes, locks, FIDs, etc. created on behalf of that TID (logon environment) may be freed. If the VC aborts (VC environment is terminated) then all resources for the consuming node may be freed. All messages, except Negotiate, include a process ID (PID) to indicate which user process initiated a request. Consu- mers inform servers of the creation of a new process by sim- ply introducing a new PID into the dialogue. There is no "fork" protocol to indicate to the server any parent child process relationship. This is not needed because any pro- cess may use handles created by another process (there is no special privilege or relationship to the parent process). Thus most server implementations will not need the PID, how- ever, the PID value in smb_pid must be returned in the response (along with smb_mid) for the use of the consumer's "SMB delivery system". Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 17 - November 7, 1988 In the LANMAN 1.0 extended protocol, no "Process Exit" pro- tocol will be sent. The operating system will ensure that the "close Protocol" will be sent when the last process referencing a file closes it. Note that a close implicitly frees locks which may be present on the file (those locks placed on the file using the file handle being closed). 5. File Sharing Connections The networks using this file sharing protocol will contain not only multi-user systems with user based security models, but single-user systems that have no concept of user-ids or permissions. Once these nodes are connected to the network, however, they are in a multi-user environment and need a method of access control. First, unsecure nodes need to be able to provide some sort of bona-fides to other net nodes which do have permissions, secondly unsecure nodes need to control access to their resources by others. This protocol defines a mechanism that enables the network software to provide the security where it is missing from the operating system, and supports user based security where it is provided by the operating system. The mechanism also allows nodes with no concept of user-id to demonstrate access authorization to nodes which do have a permission mechanism. Finally, the permission protocol is designed so that it can be omitted if both nodes share a common permis- sion mechanism. This protocol, called the "tree connect" protocol, does not specify a user interface. A possible user interface will be described by way of illustration. 5.1. Share Level Security Mode Server Nodes The following examples apply to access to serving systems which do NOT have a user based permission mechanism. a) NET SHARE By default all network requests are refused as unauthorized. Should a user wish to allow access to some or all of his files he offers access to an arbitrary set of subtrees by specifying each subtree and an optional password. Examples: NET SHARE src=c:\dir1\src "bonzo" assign password "bonzo" to all files within directory "dir1\src" and its subdirectories with the "short name" src being the name used to connect to this offer. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 18 - November 7, 1988 NET SHARE c=c:\ " " RO NET SHARE work=c:\work "flipper" RW offer read-only access to everything (all files are within the root directory or its subdirectories) Offer read-write access to all files within the \work direc- tory and its subdirectories. b) NET USE Other users can gain access to one or more offered subtrees via the NET USE command. Once the NET USE command is issued the user can access the files freely without further special requirements. Examples: 1. NET USE d: \\Server1\src "bonzo" This gains full access to the files and directories on Server1 matching the offer defined by the netname "src" with the password of "bonzo". The user may now address files on Server1 c:\dir1\src by referencing d:. E.g. "type d:srcfile1.c". 2. NET USE e: \\Server1\c 3. NET USE f: \\Server1\work "flipper" Now any read request to any file on that node (drive c) is valid (e.g. "type e:\bin\foo.bat"). Read-write requests only succeed to files whose pathnames start with f: (e.g. "copy foo f:foo.tmp" copies foo to Server1 c:\work\foo.tmp). The consumer system must remember the drive identifier sup- plied with the NET USE request and associate it with the TID value returned by the server. Subsequent requests using this TID must include only the pathname relative to the con- nected subtree as the server treats the subtree as the root directory (virtual root). When the user references one of the remote drives, the con- sumer looks through its list of drives for that node and includes the TID associated with this drive in the smb_tid field of each request. Note that one offers (shares) a directory and all files underneath that directory are then affected. If a particu- lar file is within the range of multiple offer ranges, con- necting to any of the offer ranges gains access to the file with the permissions specified for the offer named in the NET USE. The server will not check for nested directories Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 19 - November 7, 1988 with more restrictive permissions. 5.2. User Level Security Mode Server Nodes Servers with user based file security (in "user level secu- rity mode") will require that the consumer present an account name and account passwd (if any) along with the requested UID value (via the Session Set Up protocol) prior to accessing resources. When the Session Set Up request is received, the account- name is validated and the UID representing that authenti- cated instance of the user is validated. This UID must be included in all further requests made on behalf of the user. The Tree Connect protocol is still used to define the direc- tory (tree) or other resource available to the user. The server in user level security mode uses the UID to allow differing types of access to the same resources under a given TID. Note that a single consumer user may issue multiple Tree Connect commands in order to gain access to multiple shared resources. Multiple Session Set Up commands may also be issued in order to validate additional users. NOTE - The first release of LANMAN 1.0 will allow only one valid user at a time. A user established by a Session Set Up command may be logged off via the User Logoff and X command (after all files and other resources in use are closed) and the Session Set Up and X command used to validate another userid. The permission-based (user level security mode) systems may execute a NET SHARE command which shares the entire system and set up name/password (or whatever) information in its user definition files in order to allow user/group based access to the shared files. The server will return whether it is executing in user level security mode or share level security mode in the extended Negotiate response protocol (when the LANMAN 1.0 dialect has been selected). This allows the consumer to know whether the "User Logon" information is needed in the Session Set Up protocol. A server in user level security mode (having negotiated core protocol with the consumer node) will accept the core format of the Tree Connect command and do the following: Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 20 - November 7, 1988 If the consumer's node name is defined as an account-name (and the Tree Connect passwd matches), the "user logon" will be performed using that value. If the above fails, the server may fail the request or assign a default account name (probably allowing limited access). The value in smb_uid will then be ignored and all access will be validated assuming the account name selected above. The above allows servers in "user level security mode" to accommodate core protocol users. 5.3. Connection Protocols The NET SHARE command generates no network messages. The server remembers the pathname's netname and the password for later verification. The NET USE command generates a tree connect message con- taining the netname and the associated password. If the server is in "user level security mode" the UID, account- name and account-password will also be supplied via the "Session Set Up" protocol. If the no Session Set Up proto- col is received, the server will try the consumer node name as described above. On receiving the Tree Connect protocol, the serving node verifies the name/password combination and returns an error code or an identifier (the TID). The short-name is included in the Tree Connect request mes- sage and the identifier (TID) identifying the connection is returned in the smb_tid field. The meaning of this identif- ier (TID) is server specific; the requester must not associ- ate any specific meaning to it. The server makes whatever use of the TID it desires. Nor- mally it is an index into a server table which allows the server to optimize its response. The consumer must associate the identifier with the device name being redirected (specified in the NET USE) and include the appropriate identifier (TID) for all network file accesses made. 5.4. USER ADMINISTRATION The LANMAN 1.0 extended protocol makes use of the "Server Based" method of user administration and allows for "Consu- mer Based" user administration. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 21 - November 7, 1988 The server based approach is similar to the consumer authen- tication scheme used by the core protocol. It is based on the principle that the consumer processors may or may not be trusted to authenticate users. It assumes that the LAN con- nects autonomous systems that are willing to make some sub- set of their local files available to remote users. On some networks, there may be centralized logon servers or some other means to guarantee that a global UID is unique and valid. In these networks, the consumer will merely introduce a new UID into the SMB header and the server will know who it represents and that it is valid. This is known as a "consumer based" approach in that the consumer is responsible for validating the users. The protocol supports both types of administration in that the server may respond with ERRbaduid which will require that the consumer send a Session Set Up command to "logon" the user or it may just accept a new UID from a "trusted" consumer node. Each server may maintain a list of valid users (or invoke some other means of user validation). It may then verify every access by these users. It can therefore accept any and all transport connections offered. A UID is selected by the consumer and validated by the server via the Session Set Up protocol. This UID is used to both identify the user on all subsequent requests and prove to the server that this user has been authenticated. The consumer must associate the UID with the user and include the appropriate identifier (UID) for all network file accesses made by that user. From the servers point of view the user identifier (UID) is therefore NOT associated with a particular offer (shared resource identified by the TID) but the authenticated user. The UID may be used to access any shared resource which has been connected to via the Tree Connect protocol. 5.5. FILE SECURITY The specific file security model enforced by a server in "user level security mode" is outside the scope of this document, however, the types of access a user may expect are discussed here. As was true in core protocol, the user must be prepared to be denied access. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 22 - November 7, 1988 With LANMAN 1.0 extended protocol and the server in "user level security mode" the user should expect to be allowed differing access to different files within the same shared Tree structure. He/she may be allowed to read one file only and yet be able to write to others in the same directory. Files may have specific access permissions for specified users or groups, and another set of permissions for all other users. The protocol provides no way to set or modify the permis- sions of the files and directories on the server. It is expected that the "system administrator" of the server will have a mechanism to set and modify permissions. When files are created on the server, the files by default take on the permissions defined by the parent directory. 5.6. FILE ATTRIBUTES AND TYPES The LANMAN 1.0 Extended File Sharing Protocol may support additional attributes to those specified in the Core File Sharing Protocol. The LANMAN 1.0 Extended File Sharing Protocol may support additional file types to those specified in the Core File Sharing Protocol. The following file types will be sup- ported by the LANMAN 1.0 implementation: named pipes message mode named pipes I/O devices mail slots NAMED PIPES Named pipes provide a new facility which allows pipes to be named and act like full duplex virtual circuits between a pair of endpoints. Named Pipe Features o Allows LANMAN 1.0 pipes to be named and accessed across a network. o Once created, named pipes can be opened and read/written like standard files, i.e., using Open, Read, Write, and Close protocols. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 23 - November 7, 1988 o Named pipes support message as well as byte stream modes. o Byte stream mode lets processes read and write byte streams, exactly like byte conventional pipes, except the pipe is full-duplex, emulating a virtual circuit. o Message mode lets processes read and write streams of messages (as opposed to bytes). Message mode is optim- ized for peer-to-peer communication between remote as well as local processes. o Named pipes can be serially re-used by different clients (closed and reopened by another process). o A serving process can create multiple identically named pipes so that multiple clients opening to that name will get distinct pipes to the serving process. o Unmodified core consumers can access named pipes on a OS/2 server as if they were accessing a sequential file. I/O DEVICES The LANMAN 1.0 extended protocol allows a device to be opened for driver level I/O. This provides direct access to real time and interactive devices such as modems, scanners, etc.. Two such types of devices are defined, COM - communi- cation devices like modems or terminals and LPT - printer devices which will be accessed directly (not spooled). 5.6.1. REPRESENTATION On LANMAN 1.0 Extended Protocol servers the attribute field has the following format (bit0 is the least significant bit). This field matches that used by OS/2. bit0 - read only file bit1 - "hidden" file bit2 - system file bit3 - reserved bit4 - directory bit5 - archive file bits6-15 - reserved (must be zero) Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 24 - November 7, 1988 The LANMAN 1.0 Extended resource type field defines the additional resource types: 0 - Disk file or directory as defined in the attribute field. 1 - FIFO (named pipe) 2 - Named pipe (message mode) 3 - LPT (printer) Device 4 - COM (communication) Device 6. TIMEOUTS The LANMAN 1.0 extended protocol provides for actions timing out on the server. Actions which may time out include: o Opens (to I/O devices) o Locks (on records within files) o read/write (on I/O devices) If a server implementation can not support timeouts, then an error can be returned just as if a timeout had occurred if the resource is not available immediately upon request. 7. QUEUEING The LANMAN 1.0 extended protocol provides for Queuing for Opens of I/O devices and for bytes within a file to become free (unlocked). If a server implementation can not support queuing and the resource being queued for is busy, simply respond with a "busy" error just as if the queued request had timed out. The same thing could happen if queuing was supported but the queue remained full. 8. EXCEPTION HANDLING Exception handling within the LANMAN 1.0 extended protocol environment is an extension to the core techniques. It is built upon the various environments supported by the file sharing protocol. When any environment is dissolved (in either an orderly or disorderly fashion) all contained environments are dissolved. The hierarchy of environments is summarized below: Server Based User Authentication: Virtual Circuit Environment TID PID FID Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 25 - November 7, 1988 As can be seen from the summary, the Virtual Circuit (VC) is the key environment. When a VC environment (the last VC) is dissolved the server processes (or equivalent) are ter- minated; the TIDs and FIDs are invalidated, and outstanding requests are dropped -- responses will not be generated. The termination of a TID will cause the termination of all PIDs (or equivalent) created in support of that TID and close of all FIDs opened using the TID as the access key. The destruction of PIDs and FIDs has no affect on other environments. The rules for VC establishment and dissolution are identical to those enforced by the core file sharing protocol with the following exceptions: o If a server receives a VC establishment request from a consumer with which it is already conversing, it will be accepted as an "additional" VC to be used for rapid data movement protocols. The negotiate protocol will then be used to indicate if the consumer intends this VC to be the first VC or as an additional VC. If the consumer specified that this was to be the first VC, all other VCs to that consumer may be aborted. o A server may drop the VC to a consumer at any time if the consumer is generating illogical requests. How- ever, wherever possible the server should first return an error code to the consumer indicating the cause of the VC abort. o If a server gets a hard error on a VC (such as a send failure) all VCs to that consumer may be aborted. o A server may drop the VC on last Tree Disconnect, how- ever, we recommend that the drop be performed only after an automatic timeout time has passed or when the VC resource is needed. This will help performance in that the VC will not need to be reestablished if activity occurs again before the "timeout" time. Some server implementations will perform a "soft timeout" where if no tree connects (and thus no other resources) are in use on a VC, it may age until the server elects to drop it allowing other users access. Other implementations include a "hard timeout" in that if a VC has not been used for a (system administrator defined) amount of time, the VC will be aborted des- troying all Tree Connections etc. which are still on the session. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 26 - November 7, 1988 Others use an as needed basis where one or both of the above methods are used but only when Virtual Circuits are needed. A consumer is always expected to be able to reestablish in the case where the VC was dropped with no valid tree connects (and thus no other resources) on it. For Hard timeouts, the user may receive errors and have to reconnect (do another NET USE) in order to reestab- lish the session. This is similar to many "switch" timeouts on multi-user systems. On write behind activity, a subsequent write or close of the file will return the fact that a previous write failed. Normally write behind failures are limited to hard disk errors and device out of space. 9. EXTENDED PROTOCOL The format of enhanced and new commands is defined commenc- ing at the smb_wct field. All messages will include the standard SMB header defined in section 1.0. When an error is encountered a server may choose to return only the header portion of the response (i.e., smb_wct and smb_bcc both con- tain zero). 9.1. CORE SERVICE ENHANCEMENTS The LANMAN 1.0 extended protocol includes functional enhancements to some core services, and these are defined in this section. Enhancements to services can only add to the service's existing semantics, i.e., additional values for parameters may be introduced and new parameters added, but parameters cannot be removed or used for a different pur- pose. All "core" requests must continue to function with the enhanced command. If these rules cannot be followed a new command must be defined. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 27 - November 7, 1988 9.1.1. NEGOTIATE Request Format is unchanged in order to remain compatible with earlier versions and the core protocol. Enhanced Response Format (returned only when LANMAN 1.0 dialect is selected): BYTE smb_wct; /* value = 13 */ WORD smb_index; /* index identifying dialect selected */ + WORD smb_secmode; /* security mode: bit 0 - 1 = User level security, 0 = Share level security. */ bit 1 - 1 = encrypt passwords , 0 = do not encrypt passwords */ + WORD smb_maxxmt; /* max transmit buffer size server supports, 1k min */ + WORD smb_maxmux; /* max pending multiplexed requests server supports */ + WORD smb_maxvcs; /* max VCs per server/consumer session supported */ + WORD smb_blkmode; /* block read/write mode support : bit 0 - Read Block Raw supported (65,535 bytes max). bit 1 - Write Block Raw supported (65,535 bytes max). */ +DWORD smb_sesskey; /* Session Key (unique token identifying session) */ + WORD smb_srv_time; /* server's current time (hhhhh mmmmmm xxxxx) where 'xxxxx' is in two second increments */ + WORD smb_srv_date; /* server's current date (yyyyyyy mmmm ddddd) */ + WORD smb_srv_tzone; /* server's current time zone */ +DWORD smb_rsvd; /* reserved */ WORD smb_bcc; /* value = (size of smb_cryptkey) */ + BYTE smb_cryptkey[]; /* Key used for password encryption */ + Additional parameters In addition, if bit ZERO (low order bit) of smb_flg is set (returned) from the server in the Negotiate response proto- col header, this indicates that the server supports the "sub dialect" consisting of the LockandRead and WriteandUnlock protocols. Service Enhancement: The dialect string for the LANMAN 1.0 extended protocol specified in this document is: LANMAN1.0 Having selected LANMAN 1.0 as the dialect, the consumer needs to be informed of whether or not the server is execut- ing in "share level security mode" or "user level security mode" in order to format appropriate Session Set Up proto- cols. Whether or not Read Block Raw (where up to 65,535 bytes of data may be read directly into user space) is supported is returned. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 28 - November 7, 1988 Whether or not Write Block Raw (where up to 65,535 bytes of data may be written directly from user space) is supported is returned. The smb_sesskey value is used to validate additional VCs added to a session (via the Session Set Up protocol). The minimum server SMB buffer size (smb_maxxmt) is 1024 bytes (1k). This provides sufficient room for most proto- cols including the simple "request-response" mode of the IOCTL protocol. Note that smb_maxxmt returned in the NEGOTIATE response is the server buffer size supported. Thus this is the max SMB message size which the consumer can send to the server. This size may be larger than smb_bufsize returned to the server from the consumer via the SESSION SETUP and X proto- col which is the maximum SMB message size which the server may send to the consumer. Thus if the server's buffer size (as indicated in smb_maxxmt on NEGOTIATE) were 4k and the consumer's buffer size were only 2k (as indicated in smb_bufsize on SESSION SETUP and X), The consumer could send up to 4k (standard) write requests but must only request up to 2k for (standard) read requests. The max transaction response from the server would also be 2k. LANMAN 1.0 will use a cryptkey of 8 bytes. The date is in the following format: bits: 1111 11 5432 1098 7654 3210 yyyy yyym mmmd dddd where: y - bit of year 0-119 (1980-2099) m - bit of month 1-12 d - bit of day 1-31 The time is in the following format: bits: 1111 11 5432 1098 7654 3210 hhhh hmmm mmmx xxxx where: h - bit of hour (0-23) m - bit of minute (0-59) x - bit of 2 second increment Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 29 - November 7, 1988 Negotiate may generate the following errors. Error Class ERRDOS Error Class ERRSRV ERRerror Error Class ERRHRD 9.2. ADDITIONAL SERVICES This LANMAN 1.0 Extension Set includes all functions con- sidered necessary to provide transparency for all essential or frequently used file access functions. OS/2 requirements have been used as a guide for selecting the services included here; when other common operating systems are con- sidered in more detail it may prove necessary to expand this set. The protocols in this section are presented in alphabetical order. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 30 - November 7, 1988 9.2.1. COPY Request Format: BYTE smb_wct; /* value = 3 */ WORD smb_tid2; /* second (destination) path tid */ WORD smb_ofun; /* what to do if destination file exists */ WORD smb_flags; /* flags to control copy operations: bit 0 - destination must be a file. bit 1 - destination must be a directory. bit 2 - copy destination mode: 0 = binary, 1 = ASCII. bit 3 - copy source mode: 0 = binary, 1 = ASCII. bit 4 - verify all writes. */ WORD smb_bcc; /* minimum value = 2 */ BYTE smb_path[]; /* pathname of source file */ BYTE smb_new_path[]; /* pathname of destination file */ Response Format: BYTE smb_wct; /* value = 1 */ WORD smb_cct; /* number of files copied */ WORD smb_bcc; /* minimum value = 0 */ BYTE smb_errfile[]; /* pathname of file where error occured - ASCIIZ */ Service: The file referenced by smb_path is copied to smb_new_path. Both smb_path and smb_new_path must refer to paths on the server. The server must do any necessary access permission checks on both the source and the destination paths. The TID in smb_tid of the header is associated with the source while smb_tid2 is associated with the destination. These TID fields may contain the same or differing valid TIDs. Note that smb_tid2 can be set to -1 indicating that this is to be the same TID as the TID in smb_tid of the header. This allows use of the copy protocol with TCONandX. The source path must refer to an existing file or files. Wild Cards are permitted. Source files specified by Wild Cards are processed until an error is encountered. If an error is encountered, the expanded name of the file is returned in smb_errfile. The error code is returned in smb_err. The destination path can refer to either a file or a direc- tory. The destination can be required to be a file or a directory by smb_flags bits. If neither bit is set, the destination may be either a file or a directory. Wild Cards are not permitted in the destination path. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 31 - November 7, 1988 If the destination is a file and the source contains Wild Cards, the destination file will either be truncated or appended to at the start of the operation (depending on bits in smb_ofun) . Subsiquent files will then be appended to the file. smb_ofun bit field mapping: bits: 1111 11 5432 1098 7654 3210 rrrr rrrr rrrC rrOO where: O - Open (action to be taken if destination file exists). 0 - Fail. 1 - Append file. 2 - Truncate file. r - reserved (must be zero). C - Create (action to be taken if destination file does not exist). 0 -- Fail. 1 -- Create file. Copy may generate the following errors. Error Class ERRDOS ERRbadfile ERRbadpath ERRfileexists ERRnoaccess ERRnofiles ERRbadshare Error Class ERRSRV ERRerror ERRinvnid ERRnosupport ERRaccess Error Class ERRHRD Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 32 - November 7, 1988 9.2.2. ECHO Request Format: BYTE smb_wct; /* value = 01 */ WORD smb_reverb; /* number of times to echo data back */ WORD smb_bcc; /* minimum value = 4 */ BYTE smb_data[]; /* data to echo back */ Response Format (one for each echo requested): BYTE smb_wct; /* value = 1 */ WORD smb_seq; /* sequence number of this echo */ WORD smb_bcc; /* minimum value = 4 */ BYTE smb_data[]; /* echo data */ Service: The ECHO protocol is used to test the VC and to see if the server is still responding. It is also used to see if the TID is still valid. When this protocol is used, other requests may be active on the multiplexed VC. The server will respond with the zero or more response protocol messages as requested in smb_reverb. Each response echos the data sent (note - data size may be zero). If smb_reverb is zero, no response will be sent. There is no need for a valid TID field in smb_tid for the success of this protocol (a null TID is defined as 0xFFFF). However, if a TID is present, then the server must check the TID for validity because the consumer may be sending this protocol to see if the TID is still valid. ERRSRV error class and ERRinvnid error code should be set in the protocol response if the TID is invalid. The flow for the ECHO protocol is: consumer ----> ECHO request (data) >------> server consumer <--< ECHO response 1 (data) <----- server consumer <--< ECHO response 2 (data) <----- server . . . consumer <--< ECHO response n (data) <----- server ECHO may generate the following errors. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 33 - November 7, 1988 Error Class ERRDOS Error Class ERRSRV ERRerror ERRnosupport Error Class ERRHRD Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 34 - November 7, 1988 9.2.3. FIND Request Format: (same as core Search Protocol) BYTE smb_wct; /* value = 2 */ WORD smb_count; /* max number of entries to find */ WORD smb_attr; /* search attribute */ WORD smb_bcc; /* minimum value = 5 */ BYTE smb_ident1; /* ASCII (04) */ BYTE smb_pathname[]; /* filename (may contain global characters) */ BYTE smb_ident2; /* Variable Block (05) */ WORD smb_keylen; /* resume key length (zero if "Find First") */ BYTE smb_resumekey[*]; /* "Find Next" key (* = value of smb_keylen) */ Response Format: (same as core Search Protocol) BYTE smb_wct; /* value = 1 */ WORD smb_count; /* number of entries found */ WORD smb_bcc; /* minimum value = 3 */ BYTE smb_ident; /* Variable Block (05) */ WORD smb_datalen; /* data length */ BYTE smb_data[*]; /* directory entries */ Directory Information Entry (dir_info) Format: (same as core Search Protocol) BYTE find_buf_reserved[21]; /* reserved (resume_key) */ BYTE find_buf_attr; /* attribute */ WORD find_buf_time; /* modification time (hhhhh mmmmmm xxxxx) where 'xxxxx' is in two second increments */ WORD find_buf_date; /* modification date (yyyyyyy mmmm ddddd) */ DWORD find_buf_size; /* file size */ BYTE find_buf_pname[13]; /* file name -- ASCII (null terminated) */ The resume_key has the following format: BYTE sr_res; /* reserved: bit 7 - reserved for consumer use bit 5,6 - reserved for system use (must be preserved) bits 0-4 - reserved for server (must be preserved) */ BYTE sr_name[11]; /* pathname sought. Format: 0-3 character extension, left justified (in last 3 chars) */ BYTE sr_findid[1]; /* uniquely identifies find through find close */ BYTE sr_server[4]; /* available for server use (must be non-zero) */ BYTE sr_res[4]; /* reserved for consumer use */ Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 35 - November 7, 1988 Service: The Find protocol finds the directory entry or group of entries matching the specified file pathname. The filename portion of the pathname may contain global (wild card) char- acters. The Find protocol is used to match the find OS/2 system call. The protocols "Find ", "Find Unique" and "Find Close" are methods of reading (or searching) a directory. These protocols may be used in place of the core "Search" protocol when LANMAN 1.0 dialect has been negotiated. There may be cases where the Search protocol will still be used. The format of the Find protocol is the same as the core "Search" protocol. The difference is that the directory is logically Opened with a Find protocol and logically closed with the Find Close protocol. This allows the Server to make better use of its resources. Search buffers are thus held (allowing search resumption via presenting a "resume_key") until a Find Close protocol is received. The sr_findid field of each resume key is a unique identifier (within the session) of the search from "Find" through "Find close". Thus if the consumer does "Find ahead", any find buffers containing resume keys with the matching find id may be released when the Find Close is requested. As is true of a failing open, if a Find request (Find "first" request where resume_key is null) fails (no entries are found), no find close protocol is expected. If no global characters are present, a "Find Unique" proto- col should be used (only one entry is expected and find close need not be sent). The file path name in the request specifies the file to be sought. The attribute field indicates the attributes that the file must have. If the attribute is zero then only nor- mal files are returned. If the system file, hidden or directory attributes are specified then the search is inclusive -- both the specified type(s) of files and normal files are returned. If the volume label attribute is speci- fied then the search is exclusive, and only the volume label entry is returned The max-count field specifies the number of directory entries to be returned. The response will contain zero or more directory entries as determined by the count-returned field. No more than max-count entries will be returned. Only entries that match the sought filename/attribute will be returned. The resume_key field must be null (length = 0) on the ini- tial ("Find First") find request. Subsequent find requests Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 36 - November 7, 1988 intended to continue a search must contain the resume_key field extracted from the last directory entry of the previ- ous response. The resume_key field is self-contained, for on calls containing a resume_key neither the attribute or pathname fields will be valid in the request. A find request will terminate when either the requested maximum number of entries that match the named file are found, or the end of directory is reached without the maximum number of matches being found. A response containing no entries indicates that no matching entries were found between the starting point of the search and the end of directory. There may be multiple matching entries in response to a sin- gle request as Find supports "wild cards" in the file name (last component of the pathname). "?" is the wild card for single characters, "*" or "null" will match any number of filename characters within a single part of the filename component. The filename is divided into two parts -- an eight character name and a three character extension. The name and extension are divided by a ".". If a filename part commences with one or more "?"s then exactly that number of characters will be matched by the Wild Cards, e.g., "??x" will equal "abx" but not "abcx" or "ax". When a filename part has trailing "?"s then it will match the specified number of characters or less, e.g., "x??" will match "xab", "xa" and "x", but not "xabc". If only "?"s are present in the filename part, then it is han- dled as for trailing "?"s "*" or "null" match entire pathname parts, thus "*.abc" or ".abc" will match any file with an extension of "abc". "*.*", "*" or "null" will match all files in a directory. Unprotected servers require the requester to have read per- mission on the subtree containing the directory searched (the share specifies read permission). Protected servers require the requester to have permission to search the specified directory. If a Find requests more data than can be placed in a message of the max-xmit-size for the TID specified, the server will return only the number of entries which will fit. The number of entries returned will be the minimum of: 1. The number of entries requested. 2. The number of (complete) entries that will fit in the negotiated SMB buffer. 3. The number of entries that match the requested name pattern and attributes. The error ERRnofiles set in smb_err field of the response header or a zero value in smb_count of the response Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 37 - November 7, 1988 indicates no matching entry was found. The resume search key returned along with each directory entry is a server defined key which when returned in the Find Next protocol, allows the directory search to be resumed at the directory entry following the one denoted by the resume search key. The date is in the following format: bits: 1111 11 5432 1098 7654 3210 yyyy yyym mmmd dddd where: y - bit of year 0-119 (1980-2099) m - bit of month 1-12 d - bit of day 1-31 The time is in the following format: bits: 1111 11 5432 1098 7654 3210 hhhh hmmm mmmx xxxx where: h - bit of hour (0-23) m - bit of minute (0-59) x - bit of 2 second increment Find may generate the following errors. Error Class ERRDOS ERRnofiles ERRbadpath ERRnoaccess ERRbadaccess ERRbadshare Error Class ERRSRV ERRerror ERRaccess ERRinvnid Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 38 - November 7, 1988 Error Class ERRHRD Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 39 - November 7, 1988 9.2.4. FIND CLOSE Request Format: (same as core Search Protocol - "Find Next" form) BYTE smb_wct; /* value = 2 */ WORD smb_count; /* max number of entries to find */ WORD smb_attr; /* search attribute */ WORD smb_bcc; /* minimum value = 5 */ BYTE smb_ident1; /* ASCII (04) */ BYTE smb_pathname[]; /* null (may contain only null) */ BYTE smb_ident2; /* Variable Block (05) */ WORD smb_keylen; /* resume (close) key length (may not be zero) */ BYTE smb_resumekey[*]; /* "Find Close" key (* = value of smb_keylen) */ Response Format: (same format as core Search Protocol) BYTE smb_wct; /* value = 1 */ WORD smb_reserved; /* reserved */ WORD smb_bcc; /* value = 3 */ BYTE smb_ident; /* Variable Block (05) */ WORD smb_datalen; /* data length (value = 0) */ The resume_key (or close key) has the following format: BYTE sr_res; /* reserved: bit 7 - reserved for consumer use bit 5,6 - reserved for system use (must be preserved) bits 0-4 - rsvd for server (must be preserved by consumer) */ BYTE sr_name[11]; /* pathname sought. Format: 1-8 character file name, left justified 0-3 character extension, left justified (in last 3 chars) */ BYTE sr_findid[1]; /* uniquely identifies find through find close */ BYTE sr_server[4]; /* available for server use (must be non-zero) */ BYTE sr_res[4]; /* reserved for consumer use */ Service: The Find Close protocol closes the association between a Find id returned (in the resume_key) by the Find protocol and the directory search. Whereas the First Find protocol logically opens the direc- tory, subsequent find protocols presenting a resume_key further "read" the directory, the Find Close protocol "closes" the directory allowing the server to free any Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 40 - November 7, 1988 resources held in support of the directory search. The Find Close protocol is used to match the find Close OS/2 system call. The protocols "Find", "Find Unique" and "Find Close" are methods of reading (or searching) a directory. These protocols may be used in place of the core "Search" protocol when LANMAN 1.0 dialect has been negotiated. There may be cases where the Search protocol will still be used. Although only the find id portion the resume key should be required to identify the search being terminated, the entire resume_key as returned in the previous Find (either a "Find First" or "Find Next") is sent to the server in this proto- col. Find Close may generate the following errors. Error Class ERRDOS ERRbadfid Error Class ERRSRV ERRerror ERRinvnid Error Class ERRHRD Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 41 - November 7, 1988 9.2.5. FIND UNIQUE Request Format: (same as core Search Protocol - "Find First" form) BYTE smb_wct; /* value = 2 */ WORD smb_count; /* max number of entries to find */ WORD smb_attr; /* search attribute */ WORD smb_bcc; /* minimum value = 5 */ BYTE smb_ident1; /* ASCII (04) */ BYTE smb_pathname[]; /* filename (may contain global characters) */ BYTE smb_ident2; /* Variable Block (05) */ WORD smb_keylen; /* must be zero ("Find First" only) */ Response Format: (same as core Search Protocol) BYTE smb_wct; /* value = 1 */ WORD smb_count; /* number of entries found */ WORD smb_bcc; /* minimum value = 3 */ BYTE smb_ident; /* Variable Block (05) */ WORD smb_datalen; /* data length */ BYTE smb_data[*]; /* directory entries */ Directory Information Entry (dir_info) Format: (same as core Search Protocol) BYTE find_buf_reserved[21]; /* reserved (resume_key) */ BYTE find_buf_attr; /* attribute */ WORD find_buf_time; /* modification time (hhhhh mmmmmm xxxxx) where 'xxxxx' is in two second increments */ WORD find_buf_date; /* modification date (yyyyyyy mmmm ddddd) */ DWORD find_buf_size; /* file size */ BYTE find_buf_pname[13]; /* file name -- ASCII (null terminated) */ The resume_key has the following format: BYTE sr_res; /* reserved: bit 7 - reserved for consumer use bit 5,6 - reserved for system use (must be preserved) bits 0-4 - rsvd for server (must be preserved by consumer) */ BYTE sr_name[11]; /* pathname sought. Format: 1-8 character file name, left justified 0-3 character extension, left justified (in last 3 chars) */ BYTE sr_findid[1]; /* uniquely identifies find through find close */ BYTE sr_server[4]; /* available for server use (must be non-zero) */ BYTE sr_res[4]; /* reserved for consumer use */ Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 42 - November 7, 1988 Service: The Find Unique protocol finds the directory entry or group of entries matching the specified file pathname. The filename portion of the pathname may contain global (wild card) characters, but the search may not be resumed and no Find Close protocol is expected. The protocols "Find ", "Find Unique" and "Find Close" are methods of reading (or searching) a directory. These proto- cols may be used in place of the core "Search" protocol when LANMAN 1.0 dialect has been negotiated. There may be cases where the Search protocol will still be used. The format of the Find Unique protocol is the same as the core "Search" protocol. The difference is that the direc- tory is logically opened , any matching entries returned, and then the directory is logically closed. This allows the Server to make better use of its resources. No Search buffers are held (search resumption via presenting a "resume_key" will not be allowed). Only one buffer of entries is expected and find close need not be sent). The file path name in the request specifies the file to be sought. The attribute field indicates the attributes that the file must have. If the attribute is zero then only nor- mal files are returned. If the system file, hidden or directory attributes are specified then the search is inclusive -- both the specified type(s) of files and normal files are returned. If the volume label attribute is speci- fied then the search is exclusive, and only the volume label entry is returned The max-count field specifies the number of directory entries to be returned. The response will contain zero or more directory entries as determined by the count-returned field. No more than max-count entries will be returned. Only entries that match the sought filename/attribute will be returned. The resume_key field must be null (length = 0). A Find Unique request will terminate when either the requested maximum number of entries that match the named file are found, or the end of directory is reached without the maximum number of matches being found. A response con- taining no entries indicates that no matching entries were found between the starting point of the search and the end of directory. There may be multiple matching entries in response to a Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 43 - November 7, 1988 single request as Find Unique supports "wild cards" in the file name (last component of the pathname). "?" is the wild card for single characters, "*" or "null" will match any number of filename characters within a single part of the filename component. The filename is divided into two parts -- an eight character name and a three character extension. The name and extension are divided by a ".". If a filename part commences with one or more "?"s then exactly that number of characters will be matched by the Wild Cards, e.g., "??x" will equal "abx" but not "abcx" or "ax". When a filename part has trailing "?"s then it will match the specified number of characters or less, e.g., "x??" will match "xab", "xa" and "x", but not "xabc". If only "?"s are present in the filename part, then it is han- dled as for trailing "?"s "*" or "null" match entire pathname parts, thus "*.abc" or ".abc" will match any file with an extension of "abc". "*.*", "*" or "null" will match all files in a directory. Unprotected servers require the requester to have read per- mission on the subtree containing the directory searched (the share specifies read permission). Protected servers require the requester to have permission to search the specified directory. If a Find Unique requests more data than can be placed in a message of the max-xmit-size for the TID specified, the server will abort the virtual circuit to the consumer. The number of entries returned will be the minimum of: 1. The number of entries requested. 2. The number of (complete) entries that will fit in the negotiated SMB buffer. 3. The number of entries that match the requested name pattern and attributes. The error ERRnofiles set in smb_err field of the response header or a zero value in smb_count of the response indi- cates no matching entry was found. The resume search key returned along with each directory entry is a server defined key. This key will be returned as in the Find protocol and Search protocol however it may NOT be returned to continue the search. The date is in the following format: bits: 1111 11 Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 44 - November 7, 1988 5432 1098 7654 3210 yyyy yyym mmmd dddd where: y - bit of year 0-119 (1980-2099) m - bit of month 1-12 d - bit of day 1-31 The time is in the following format: bits: 1111 11 5432 1098 7654 3210 hhhh hmmm mmmx xxxx where: h - bit of hour (0-23) m - bit of minute (0-59) x - bit of 2 second increment Find Unique may generate the following errors. Error Class ERRDOS ERRnofiles ERRbadpath ERRnoaccess ERRbadaccess ERRbadshare Error Class ERRSRV ERRerror ERRaccess ERRinvnid Error Class ERRHRD Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 45 - November 7, 1988 9.2.6. GET EXPANDED FILE ATTRIBUTES Request Format: BYTE smb_wct; /* value = 1 */ WORD smb_fid; /* file handle */ WORD smb_bcc; /* value = 0 */ Response Format: BYTE smb_wct; /* value = 11 */ WORD smb_cdate; /* date of creation */ WORD smb_ctime; /* time of creation */ WORD smb_adate; /* date of last access */ WORD smb_atime; /* time of last access */ WORD smb_mdate; /* date of last modification */ WORD smb_mtime; /* time of last modification */ DWORD smb_datasize; /* file end of data */ DWORD smb_allocsize; /* file allocation */ WORD smb_attr; /* file attribute */ WORD smb_bcc; /* minimum value = 0 */ BYTE smb_rsvd[]; /* reserved */ Service Enhancement: The Expanded Get File Attributes is enhanced to return more information about the queried file. The current values of the file attributes listed as output parameters are returned to the requester. If a server does not support one of the optional attributes, a null value (hex FFFF) is returned. The file being interrogated is specified by the file handle (FID). The values of the response fields which are for information not requested (via smb_info of the request) are undefined. The attribute field (smb_attr) has the following format (bit0 is the least significant bit). This field matches that used by OS/2. bit0 - read only file bit1 - "hidden" file bit2 - system file bit3 - reserved bit4 - directory bit5 - archive file bits6-15 - reserved (must be zero) Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 46 - November 7, 1988 Note that the volume label bit (as defined in the core pro- tocol) is no longer a valid attribute. The volume label is now returned in the Query Server Information response. The contents of response parameters is not guaranteed in the case of an error return (any protocol response with an error set in the header may have smb_wct of zero and smb_bcc count of zero). The dates are in the following format: bits: 1111 11 5432 1098 7654 3210 yyyy yyym mmmd dddd where: y - bit of year 0-119 (1980-2099) m - bit of month 1-12 d - bit of day 1-31 The times are in the following format: bits: 1111 11 5432 1098 7654 3210 hhhh hmmm mmmx xxxx where: h - bit of hour (0-23) m - bit of minute (0-59) x - bit of 2 second increment Get Expanded file attributes may generate the following errors. Error Class ERRDOS ERRbadfile ERRbadfid Error Class ERRSRV ERRerror ERRinvnid Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 47 - November 7, 1988 Error Class ERRHRD Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 48 - November 7, 1988 9.2.7. IOCTL Primary Request Format: BYTE smb_wct; /* value = 14 */ WORD smb_fid; /* file handle */ WORD smb_cat; /* device category */ WORD smb_fun; /* device function */ WORD smb_tpscnt; /* total number of parameter bytes being sent */ WORD smb_tdscnt; /* total number of data bytes being sent */ WORD smb_mprcnt; /* max number of parameter bytes to return */ WORD smb_mdrcnt; /* max number of data bytes to return */ DWORD smb_timeout; /* number of milliseconds to wait for completion */ WORD smb_rsvd; /* reserved */ WORD smb_pscnt; /* number of parameter bytes being sent this buffer */ WORD smb_psoff; /* offset (from start of SMB hdr) to parameter bytes */ WORD smb_dscnt; /* number of data bytes being sent this buffer */ WORD smb_dsoff; /* offset (from start of SMB hdr) to data bytes */ WORD smb_bcc; /* total bytes (including pad bytes) following */ BYTE smb_pad[]; /* (optional) to pad to word or dword boundary */ BYTE smb_param[*]; /* param bytes (* = value of smb_pscnt) */ BYTE smb_pad1[]; /* (optional) to pad to word or dword boundary */ BYTE smb_data[*]; /* data bytes (* = value of smb_dscnt) */ Interim Response Format (if no error - ok send remaining data): BYTE smb_wct; /* value = 0 */ WORD smb_bcc; /* value = 0 */ Secondary Request Format (more data - may be zero or more of these): BYTE smb_wct; /* value = 8 */ WORD smb_tpscnt; /* total number of parameter bytes being sent */ WORD smb_tdscnt; /* total number of data bytes being sent */ WORD smb_pscnt; /* number of parameter bytes being sent this buffer */ WORD smb_psoff; /* offset (from start of SMB hdr) to parameter bytes */ WORD smb_psdisp; /* byte displacement for these parameter bytes */ WORD smb_dscnt; /* number of data bytes being sent this buffer */ WORD smb_dsoff; /* offset (from start of SMB hdr) to data bytes */ WORD smb_dsdisp; /* byte displacement for these data bytes */ WORD smb_bcc; /* total bytes (including pad bytes) following */ BYTE smb_pad[]; /* (optional) to pad to word or dword boundary */ BYTE smb_param[*]; /* param bytes (* = value of smb_pscnt) */ BYTE smb_pad1[]; /* (optional) to pad to word or dword boundary */ BYTE smb_data[*]; /* data bytes (* = value of smb_dscnt) */ Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 49 - November 7, 1988 Response Format (may respond with one or more of these): BYTE smb_wct; /* value = 8 */ WORD smb_tprcnt; /* total number of parameter bytes being returned */ WORD smb_tdrcnt; /* total number of data bytes being returned */ WORD smb_prcnt; /* number of param bytes being returned this buffer */ WORD smb_proff; /* offset (from start of SMB hdr) to parameter bytes */ WORD smb_prdisp; /* byte displacement for these parameter bytes */ WORD smb_drcnt; /* number of data bytes being returned this buffer */ WORD smb_droff; /* offset (from start of SMB hdr) to data bytes */ WORD smb_drdisp; /* byte displacement for these data bytes */ WORD smb_bcc; /* total bytes (including pad bytes) following */ BYTE smb_pad[]; /* (optional) to pad to word or dword boundary */ BYTE smb_param[*]; /* param bytes (* = value of smb_prcnt) */ BYTE smb_pad1[]; /* (optional) to pad to word or dword boundary */ BYTE smb_data[*]; /* data bytes (* = value of smb_drcnt) */ Service: This function delivers a device/file specific request to a server, and the device/file specific response to the reques- ter. The target file is identified by the file handle in smb_fid. The request defines a function specific to a particular dev- ice type on a particular server type. Therefore the func- tions supported are not defined by the protocol, but by consumer/server implementations. The protocol simply pro- vides a means of delivering them and retrieving the results. Note that the primary request through the final response make up the complete protocol, thus the TID, PID, UID and MID are expected to remain constant and can be used by both the server and consumer to route the individual messages of the protocol to the correct process. The number of bytes needed in order to perform the IOCTL request may be more than will fit in a single buffer. At the time of the request, the consumer knows the number of parameter and data bytes expected to be sent and passes this information to the server via the primary request (smb_tpscnt and smb_tdscnt). This may be reduced by lowering the total number of bytes expected (smb_tpscnt and/or smbtdscnt) in each (any) secondary request. Thus when the amount of parameter bytes received (total of each smb_pscnt) equals the total amount of parameter bytes expected (smallest smb_tpscnt) received, then the server has received all the parameter bytes. Likewise, when the amount of data bytes received (total of each smb_dscnt) equals the total amount of data bytes expected (smallest smb_tdscnt) received, then the server has Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 50 - November 7, 1988 received all the data bytes. The parameter bytes should normally be sent first followed by the data bytes. However, the server knows where each begins and ends in each buffer by the offset fields (smb_psoff and smb_dsoff) and the length fields (smb_pscnt and smb_dscnt). The displacement of the bytes (relative to start of each) is also known (smb_psdisp and smb_dsdisp). Thus the server is able to reasemble the parameter and data bytes should the "packets" (buffers) be received out of sequence. If all parameter bytes and data bytes fit into a single buffer, then no interrum response is expected (and no secon- dary request is sent). The Consumer knows the maximum amount of data bytes and parameter bytes which the server may return (from smb_mprcnt and smb_mdrcnt of the request). Thus it initializes its bytes expected variables to these values. The Server then informs the consumer of the actual amounts being returned via each "packet" (buffer) of the response (smb_tprcnt and smb_tdrcnt). The server may reduce the expected bytes by lowering the total number of bytes expected (smb_tprcnt and/or smb_tdrcnt) in each (any) response. Thus when the amount of parameter bytes received (total of each smb_prcnt) equals the total amount of parameter bytes expected (smallest smb_tprcnt) received, then the consumer has received all the parameter bytes. Likewise, when the amount of data bytes received (total of each smb_drcnt) equals the total amount of data bytes expected (smallest smb_tdrcnt) received, then the consumer has received all the data bytes. The parameter bytes should normally be returned first fol- lowed by the data bytes. However, the consumer knows where each begins and ends in each buffer by the offset fields (smb_proff and smb_droff) and the length fields (smb_prcnt and smb_drcnt). The displacement of the bytes (relative to start of each) is also known (smb_prdisp and smb_drdisp). Thus the consumer is able to reasemble the parameter and data bytes should the "packets" (buffers) be received out of sequence. In the simplest form, a single request is sent and a single response is returned. Thus the flow is: Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 51 - November 7, 1988 1 The consumer sends the first (primary) request which identifies the total bytes (both parameters and data) which are expected to be sent and contains as many of those bytes as will fit in a negotiated size buffer. This request also identifies the maximum number of bytes (both parameters and data) the server will need to return on IOCTL completion. If all the bytes fit in the single buffer, skip to step 4. 2 The server responds with a single interim response meaning "ok, send the remainder of the bytes". 3 The consumer then sends another buffer full of bytes to the server. On each iteration of this secondary request, smb_tpscnt and/or smb_tdscnt could be reduced. This step is repeated until all bytes have been delivered to the server (total of all smb_pscnt equals smallest smb_tpscnt and total of all smb_dscnt equals smallest smb_tdscnt). 4 The Server sets up and performs the IOCTL with the information provided. 5 Upon completion of the IOCTL, the server sends back (up to) the number of parameter and data bytes requested (or as many as will fit in the negotiated buffer size). This step is repeated until all result bytes have been returned. On each iteration of this response, smb_tprcnt and/or smb_tdrcnt could be reduced. This step is repeated until all bytes have been delivered to the consumer (total of all smb_prcnt equals smallest smb_tprcnt and total of all smb_drcnt equals smallest smb_tdrcnt). The flow for the IOCTL protocol when the request parameters and data does NOT all fit in a single buffer is: consumer ----> IOCTL request (data) >-----> server consumer <--< OK send remaining data <---- server consume> IOCTL secondary request 1 (data) > server consume> IOCTL secondary request 2 (data) > server . . . consume> IOCTL secondary request n (data) > server . . . . (server sets up and performs the IOCTL) . . . . consumer <-< IOCTL response 1 (data) <----- server consumer <-< IOCTL response 2 (data) <----- server Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 52 - November 7, 1988 . . . consumer <-< IOCTL response n (data) <----- server The flow for the IOCTL protocol when the request parameters and data does all fit in a single buffer is: consumer ----> IOCTL request (data) >-----> server . . . . (server sets up and performs the IOCTL) . . . . consumer <-< IOCTL response 1 (data) <----- server . (only one if all data fit in buffer) . consumer <-< IOCTL response 2 (data) <----- server . . . consumer <-< IOCTL response n (data) <----- server The first release of LANMAN 1.0 will support only the most simple form of the IOCTL protocol. Only a single request and a single response is expected. Further the maximum number of parameter bytes is limited to 128 bytes and the maximum number of data bytes is limited to 128 bytes on both the request and response IOCTL protocols. This ensures that the request and response will fit within the minimum 1024 byte SMB buffers. The flow for the IOCTL protocol when the request parameters and data does all fit in a single buffer is and the reply parameters and data all fit in a single buffer is: consumer ----> IOCTL request (data) >-----> server . . . . (server sets up and performs the IOCTL) . . . . consumer <--< IOCTL response (data) <------ server IOCTL may generate the following errors. Error Class ERRDOS ERRbadfile ERRbadfid ERRbaddata Error Class ERRSRV ERRerror ERRinvnid Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 53 - November 7, 1988 Error Class ERRHRD Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 54 - November 7, 1988 9.2.8. LOCK and READ Request Format (same as core READ): BYTE smb_wct; /* value = 5 */ WORD smb_fid; /* file handle */ WORD smb_count; /* number of bytes to lock and return */ DWORD smb_offset; /* offset in file to lock and begin read */ WORD smb_remcnt; /* number of bytes remaining to be read */ WORD smb_bcc; /* value = 0 */ Response Format (same as core READ): BYTE smb_wct; /* value = 5 */ WORD smb_count; /* number of locked bytes read */ WORD smb_rsvd[4]; /* reserved (to match size of write request) */ WORD smb_bcc; /* minimum value = 4 */ BYTE smb_ident1; /* value = DATA_BLOCK */ WORD smb_size; /* length of data returned */ BYTE smb_data[]; /* data */ Service: The LockandRead request is used to lock and "read ahead" the specified bytes. The locked portion of a file is "safe" to read ahead because no other process can access the locked bytes until this pro- cess unlocks the bytes. Thus the consumer can assume that the bytes being locked will be read and submit this protocol to both lock and read ahead the bytes. This can provide significant performance improvements on data base update operations (lock data -> read data -> [update -> write data] -> unlock data). Whether or not this protocol is supported (along with Wri- teandUnlock) is returned in the smb_flg field of the nego- tiate response. The request and response format are identical to the core read. The server merely locks the bytes before reading them. If an error occurs on the lock, the bytes should not be read. LockandRead may generate the following errors: Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 55 - November 7, 1988 Error Class ERRDOS: ERRnoaccess ERRbadfid ERRlock ERRbadaccess Error Class ERRSRV: ERRerror ERRinvdevice ERRinvnid Error Class ERRHRD: Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 56 - November 7, 1988 9.2.9. LOCKING and X Request Format: BYTE smb_wct; /* value = 8 */ BYTE smb_com2; /* secondary (X) command, 0xFF = none */ BYTE smb_reh2; /* reserved (must be zero) */ WORD smb_off2; /* offset (from SMB hdr start) to next cmd (@smb_wct) */ WORD smb_fid; /* file handle */ WORD smb_locktype; /* locking mode: bit 0 - 0 = lock out all access, 1 = read ok while locked bit 1 - 1 = single user total file unlock DWORD smb_timeout; /* number of milliseconds to attempt each lock */ WORD smb_unlocknum; /* number of unlock range structures following */ WORD smb_locknum; /* number of lock range structures following */ WORD smb_bcc; /* total bytes following */ struct smb_unlkrng[*]; /* unlock range structures (* = smb_unlocknum) */ struct smb_lockrng[*]; /* lock range structures (* = smb_locknum) */ Unlock Range Structure (smb_unlkrng) Format: WORD smb_lpid; /* pid of process "owning" the lock */ DWORD smb_unlockoff; /* file offset to bytes to be unlocked */ DWORD smb_unlocklen; /* number of bytes to be unlocked */ Lock Range Structure (smb_lockrng) Format: WORD smb_lpid; /* pid of process "owning" the lock */ DWORD smb_lockoff; /* file offset to bytes to be locked */ DWORD smb_locklen; /* number of bytes to be locked */ Response Format: BYTE smb_wct; /* value = 2 */ BYTE smb_com2; /* secondary (X) command, 0xFF = none */ BYTE smb_res2; /* reserved (pad to word) */ WORD smb_off2; /* offset (from SMB hdr start) to next cmd (@smb_wct) */ WORD smb_bcc; /* value = 0 */ Service Enhancement: This protocol allows both locking and/or unlocking of file range(s). If unlocking is specified (smb_unlocknum non-zero), the Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 57 - November 7, 1988 number of bytes specified by smb_unlocklen at the file offset specified by smb_unlockoff will be unlocked for each unlock range. Then if locking is specified (smb_locknum non-zero), the number of bytes specified by smb_locklen at the file offset specified by smb_lockoff will be locked for each lock range. The time specified by smb_timeout is the maximum amount of time to wait for the byte range(s) specified to become unlocked (so that they can be locked by this protocol). A timeout value of 0 indicates that this protocol should fail immediately if any lock range specified is locked. A timeout value of -1 indicates that the server should wait as long as it takes for each byte range specified to become unlocked so that it may be again locked by this protocol. Any other value of smb_timeout specifies the maximum number of milliseconds to wait for all lock range(s) specified to become available. If any of the lock ranges timeout because of the area to be locked is already locked (or the lock fails), the other ranges in the protocol request which were successfully locked as a result of this protocol will be unlocked (either all requested ranges will be locked when this protocol returns to the consumer or none). If smb_locktype is 1, the lock is specified as a "read only" lock. Locks for both read and write (where smb_locktype is 0) should be prohibited, but other "read only" locks should be permitted. If this mode can not be supported on a given server, the smb_locktype field should always be treated as 0 in that any lock attempt will fail if the byte range speci- fied is locked. Closing a file with locks still in force causes the locks to be released in no defined order. Locking is a simple mechanism for excluding other processes read/write access to regions of a file. The locked regions can be anywhere in the logical file. Locking beyond end- of-file is NOT an error. Any process using the FID speci- fied in smb_fid has access to the locked bytes, other processes will be denied the locking of the same bytes. The proper method for using locks is not to rely on being denied read or write access on any of the read/write proto- cols but rather to attempt the locking protocol and proceed with the read/write only if the lock succeeded. Locking a range of bytes will fail if any subranges or over- lapping ranges are locked. In other words, if any of the specified bytes are already locked, the lock will fail. The time which a byte range is locked should be kept as Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 58 - November 7, 1988 short as possible. The entire message sent and received including the optional second protocol must fit in the negotiated max transfer size. NOTE - LANMAN 1.0 does not support smb_locktype where bit 1 is set (read ok while locked) also smb_timeout is ignored and treated as if it were set to zero. The following are the only valid protocol requests commands for smb_com2 (X) for LOCKING and X: READ READ and X A "single user total file lock" is also known as an "oppor- tunistic lock". A consumer requests an "opportunistic lock" by setting the appropriate bit in the OpenX, Open, Create and MakeNew protocols whenever the file is being opened in a mode which is not exclusive. The server responds by setting the appropriate bit in the response protocol indicating whether or not the "opportunistic lock" was granted. By granting the "oplock", the server tells the consumer that the file is currently ONLY being used by this one consumer process at the current time. The consumer can therefore safely do read ahead and write behind as well as local cach- ing of file locks knowing that the file will not be accessed/changed in any way by another process while the "oplock" is in effect. The consumer will be notified when any other process attempts to open the "oplocked" file and if "opbatch" (bit 2 of smb_flags) was set on the OpenX request, the consumer will also be notified on any operation which may change the file. When another user attempts to Open (or otherwise modify if "opbatch" was requested) the file which a consumer has oplocked, the server will "hold off" the 2nd attempt and notify the consumer via a LockingX protocol (with bit one of smb_locktype set) that the "oplock" is being broken. The consumer is expected to then flush any dirty buffers, submit any file locks (LockingX protocol can be used for this) and respond to the server with either a LockingX protocol (with bit one of smb_locktype set) or with a close protocol if the file is no longer in use. Note that because a close being sent to the server and break oplock notification from the server could cross on the wire, if the consumer gets an oplock notification on a file which it does not have open, that notification should be ignored. Once the "oplock" has been broken, the consumer must no longer do any form of data or lock caching. The "oplock" is never reenstated while the Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 59 - November 7, 1988 file is open. If the file is still open once the consumer has been notified, the 2nd opener does not get the file "oplocked" along with the open. If the file is closed by the consumer which had it open, the server is again free to grant the new opener the oplock. Note that the "oplock" broken notification will only go to one consumer because after the oplock is broken, any further open attempts will just get the oplock request denied. Also note that due to timing, the consumer could get an "oplock" broken notification in a user's data buffer as a result of this notification crossing on the wire with a Read Raw request. The consumer must detect this (use length of msg, "FFSMB", MID of -1 and smb_cmd of SMBLockingX) and honor the "oplock" broken notification as usual. The server must also note on receipt of an Read Raw request that there is an outstanding (unanswered) "oplock" broken notification to the consumer and return a zero length response denoting failure of the read raw request. The consumer should (after responding to the "oplock" broken notification), use a stan- dard read protocol to redo the read request. This allows a file to actually contain data matching an "oplock" broken notification and still be read correctly. "Oplock" is a major performance win in the real world because many files must be opened in a non exclusive mode because the file could be used by others. However often, the files are not actually in use by multiple users at the same instant. Locking and X may generate the following errors. Error Class ERRDOS ERRbadfile ERRbadfid ERRlock Error Class ERRSRV ERRerror ERRinvdevice ERRinvnid Error Class ERRHRD Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 60 - November 7, 1988 9.2.10. MOVE Request Format: BYTE smb_wct; /* value = 3 */ WORD smb_tid2; /* second (destination) path tid */ WORD smb_ofun; /* what to do if destination file exists */ WORD smb_flags; /* flags to control move operations: bit 0 - destination must be a file. bit 1 - destination must be a directory. bit 2 - reserved (must be zero) bit 3 - reserved (must be zero) bit 4 - verify all writes. WORD smb_bcc; /* minimum value = 2 */ BYTE smb_path[]; /* pathname of source file */ BYTE smb_new_path[]; /* pathname of destination file */ Response Format: BYTE smb_wct; /* value = 1 */ WORD smb_cct; /* number of files moved */ WORD smb_bcc; /* minimum value = 0 */ BYTE smb_errfile[]; /* pathname of file where error occured - ASCIIZ */ Service: The file referenced by smb_path (source) is copied to smb_new_path (destination), then the file referenced by smb_path (source) is deleted. Both smb_path and smb_new_path must refer to paths on the server. The server must do any necessary access permission checks on both the source and the destination paths. The TID in smb_tid of the header is associated with the source while smb_tid2 is associated with the destination. These TID fields may contain the same or differing valid TIDs. Note that smb_tid2 can be set to -1 indicating that this is to be the same TID as the TID in smb_tid of the header. This allows use of the move protocol with TCONandX. The source path must refer to an existing file or files. Wild Cards are permitted. Source files specified by Wild Cards are processed until an error is encountered. If an error is encountered, the expanded name of the file is returned in smb_errfile. The error code is returned in smb_err. The destination path can refer to either a file or a direc- tory. The destination can be required to be a file or a directory by smb_flags bits. If neither bit is set, the destination may be either a file or a directory. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 61 - November 7, 1988 Wild Cards are not permitted in the destination path. smb_ofun bit field mapping: bits: 1111 11 5432 1098 7654 3210 rrrr rrrr rrrr rrOO where: O - Open (action to be taken if destination file exists). 0 - Fail. 1 - reserved. 2 - Truncate file. r - reserved (must be zero). If target file does not exist, it will be created. All file components except the last must exist (directories will not be created). Move may generate the following errors. Error Class ERRDOS ERRbadfile ERRbadpath ERRfileexists ERRnoaccess ERRnofiles ERRbadshare Error Class ERRSRV ERRerror ERRinvnid ERRnosupport ERRaccess Error Class ERRHRD Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 62 - November 7, 1988 9.2.11. OPEN and X Request Format: BYTE smb_wct; /* value = 15 */ BYTE smb_com2; /* secondary (X) command, 0xFF = none */ BYTE smb_reh2; /* reserved (must be zero) */ WORD smb_off2; /* offset (from SMB hdr start) to next cmd (@smb_wct) */ WORD smb_flags; /* additional information: bit 0 - if set, return additional information bit 1 - if set, set single user total file lock (if only access) bit 2 - if set, the server should notify the consumer on any action which can modify the file (delete, setattrib, rename, etc.). if not set, the server need only notify the consumer on another open request. This bit only has meaning if bit 1 is set. */ WORD smb_mode; /* file open mode */ WORD smb_sattr; /* search attributes */ WORD smb_attr; /* file attributes (for create) */ DWORD smb_time; /* create time */ WORD smb_ofun; /* open function */ DWORD smb_size; /* bytes to reserve on "create" or "truncate" */ DWORD smb_timeout; /* max milliseconds to wait for resource to open */ DWORD smb_rsvd; /* reserved (must be zero) */ WORD smb_bcc; /* minimum value = 1 */ BYTE smb_pathname[]; /* file pathname */ Response Format: BYTE smb_wct; /* value = 15 */ BYTE smb_com2; /* secondary (X) command, 0xFF = none */ BYTE smb_res2; /* reserved (pad to word) */ WORD smb_off2; /* offset (from SMB hdr start) to next cmd (@smb_wct) */ WORD smb_fid; /* file handle */ + WORD smb_attribute; /* attributes of file or device */ +DWORD smb_time; /* last modification time */ +DWORD smb_size; /* current file size */ + WORD smb_access; /* access permissions actually allowed */ + WORD smb_type; /* file type */ + WORD smb_state; /* state of IPC device (e.g. pipe) */ WORD smb_action; /* action taken */ DWORD smb_fileid; /* server unique file id */ WORD smb_rsvd; /* reserved */ WORD smb_bcc; /* value = 0 */ + returned only if bit 0 of smb_flags is set in request Service Enhancement: The open protocol request is enhanced in order to accommo- date the new open system call used in OS/2 and provide addi- tional functionality. Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 63 - November 7, 1988 The entire message sent and received including the optional second protocol must fit in the negotiated max transfer size. The following are the only valid protocol requests commands for smb_com2 (X) for OPEN and X: READ READ and X IOCTL The "mode" field for open, referenced as r/w/share in the core protocol document, is enhanced to allow direct access mode for the file, and to allow an open for execute. Sys- tems that do not support execute mode should treat the exe- cute mode as equivalent to read mode. This word has the fol- lowing format: smb_mode bit field mapping: bits: 1111 11 5432 1098 7654 3210 rWrr rrrr rSSS rAAA where: W - Write through mode. No read ahead or write behind allowed on this file (or device). When protocol is returned, data is expected to be on the disk (or device). r - reserved (must be zero). SSS - Sharing mode 0 -- Compatibility mode (as in core open protocol) 1 -- Deny read/write/execute (exclusive). 2 -- Deny write. 3 -- Deny read/execute. 4 -- Deny none. AAA - Access mode 0 -- Open for reading. 1 -- Open for writing. 2 -- Open for reading and writing. 3 -- Open for execute rSSSrAAA = 11111111 (hex FF) indicates FCB open (as in core open protocol) The "open function" field specifies the action to be taken depending on whether or not the file exists. This word has Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 64 - November 7, 1988 the following format: smb_ofun bit field mapping: bits: 1111 11 5432 1098 7654 3210 rrrr rrrr rrrC rrOO where: C - Create (action to be taken if file does not exist). 0 -- Fail. 1 -- Create file. r - reserved (must be zero). O - Open (action to be taken if file exists). 0 - Fail. 1 - Open file. 2 - Truncate file. I/O devices can be opened in a queuing mode, in that if the device (or all devices of type requested) is currently in use the user may optionally queue waiting for the device to become free. Thus a non zero smb_timeout field is used to indicate that queuing is desired. If queuing is requested, the value in the smb_timeout field is used as the maximum number of milliseconds to wait for the device to become free. A value of zero means no delay (do not queue), a value of (long) -1 indicates to wait for- ever (no timeout). The server will not send the response back to the consumer until the resource being queued for is actually opened (or the specified timeout time has passed). Note that although the timeout is specified in milliseconds (in order to match the OS/2 system calls), by the time that the timeout occurs and the consumer receives the timeout protocol much more time than specified may have occurred. The "Action Taken" field specifies the action as a result of the Open request. This word has the following format: smb_action bit field mapping: bits: 1111 11 5432 1098 7654 3210 Lrrr rrrr rrrr rrOO Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 65 - November 7, 1988 where: L - Lock (single user total file lock status). 0 -- file opened by another user (or mode not sup- ported by server). 1 -- file is opened only by this user at the present time. r - reserved (must be zero). O - Open (action taken on Open). 1 - The file existed and was opened. 2 - The file did not exist but was created. 3 - The file existed and was truncated. The attribute fields (smb_attr, smb_sattr and smb_attribute) have the following format (bit0 is the least significant bit). This field matches that used by OS/2. bit0 - read only file bit1 - "hidden" file bit2 - system file bit3 - reserved bit4 - directory bit5 - archive file bits6-15 - reserved (must be zero) The search attribute field (smb_sattr) indicates the attri- butes that the file must have to be found while searching to see if it exists. If the search attribute is zero then only normal files are returned. If the system file, hidden or directory attributes are specified then the search is inclusive -- both the specified type(s) of files and normal files are returned. The resource type field (smb_type) defines the additional resource types: 0 - Disk file or directory as defined in the attribute field. 1 - FIFO (named pipe) 2 - Named pipe (message mode) 3 - LPT (printer) Device 4 - COM (communication) Device Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 66 - November 7, 1988 IPC State Bits (smb_state) 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 B E * * T T R R |--- Icount --| where: B - Blocking - 0 => reads/writes block if no data available 1 => reads/writes return immediately if no data E - Endpoint - 0 => consumer end of pipe 1 => server end of pipe TT - Type of pipe - 00 => pipe is a byte stream pipe 01 => pipe is a message pipe RR - Read Mode - 00 => Read pipe as a byte stream 01 => Read messages from pipe Icount - 8-bit count to control pipe instancing (N/A) A "single user total file lock" is also known as an "oppor- tunistic lock". A consumer requests an "opportunistic lock" by setting the appropriate bit in the OpenX, Open, Create and MakeNew protocols whenever the file is being opened in a mode which is not exclusive. The server responds by setting the appropriate bit in the response protocol indicating whether or not the "opportunistic lock" was granted. By granting the "oplock", the server tells the consumer that the file is currently ONLY being used by this one consumer process at the current time. The consumer can therefore safely do read ahead and write behind as well as local cach- ing of file locks knowing that the file will not be accessed/changed in any way by another process while the "oplock" is in effect. The consumer will be notified when any other process attempts to open the "oplocked" file and if "opbatch" (bit 2 of smb_flags) was set on the OpenX request, the consumer will also be notified on any operation which may change the file. When another user attempts to Open (or otherwise modify if "opbatch" was requested) the file which a consumer has oplocked, the server will "hold off" the 2nd attempt and notify the consumer via a LockingX protocol (with bit one of smb_locktype set) that the "oplock" is being broken. The consumer is expected to then flush any dirty buffers, submit any file locks (LockingX protocol can be used for this) and respond to the server with either a LockingX protocol (with Copyright Microsoft Corporation, 1987, 198Microsoft Networks SMB Protocol Extensions - 67 - November 7, 1988 bit one of smb_locktype set) or with a close protocol if the file is no longer in use. Note that because a close being sent to the server and break oplock notification from the server could cross on the wire, if the consumer gets an oplock notification on a file which it does not have open, that notification should be ignored. Once the "oplock" has been broken, the consumer must no longer do any form of data or lock caching. The "oplock" is never reenstated while the file is open. If the file is still open once the consumer has been notified, the 2nd opener does not get the file "oplocked" along with the open. If the file is closed by the consumer which had it open, the server is again free to grant the new opener the oplock. Note that the "oplock" broken notification will only go to one consumer because after the oplock is broken, any further open attempts will just get the oplock request denied. Also note that due to timing, the consumer could get an "oplock" broken notification in a user's data buffer as a result of this notification crossing on the wire with a Read Raw request. The consumer must detect this (use length of msg, "FFSMB", MID of -1 and smb_cmd of SMBLockingX) and honor the "oplock" broken notification as usual. The server must also note on receipt of an Read Raw request that there is an outstanding (unanswered) "oplock" broken notification to the consumer and return a zero length response denoting failure of the read raw request. The consumer should (after responding to the "oplock" broken notification), use a stan- dard read protocol to redo the read request. This allows a file to actually contain data matching an "oplock" broken notification and still be read correctly. "Oplock" is a major performance win in the real world because many files must be opened in a non exclusive mode because the file could be used by others. However often, the files are not actually in use by multiple users at the same instant. The following errors may be generated by Open and X. Error Class ERRDOS ERRbadfile ERRnofids ERRnoaccess ERRshare ERRbadaccess Copyright Microsoft Corporation, 1987, 198Mic