Implementing CIFS: The Common Internet File System
| Clients exchange messages with a server to access resources on that server. These messages are called Server Message Blocks (SMBs), and every SMB message has a common format. This section describes the entire set of SMB commands and responses exchanged between CIFS clients and servers. It also details which SMBs are introduced into the protocol as higher dialect levels are negotiated. 3.1 Notation
This document makes use of "C"-like notation to describe the formats of messages. Unlike the "C" language, which allows for implementation flexibility in laying out structures, this document adopts the following rules. Multi-byte values are always transmitted least significant byte first. All fields, except " bit-fields ", are aligned on the nearest byte boundary (even if longer than a byte), and there is no implicit padding. Fields using the "bit field" notation are defined to be laid out within the structure with the first-named field occupying the lowest order bits, the next named field the next lowest order bits, and so on. BOOLEAN is defined to be a single byte. The SHORT and LONG types are little endian. 3.2 SMB header
While each SMB command has specific encodings, there are some fields in the SMB header, which have meaning to all SMBs. These fields and considerations are described in the following sections. typedef unsigned char UCHAR; // 8 unsigned bits typedef unsigned short USHORT; // 16 unsigned bits typedef unsigned long ULONG; // 32 unsigned bits typedef struct { ULONG LowPart; LONG HighPart; } LARGE_INTEGER; // 64 bits of data typedef struct { UCHAR Protocol[4]; // Contains 0xFF,'SMB' UCHAR Command; // Command code union { struct { UCHAR ErrorClass; // Error class UCHAR Reserved; // Reserved for future use USHORT Error; // Error code } DosError; ULONG Status; // 32-bit error code } Status; UCHAR Flags; // Flags USHORT Flags2; // More flags union { USHORT Pad[6]; // Ensure section is 12 bytes long struct { USHORT PidHigh; // High Part of PID UCHAR SecuritySignature[8]; // reserved for MAC } Extra; }; USHORT Tid; // Tree identifier USHORT Pid; // Caller's process ID, opaque for client use USHORT Uid; // User id USHORT Mid; // multiplex id UCHAR WordCount; // Count of parameter words USHORT ParameterWords[WordCount]; // The parameter words USHORT ByteCount; // Count of bytes UCHAR Buffer[ByteCount]; // The bytes } SMB_HEADER; All SMBs in this document have an identical format up to the ParameterWords field. (However, this is not true for some obsolescent SMBs.) For the last fields in the header, different SMBs have a different number and interpretation of the ParameterWords and Buffer fields. All reserved fields in the SMB header must be zero. 3.2.1 Command field
The Command is the operation code that this SMB is requesting or responding to. See section 5.1 below for number values, and section 4 for a description of each operation. 3.2.2 Flags field
This field contains 8 individual flags, numbered from least significant bit to most significant bit, which are defined below. Flags that are not defined MUST be set to zero by clients and MUST be ignored by servers.
3.2.3 Flags2 Field
This field contains nine individual flags, numbered from least significant bit to most significant bit, which are defined below. Flags that are not defined MUST be set to zero by clients and MUST be ignored by servers.
3.2.4 Tid Field
Tid represents an instance of an authenticated connection to a server resource. The server returns Tid to the client when the client successfully connects to a resource, and the client uses Tid in subsequent requests referring to the resource. In most SMB requests, Tid must contain a valid value. Exceptions are those used prior to getting a Tid established, including SMB_COM_NEGOTIATE, SMB_COM_TREE_CONNECT_ANDX, SMB_COM_ECHO, and SMB_COM_SESSION_SETUP_ANDX. 0xFFFF should be used for Tid for these situations. The server is always responsible for enforcing use of a valid Tid where appropriate. On SMB_COM_TREE_DISCONNECT over a given transport connection, with a given Tid, the server will close any files opened with that Tid over that connection. 3.2.5 Pid Field
Pid is the caller's process id, and is generated by the client to uniquely identify a process within the client computer. Concurrency control is associated with Pid (and PidHigh)sharing modes, and locks are arbitrated using the Pid. For example, if a file is successfully opened for exclusive access, subsequent opens from other clients or from the same client with a different Pid will be refused . Clients inform servers of the creation of a new process by simply introducing a new Pid value into the dialogue for new processes. The client operating system must ensure that the appropriate close and cleanup SMBs will be sent when the last process referencing a 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 transport connection and Tid. It is up to the client operating system to ensure that only authorized client processes gain access to Fids (and Tids). On SMB_COM_TREE_DISCONNECT (or when the client and server session is terminated ) with a given Tid, the server will invalidate any files opened by any process on that client.tid Field 3.2.6 Uid Field
Uid is a reference number assigned by the server after a user authenticates to it, and that it will associate with that user until the client requests the association be broken. After authentication to the server, the client SHOULD make sure that the Uid is not used for a different user that the one that authenticated. (It is permitted for a single user to have more than one Uid.) Requests that do authorization, such as open requests, will perform access checks using the identity associated with the Uid. 3.2.7 Mid Field
The multiplex ID (Mid) is used along with the Pid to allow multiplexing the single client and server connection among the client's multiple processes, threads, and requests per thread. Clients may have many outstanding requests (up to the negotiated number, MaxMpxCount) at one time. Servers MAY respond to requests in any order, but a response message MUST always contain the same Mid and Pid values as the corresponding request message. The client MUST NOT have multiple outstanding requests to a server with the same Mid and Pid. 3.2.8 Status Field
An SMB returns error information to the client in the Status field. Protocol dialects prior to NT LM 0.12 return status to the client using the combination of Status.DosError.ErrorClass and Status.DosError.Error. Beginning with NT LM 0.12 CIFS servers can return 32 bit error information to clients using Status.Status if the incoming client SMB has bit 14 set in the Flags2 field of the SMB header. The contents of response parameters are not guaranteed in the case of an error return, and must be ignored. For write-behind activity, a subsequent write or close of the file may return the fact that a previous write failed. Normally write-behind failures are limited to hard disk errors and device out of space. 3.2.9 Timeouts
In general, SMBs are not expected to block at the server; they should return "immediately". There are however a series of operations which may block for a significant time. The most obvious of these is named-pipe operations, which may be dependent on another application completing a write before they can fully complete their read. (Most named-pipe operations are never expired unless cancelled). Similarly, with byte-range locking, the Timeout period is specified by the client, so the server is not responsible for blocking on this operation as long as the client has specified it may. A SMB server should put forth its best effort to handle operations as they arrive in an efficient manner, such that clients do not timeout operations believing the server to be unresponsive falsely. A client may timeout a pending operation by terminating the session. 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. 3.2.10 Data Buffer (BUFFER) and String Formats
The data portion of SMBs typically contains the data to be read or written, file paths, or directory paths. The format of the data portion depends on the message. All fields in the data portion have the same format. In every case it consists of an identifier byte followed by the data.
When the identifier indicates a data block or variable block then the format is a word indicating the length followed by the data. In all dialects prior to NT LM 0.12, all strings are encoded in ASCII. If the agreed dialect is NT LM 0.12 or later, Unicode strings may be exchanged. Unicode strings include file names, resource names, and user names. This applies to null-terminated strings, length specified strings and the type-prefixed strings. In all cases where a string is passed in Unicode format, the Unicode string must be word-aligned with respect to the beginning of the SMB. Should the string not naturally fall on a two-byte boundary, a null byte of padding will be inserted, and the Unicode string will begin at the next address. In the description of the SMBs, items that may be encoded in Unicode or ASCII are labeled as STRING. If the encoding is ASCII, even if the negotiated string is Unicode, the quantity is labeled as UCHAR. For type-prefixed Unicode strings, the padding byte is found after the type byte. The type byte is 4 (indicating SMB_FORMAT_ASCII) independent of whether the string is ASCII or Unicode. For strings whose start addresses are found using offsets within the fixed part of the SMB (as opposed to simply being found at the byte following the preceding field,) it is guaranteed that the offset will be properly aligned. Strings that are never passed in Unicode are:
When Unicode is negotiated, the SMB_FLAGS2_UNICODE bit should be set in the Flags2 field of every SMB header. Despite the flexible encoding scheme, no field of a data portion may be omitted or included out of order. In addition, neither a WordCount nor ByteCount of value 0 at the end of a message may be omitted. 3.3 Name Restrictions
The following four reserved characters MUST not be used in share names (network names), user names, group names or domain names. "\", "/", "?", "*" The following ten characters SHOULD not be used in share names, user names, group names or domain names as they are considered reserved by multiple existing implementations : "[", "]", ":", ";", "", "=", ",", "+", "<", ">" A share name or server or workstation name SHOULD not begin with a period (" . ") nor should it include two adjacent periods (" .. "). The same naming considerations apply for RFC 1001 names for servers or workstations when using Netbios over TCP/IP name resolution mechanisms. 3.4 File Names
File names in the CIFS protocol consist of components separated by a backslash (' \ '). Early clients of the CIFS protocol required that the name components adhere to an 8.3 format name. These names consist of two parts : a basename of no more than 8 characters, and an extension of no more than 3 characters. The basename and extension are separated by a ' . '. All characters are legal in the basename and extension except the space character (0x20) and: "'", ".", "/", "\", "[", "]", ":", "+", "", "<", ">", "=", ";", ",", "*", "?" If the client has indicated long name support by setting bit2 in the Flags2 field of the SMB header, this indicates that the client is not bound by the 8.3 convention. Specifically this indicates that any SMB which returns file names to the client may return names which do not adhere to the 8.3 convention, and have a total length of up to 255 characters. This capability was introduced with the LM1.2X002 protocol dialect. The two special path components "." and ".." MUST be recognized. They indicate the current directory and the parent directory respectively. Although the use of ".." permits the specification of resources "above" the root of the tree connection, servers SHOULD prevent access to files or directories above the root of the exported share. 3.5 Wildcards
Some SMB requests allow wildcards to be given for the filename. The wildcard allows a number of files to be operated on as a unit without having to separately enumerate the files and individually operate on each one from the client. Two different sets of search semantics are supported. DOS search semantics are used for searching by 8.3 (or short names). Normal search semantics are used for searching by long names (those which support file names different from 8.3). In the 8.3 naming scheme, each file name can contain up to 8 characters, a dot, and up to 3 trailing characters. Each part of the name (base (8) or extension (3)) is treated separately. The " * ", the " ? " and the " . " can be used as wildcards. The " * " matches 0 or more characters until encountering and matching the " . " in the name. The " ? " matches any single character, or upon encountering a " . " or end of name string, advances the expression to the end of the set of contiguous " ? "s. So if the filename part commences with one or more " ? "s then exactly that number of characters will be matched by the wildcards, e.g., " ??x " equals " abx " but not " abcx " or " ax ". When a filename part has trailing " ? "s then it matches the specified number of characters or less, e.g., " x?? " matches " xab ", " xa " and " x ", but not " xabc ". If only " ? "s are present in the filename part, then it is handled as for trailing " ? "s. Finally, the " . " Matches either a " . " or an empty extension string. In the normal naming scheme, the " . " In the name is significant even though there is no longer a restriction on the size of each of the file name components. A file name may have none, one or more than one " . "s within its name. Spaces " " are also allowed within file names and both follow normal wildcard searching rules. For example, if the files " foo bar none " and " foo.bar.none " exist, the pattern " foo* " equals both, " foo.* " equals " foo.bar.none " and " foo * " equals " foo bar none ". The ? character is a wildcard for a single character. If the match pattern commences with one or more "?"s then exactly that number of characters will be matched by the wildcards, e.g., "??x" equals "abx" but not "abcx" or "ax". When a match pattern has trailing "?"s then it matches the specified number of characters or less, e.g., "x??" matches "xab", "xa" and "x", but not "xabc". If only "?"s are present in the match pattern, then it is handled as for trailing "?"s. The * character matches an entire name. For example, " * " matches all files in a directory. If the negotiated dialect is "NT LM 0.12" or later, and the client requires MS-DOS wildcard matching semantics, UNICODE wildcards should be translated according to the following rules:
The translation can be performed in-place. 3.6 DFS Pathnames
A DFS pathname adheres to the standard described in the FileNames section. A DFS enabled client accessing a DFS share should set the Flags2 bit 12 in all name based SMB requests indicating to the server that the enclosed pathname should be resolved in the Distributed File System namespace. The pathname should always have the full file name, including the server name and share name. If the server can resolve the DFS name to a piece of local storage, the local storage will be accessed. If the server determines that the DFS name actually maps to a different server share, the access to the name will fail with the 32-bit status STATUS_PATH_NOT_COVERED (0xC0000257), or DOS error ERRsrv/ERRbadpath. On receiving this error, the DFS enabled client should ask the server for a referral (see TRANS2_GET_DFS_REFERRAL). The referral request should contain the full file name. The response to the request will contain a list of server and share names to try, and the part of the request file name that junctions to the list of server shares. If the ServerType field of the referral is set to 1 (SMB server), then the client should resubmit the request with the original file name to one of the server shares in the list, once again setting the Flags2 bit 12 bit in the SMB. If the ServerType field is not 1, then the client should strip off the part of the file name that junctions to the server share before resubmitting the request to one of servers in the list. A response to a referral request may elicit a response that does not have the StorageServers bit set. In that case, the client should resubmit the referral request to one of the servers in the list, until it finally obtains a referral response that has the StorageServers bit set, at which point the client can resubmit the request SMB to one of the listed server shares. If, after getting a referral with the StorageServers bit set and resubmitting the request to one of the server shares in the list, the server fails the request with STATUS_PATH_NOT_COVERED, it must be the case that there is an inconsistency between the view of the DFS namespace held by the server granting the referral and the server listed in that referral. In this case, the client may inform the server granting the referral of this inconsistency via the TRANS2_REPORT_DFS_INCONSISTENCY SMB. 3.7 Time And Date Encoding
When SMB requests or responses encode time values, the following describes the various encodings used. struct { USHORT Day : 5; USHORT Month : 4; USHORT Year : 7; } SMB_DATE; The Year field has a range of 0-119, which represents years 1980 - 2099. The Month is encoded as 1-12, and the day ranges from 1-31. struct { USHORT TwoSeconds : 5; USHORT Minutes : 6; USHORT Hours : 5; } SMB_TIME; Hours ranges from 0-23, Minutes range from 0-59, and TwoSeconds ranges from 0-29 representing two second increments within the minute. typedef struct { ULONG LowTime; LONG HighTime; } TIME; TIME indicates a signed 64-bit integer representing either an absolute time or a time interval. Times are specified in units of 100ns. A positive value expresses an absolute time. The time base (the 64-bit integer with value 0) is the beginning of the year 1601 AD in the Gregorian calendar UTC. However, file creation, modification and access times include an additional correction factor as follows : Tf = Tutc + Tdaf - Tdan Where Tf time reported for file creation/modification/deletion Tutc UTC time (secs since 1601 AD) Tdaf Daylight savings adjustment (positive quantity) in effect at Tf Tdan Current daylight savings adjustment (positive quantity) For example, if a file is created in the summer - when daylight savings time is in effect - the creation time will be reported as Summer: Tutc + 3600 - 3600 = Tutc Winter: Tutc + 3600 - 0 = Tutc + 3600 If a file is created during the winter - when daylight savings time not in effect - the creation time will be reported as: Summer: Tutc + 0 - 3600 = Tutc - 3600 Winter: Tutc + 0 - 0 = Tutc A negative value expresses a time interval relative to some base time, usually the current time. typedef unsigned long UTIME; UTIME is the number of seconds since Jan 1, 1970, 00:00:00.0. 3.8 Access Mode Encoding
Various client requests and server responses, such as SMB_COM_OPEN, pass file access modes encoded into a USHORT. The encoding of these is as follows: 1111 11 5432 1098 7654 3210 rWrC rLLL rSSS rAAA where: W - Write through mode. No read ahead or write behind allowed on this file or device. When the response is returned, data is expected to be on the disk or device. S - Sharing mode: 0 - Compatibility mode 1 - Deny read/write/execute (exclusive) 2 - Deny write 3 - Deny read/execute 4 - Deny none A - 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 (???) C - Cache mode 0 - Normal file 1 - Do not cache this file L - Locality of reference 0 - Locality of reference is unknown 1 - Mainly sequential access 2 - Mainly random access 3 - Random access with some locality 4 to 7 - Currently undefined 3.9 Access Mask Encoding
The ACCESS_MASK structure is one 32-bit value containing standard, specific, and generic rights. These rights are used in access-control entries (ACEs) and are the primary means of specifying the requested or granted access to an object. The bits in this value are allocated as follows: Bits 0-15 contain the access mask specific to the object type associated with the mask. Bits 16-23 contain the object's standard access rights and can be a combination of the following predefined flags:
3.10 Open Function Encoding
OpenFunction specifies the action to be taken depending on whether or not the file exists. This word has the following format: 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 3.11 Open Action Encoding
Action in the response to an open or create request describes the action taken as a result of the request. It has the following format: 1111 11 5432 1098 7654 3210 Lrrr rrrr rrrr rrOO where: L - Lock (single user total file lock status) 0 -- file opened by another user (or mode not supported 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 3.12 File Attribute Encoding
When SMB messages exchange file attribute information, it is encoded in 16 bits as:
3.13 Extended File Attribute Encoding
The extended file attributes is a 32 bit value composed of attributes and flags. Any combination of the following attributes is acceptable, except all other file attributes override FILE_ATTR_NORMAL:
Any combination of the following flags is acceptable:
3.14 Batching Requests ("AndX" Messages)
LANMAN1.0 and later dialects of the CIFS protocol allow multiple SMB requests to be sent in one message to the server. Messages of this type are called AndX SMBs, and they obey the following rules:
3.15 "Transaction" Style Subprotocols
The "transaction" style subprotocols are used for commands that potentially need to transfer a large amount of data (greater than 64K bytes). 3.15.1 SMB_COM_TRANSACTION2 Format
The following list describes the format of the TRANSACTION2 client request: Primary Client Request Description ======================= ============ Command SMB_COM_TRANSACTION2 UCHAR WordCount; Count of parameter words; value = (14 + SetupCount) USHORT TotalParameterCount; Total parameter bytes being sent USHORT TotalDataCount; Total data bytes being sent USHORT MaxParameterCount; Max parameter bytes to return USHORT MaxDataCount; Max data bytes to return UCHAR MaxSetupCount; Max setup words to return UCHAR Reserved; USHORT Flags; Additional information: bit 0 - Disconnect TID ULONG Timeout; USHORT Reserved2; USHORT ParameterCount; Parameter bytes sent this buffer USHORT ParameterOffset; Offset (from header start) to Parameters USHORT DataCount; Data bytes sent this buffer USHORT DataOffset; Offset (from header start) to data UCHAR SetupCount; Count of setup words UCHAR Reserved3; Reserved (pad above to word boundary) USHORT Setup[SetupCount]; Setup words (# = SetupWordCount) USHORT ByteCount; Count of data bytes STRING Name[]; Must be NULL UCHAR Pad[]; Pad to SHORT or LONG UCHAR Parameters[ Parameter bytes (# = ParameterCount) ParameterCount]; UCHAR Pad1[]; Pad to SHORT or LONG UCHAR Data[DataCount]; Data bytes (# = DataCount) The interim server response will consist of two fields: UCHAR WordCount; \ Count of parameter words = 0 USHORT ByteCount; \ Count of data bytes = 0 The following list describes the format of the TRANSACTION2 secondary client request: Secondary Client Request Description ========================= ============ Command SMB_COM_TRANSACTION_SECONDARY UCHAR WordCount; Count of parameter words = 8 USHORT TotalParameterCount; Total parameter bytes being sent USHORT TotalDataCount; Total data bytes being sent USHORT ParameterCount; Parameter bytes sent this buffer USHORT ParameterOffset; Offset (from header start) to Parameters USHORT ParameterDisplacement; Displacement of these Parameter bytes USHORT DataCount; Data bytes sent this buffer USHORT DataOffset; Offset (from header start) to data USHORT DataDisplacement; Displacement of these data bytes USHORT Fid; FID for handle based requests, else 0xFFFF. This field is present only if this is an SMB_COM_TRANSACTION2 request. USHORT ByteCount; Count of data bytes UCHAR Pad[]; Pad to SHORT or LONG UCHAR Parameters[ Parameter bytes (# = ParameterCount) ParameterCount]; UCHAR Pad1[]; Pad to SHORT or LONG UCHAR Data[DataCount]; Data bytes (# = DataCount) And, the fields of the server response are described in the following list: Server Response Description ================ ============ UCHAR WordCount; Count of data bytes; value = 10 + SetupCount USHORT TotalParameterCount; Total parameter bytes being sent USHORT TotalDataCount; Total data bytes being sent USHORT Reserved; USHORT ParameterCount; Parameter bytes sent this buffer USHORT ParameterOffset; Offset (from header start) to Parameters USHORT ParameterDisplacement; Displacement of these Parameter bytes USHORT DataCount; Data bytes sent this buffer USHORT DataOffset; Offset (from header start) to data USHORT DataDisplacement; Displacement of these data bytes UCHAR SetupCount; Count of setup words UCHAR Reserved2; Reserved (pad above to word boundary) USHORT Setup[SetupWordCount]; Setup words (# = SetupWordCount) USHORT ByteCount; Count of data bytes UCHAR Pad[]; Pad to SHORT or LONG UCHAR Parameters[ Parameter bytes (# = ParameterCount) ParameterCount]; UCHAR Pad1[]; Pad to SHORT or LONG UCHAR Data[DataCount]; Data bytes (# = DataCount) 3.15.2 SMB_COM_NT_TRANSACTION Formats
The following list describes the format of the TRANSACTION primary client request: Primary Client Request Description ======================= ============ UCHAR WordCount; Count of parameter words; value = (19 + SetupCount) UCHAR MaxSetupCount; Max setup words to return USHORT Reserved; ULONG TotalParameterCount; Total parameter bytes being sent ULONG TotalDataCount; Total data bytes being sent ULONG MaxParameterCount; Max parameter bytes to return ULONG MaxDataCount; Max data bytes to return ULONG ParameterCount; Parameter bytes sent this buffer ULONG ParameterOffset; Offset (from header start) to Parameters ULONG DataCount; Data bytes sent this buffer ULONG DataOffset; Offset (from header start) to data UCHAR SetupCount; Count of setup words USHORT Function; The transaction function code UCHAR Buffer[1]; USHORT Setup[SetupWordCount]; Setup words USHORT ByteCount; Count of data bytes UCHAR Pad1[]; Pad to LONG UCHAR Parameters[ Parameter bytes ParameterCount]; UCHAR Pad2[]; Pad to LONG UCHAR Data[DataCount]; Data bytes The interim server response will consist of two fields: UCHAR WordCount; \ Count of parameter words = 0 USHORT ByteCount; \ Count of data bytes = 0 The following list describes the format of the TRANSACTION secondary client request: Secondary Client Request Description ========================= ============ UCHAR WordCount; Count of parameter words = 18 UCHAR Reserved[3]; MUST BE ZERO ULONG TotalParameterCount; Total parameter bytes being sent ULONG TotalDataCount; Total data bytes being sent ULONG ParameterCount; Parameter bytes sent this buffer ULONG ParameterOffset; Offset (from header start) to Parameters ULONG ParameterDisplacement; Specifies the offset from the start of the overall parameter block to the parameter bytes that are contained in this message ULONG DataCount; Data bytes sent this buffer ULONG DataOffset; Offset (from header start) to data ULONG DataDisplacement; Specifies the offset from the start of the overall data block to the data bytes that are contained in this message UCHAR Reserved1; USHORT ByteCount; Count of data bytes UCHAR Pad1[]; Pad to LONG UCHAR Parameters[ Parameter bytes ParameterCount]; UCHAR Pad2[]; Pad to LONG UCHAR Data[DataCount]; Data bytes And, the fields of the server response are described in the following list: Server Response Description ================ ============ UCHAR WordCount; Count of data bytes; value = 18 + SetupCount UCHAR Reserved[3]; ULONG TotalParameterCount; Total parameter bytes being sent ULONG TotalDataCount; Total data bytes being sent ULONG ParameterCount; Parameter bytes sent this buffer ULONG ParameterOffset; Offset (from header start) to Parameters ULONG ParameterDisplacement; Specifies the offset from the start of the overall parameter block to the parameter bytes that are contained in this message ULONG DataCount; Data bytes sent this buffer ULONG DataOffset; Offset (from header start) to data ULONG DataDisplacement; Specifies the offset from the start of the overall data block to the data bytes that are contained in this message UCHAR SetupCount; Count of setup words USHORT Setup[SetupWordCount]; Setup words USHORT ByteCount; Count of data bytes UCHAR Pad1[]; Pad to LONG UCHAR Parameters[ Parameter bytes ParameterCount]; UCHAR Pad2[]; Pad to SHORT or LONG UCHAR Data[DataCount]; Data bytes 3.15.3 Functional Description
The transaction Setup information and/or Parameters define functions specific to a particular resource on a particular server. Therefore the functions supported are not defined by the transaction sub-protocol. The transaction protocol simply provides a means of delivering them and retrieving the results. The number of bytes needed in order to perform the transaction request may be more than will fit in a single buffer. At the time of the request, the client knows the number of parameter and data bytes expected to be sent and passes this information to the server via the primary request (TotalParameterCount and TotalDataCount). This may be reduced by lowering the total number of bytes expected (TotalParameterCount and TotalDataCount) in each (if any) secondary request. When the amount of parameter bytes received (total of each ParameterCount) equals the total amount of parameter bytes expected (smallest TotalParameterCount) received, then the server has received all the parameter bytes. Likewise, when the amount of data bytes received (total of each DataCount) equals the total amount of data bytes expected (smallest TotalDataCount) received, then the server has 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 (ParameterOffset and DataOffset) and the length fields (ParameterCount and DataCount). The displacement of the bytes (relative to start of each) is also known (ParameterDisplacement and DataDisplacement). Thus the server is able to reassemble the parameter and data bytes should the individual requests be received out of sequence. If all parameter bytes and data bytes fit into a single buffer, then no interim response is expected and no secondary request is sent. The client knows the maximum amount of data bytes and parameter bytes which may be returned by the server (from MaxParameterCount and MaxDataCount of the request). Thus the client initializes its bytes expected variables to these values. The server then informs the client of the actual amounts being returned via each message of the server response (TotalParameterCount and TotalDataCount). The server may reduce the expected bytes by lowering the total number of bytes expected (TotalParameterCount and/or TotalDataCount) in each (any) response. When the amount of parameter bytes received (total of each ParameterCount) equals the total amount of parameter bytes expected (smallest TotalParameterCount) received, then the client has received all the parameter bytes. Likewise, when the amount of data bytes received (total of each DataCount) equals the total amount of data bytes expected (smallest TotalDataCount) received, then the client has received all the data bytes. The parameter bytes should normally be returned first followed by the data bytes. However, the client knows where each begins and ends in each buffer by the offset fields (ParameterOffset and DataOffset) and the length fields (ParameterCount and DataCount). The displacement of the bytes (relative to start of each) is also known (ParameterDisplacement and DataDisplacement). The client is able to reassemble the parameter and data bytes should the server responses be received out of sequence. The flow for these transactions over a connection oriented transport is:
The flow for the transaction protocol when the request parameters and data do not all fit in a single buffer is:
The flow for the transaction protocol when the request parameters and data do all fit in a single buffer is:
The primary transaction request through the final response make up the complete transaction exchange, thus the Tid, Pid, Uid and Mid must remain constant and can be used as appropriate by both the server and the client. Of course, other SMB requests may intervene as well. There are (at least) three ways that actual server responses have been observed to differ from what might be expected. First, some servers will send Pad bytes to move the DataOffset to a 2-or 4-byte boundary even if there are no data bytes; the point here is that the ByteCount must be used instead of ParameterOffset plus ParameterCount to infer the actual message length. Second, some servers always return MaxParameterCount bytes even if the particular Transact2 has no parameter response. Finally, in case of an error, some servers send the "traditional WordCount==0/ByteCount==0" response while others generate a Transact response format. 3.15.4 SMB_COM_TRANSACTION Operations
DCE/RPC documents were defined by the Open Group (TOG) used to be called the X/open group. CIFS uses DCE/RPC to process Server and User management information, like logon information, Local Security, Account management, Server/Workstation services and CIFS networking management functions (like browsing and domain controller management). DCE/RPC are implemented on top of SMB. SMB protocol is used as a transport for the DCE/RPC protocol. DCE/RPC uses Protocol Data Unit (PDU) fragments to communicate. The PDUs are totally independent of the SMB transmission size. So PDU can span over multiple SMB transmission boundaries and multiple PDUs can be transmitted in a single SMB transmission. Name Pipe are used as the transmission vehicle. Once and Named Pipe is opened all the DCE/RPC calls related to that Name Pipe will be written and read through SMB_COM_TRANSCATION operation. SMB_COM_TRANSACTION will communicate to the Name Pipe with as much PDU fragments it can contains, the rest of the fragments will follow with either SMBReadX or SMBWriteX. Some of the RPC calls are defined at Appendix E. The "smb com transaction" style subprotocols are used mostly as MS RPC commands for managing the server and the client. Mail Slots are used for broadcasting and informing the other nodes on the networks. Named Pipes are mostly used for RPC. The details of the use of these RPCs are outside of the scope of this document. The following section describes the data format, but not the content of the content of the RPC. After the client or the server has open a Name Pipe the RPC are communicated using that pipe. 3.15.4.1 Mail Slot Transaction Protocol
The only transaction allowed to a mailslot is a mailslot write. The following table shows the interpretation of parameters for a mailslot transaction:
3.15.4.2 Server Announcement Mailslot Transaction
A server announces its presence on the network by periodically transmitting an announcement mailslot message to a well known name. The server initially announces itself every minute, but as the server stays up for longer and longer periods, it should stretch out its announcement period to a maximum of once every 12 minutes. If a server has not been heard from for three announcements, it is considered unavailable. The announcements can be received by any entity on the network wishing to keep a reasonably up to date view of the available network servers. Systems wishing to be visible on the network and compatible with LANMAN 1.0 periodically send the following announcement:
The NETBIOS address for this mailslot transaction is the domain name padded with blanks and having a zero as the sixteenth octet. A client can cause LANMAN 1.0 severs to announce themselves to the client by sending the following mailslot transaction to the specific computer of interest or to the domain name as previously described:
Nodes wishing to be visible on the network and compatible with systems using Windows for Workgroups 3.1a and later dialects periodically send the following directed mailslot message to a NETBIOS address consisting of the domain name padded with blanks and having a 0x1D in the sixteenth octet.
3.15.4.3 Named Pipe Transaction Protocol
A named pipe SMB_COM_TRANSACTION is used to wait for the specified named pipe to become available (WaitNmPipe) or perform a logical "open -> write -> read -> close" of the pipe (CallNmPipe), along with other functions defined below. The identifier "\PIPE\<name>" denotes a named pipe transaction, where the <name> is the pipe name to apply the transaction against.
The subcommand codes, placed in SETUP[ ] , for named pipe operations are:
3.15.4.4 CallNamedPipe
This command is used to implement the Win32 CallNamedPipe() API remotely. The CallNamedPipe function connects to a message-type pipe (and waits if an instance of the pipe is not available), writes to and reads from the pipe, and then closes the pipe. This form of the transaction protocol sends no parameter bytes, thus the bytes to be written to the pipe are sent as data bytes and the bytes read from the pipe are returned as data bytes. The number of bytes being written is defined by TOTALDATACOUNT and the maximum number of bytes to return is defined by MAXDATACOUNT . On the response TOTALPARAMETERCOUNT is 0 (no Parameter bytes to return), TOTALDATACOUNT indicates the amount of databytes being returned in total and DATACOUNT identifies the amount of data being returned in each buffer. Note that the full form of the Transaction protocol can be used to write and read up to 65,535 bytes each utilizing the secondary requests and responses. 3.15.4.5 WaitNamedPipe
The command is used to implement the Win32 WaitNamedPipe() API remotely. The WaitNamedPipe function waits until either a time-out interval elapses or an instance of the specified named pipe is available to be connected to (that is, the pipe's server process has a pending ConnectNamedPipe operation on the pipe). The server will wait up to TIMEOUT milliseconds for a pipe of the name given to become available. Note that although the timeout is specified in milliseconds, by the time that the timeout occurs and the client receives the timed out response much more time than specified may have occurred. This form of the transaction protocol sends no data or parameter bytes. The response also contains no data or parameters. If the transaction response indicates success, the pipe may now be available. However, this request does not reserve the pipe, thus all waiting programs may race to get the pipe now available. The losers will get an error on the pipe open attempt. 3.15.4.6 PeekNamedPipe
This form of the pipe Transaction protocol is used to implement the Win32 PeekNamePipe() API remotely. The PeekNamedPipe function copies data from a named or anonymous pipe into a buffer without removing it from the pipe. It also returns information about data in the pipe. TOTALPARAMETERCOUNT and TOTALDATACOUNT should be 0 for this request. The FID of the pipe to which this request should be applied is in Setup[1]. MAXPARAMETERCOUNT should be set to 6, requesting 3 words of information about the pipe, and MAXDATACOUNT should be set to the number of bytes to "peek". The response contains the following PARAMETER WORDS :
The DATA portion of the response is the data peeked from the named pipe. 3.15.4.7 GetNamedPipeHandleState
This form of the pipe transaction protocol is used to implement the Win32 GetNamedPipeHandleState() API. The GetNamedPipeHandleState function retrieves information about a specified named pipe. The information returned can vary during the lifetime of an instance of the named pipe. This request sends no parameters and no data. The FID of the pipe to which this request should be applied is in Setup[1]. MAXPARAMETERCOUNT should be set to 2 (requesting the 1 word of information about the pipe) and MAXDATACOUNT should be 0 (not reading the pipe). The response returns one parameter of pipe state information interpreted as: Pipe Handle State Bits 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 => client 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 The E (endpoint) bit is 0 because this handle is the client end of a pipe. 3.15.4.8 SetNamedPipeHandleState
This form of the pipe transaction protocol is used to implement the Win32 SetNamedPipeHandleState() API. The SetNamedPipeHandleState function sets the read mode and the blocking mode of the specified named pipe. This request sends 1 parameter word ( TOTALPARAMETERCOUNT = 2) which is the pipe state to be set. The FID of the pipe to which this request should be applied is in SETUP[1]. The response contains no data or parameters. The interpretation of the input parameter word is: Pipe Handle State Bits 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 B * * * * * R R 0 0 0 0 0 0 0 0 where: B - Blocking 0 => reads/writes block if no data available 1 => reads/writes return immediately if no data RR - Read Mode 00 => Read pipe as a byte stream 01 => Read messages from pipe Note that only the read mode (byte or message) and blocking/nonblocking mode of a named pipe can be changed. Some combinations of parameters may be illegal and will be rejected as an error. 3.15.4.9 GetNamedPipeInfo
This form of the pipe transaction protocol is used to implement the Win32 GetNamedPipeInfo() API. The GetNamedPipeInfo function retrieves information about the specified named pipe. The request sends 1 parameter word ( TOTALPARAMETERCOUNT = 2) which is the information level requested and must be set to 1. The FID of the pipe to which this request should be applied is in SETUP[1]. MAXDATACOUNT should be set to the size of the buffer specified by the user in which to receive the pipe information. Pipe information is returned in the data area of the response, up to the number of bytes specified. The information is returned in the following format:
3.15.4.10 TransactNamedPipe
This form of the pipe transaction protocol is used to implement the Win32 TransactNamedPipe() API. The TransactNamedPipe function combines into a single network operation the functions that write a message to and read a message from the specified named pipe. It provides an optimum way to implement transaction-oriented dialogs. TransactNamedPipe will fail if the pipe currently contains any unread data or is not in message read mode. Otherwise the call will write the entire request data bytes to the pipe and then read a response from the pipe and return it in the data bytes area of the response protocol. In the transaction request, SETUP[1] must contain the FID of the pipe. If NAME is \PIPE\LANMAN, this is a server API request. The request encoding is:
The response is formatted as:
The state of blocking/nonblocking has no effect on this protocol (TransactNamedPipe does not return until a message has been read into the response protocol). If MAXDATACOUNT is too small to contain the response message, an error is returned. 3.15.4.11 RawReadNamedPipe
RawReadNamedPipe reads bytes directly from a pipe, regardless of whether it is a message or byte pipe. For a byte pipe, this is exactly like SMB_COM_READ . For a message pipe, this is exactly like reading the pipe in byte read mode, except message headers will also be returned in the buffer (note that message headers will always be returned in totonever split at a byte boundary). This request sends no parameters or data to the server, and SETUP[1] must contain the FID of the pipe to read. MAXDATACOUNT should contain the number of bytes to read raw. The response will return 0 parameters, and DATACOUNT will be set to the number of bytes read. 3.15.4.12 RawWriteNamedPipe
RawWriteNamedPipe puts bytes directly into a pipe, regardless of whether it is a message or byte pipe. The data will include message headers if it is a message pipe. This call ignores the blocking/nonblocking state and always acts in a blocking manner. It returns only after all bytes have been written. The request sends no parameters. SETUP[1] must contain the FID of the pipe to write. TOTALDATACOUNT is the total amount of data to write to the pipe. Writing zero bytes to a pipe is an error unless the pipe is in message mode. The response contains no data and one parameter word. If no error is returned, the one parameter word indicates the number of the requested bytes that have been "written raw" to the specified pipe. 3.16 Valid SMB Requests by Negotiated Dialect
CIFS clients and servers may exchange the following SMB messages if the "PC NETWORK PROGRAM 1.0" dialect is negotiated: SMB_COM_CREATE_DIRECTORY SMB_COM_DELETE_DIRECTORY SMB_COM_OPEN SMB_COM_CREATE SMB_COM_CLOSE SMB_COM_FLUSH SMB_COM_DELETE SMB_COM_RENAME SMB_COM_QUERY_INFORMATION SMB_COM_SET_INFORMATION SMB_COM_READ SMB_COM_WRITE SMB_COM_LOCK_BYTE_RANGE SMB_COM_UNLOCK_BYTE_RANGE SMB_COM_CREATE_TEMPORARY SMB_COM_CREATE_NEW SMB_COM_CHECK_DIRECTORY SMB_COM_PROCESS_EXIT SMB_COM_SEEK SMB_COM_TREE_CONNECT SMB_COM_TREE_DISCONNECT SMB_COM_NEGOTIATE SMB_COM_QUERY_INFORMATION_DISK SMB_COM_SEARCH SMB_COM_OPEN_PRINT_FILE SMB_COM_WRITE_PRINT_FILE SMB_COM_CLOSE_PRINT_FILE SMB_COM_GET_PRINT_QUEUE If the "LANMAN 1.0" dialect is negotiated, all of the messages in the previous list must be supported. Clients negotiating LANMAN 1.0 and higher dialects will probably no longer send SMB_COM_PROCESS_EXIT, and the response format for SMB_COM_NEGOTIATE is modified as well. New messages introduced with the LANMAN 1.0 dialect are: SMB_COM_LOCK_AND_READ SMB_COM_WRITE_AND_UNLOCK SMB_COM_READ_RAW SMB_COM_READ_MPX SMB_COM_WRITE_MPX SMB_COM_WRITE_RAW SMB_COM_WRITE_COMPLETE SMB_COM_WRITE_MPX_SECONDARY SMB_COM_SET_INFORMATION2 SMB_COM_QUERY_INFORMATION2 SMB_COM_LOCKING_ANDX SMB_COM_TRANSACTION SMB_COM_TRANSACTION_SECONDARY SMB_COM_IOCTL SMB_COM_IOCTL_SECONDARY SMB_COM_COPY SMB_COM_MOVE SMB_COM_ECHO SMB_COM_WRITE_AND_CLOSE SMB_COM_OPEN_ANDX SMB_COM_READ_ANDX SMB_COM_WRITE_ANDX SMB_COM_SESSION_SETUP_ANDX SMB_COM_TREE_CONNECT_ANDX SMB_COM_FIND SMB_COM_FIND_UNIQUE SMB_COM_FIND_CLOSE The "LM1.2X002" dialect introduces these new SMBs: SMB_COM_TRANSACTION2 SMB_COM_TRANSACTION2_SECONDARY SMB_COM_FIND_CLOSE2 SMB_COM_LOGOFF_ANDX "NT LM 0.12" dialect introduces: SMB_COM_NT_TRANSACT SMB_COM_NT_TRANSACT_SECONDARY SMB_COM_NT_CREATE_ANDX SMB_COM_NT_CANCEL SMB_COM_NT_RENAME Capabilities are used to determine which SMB requests a server supports. However, they do not directly map to which info levels associated with that particular request are supported. In the event that a client sends a request with an info -level that the server does not support or recognize (if it is legacy), it should return STATUS_UNSUPPORTED (or the non-NT equivalent). The extended functionality that was added later is then simply not available to client applications who would ask for it. (If a file system or SMB server does not support unique file ID's, then the query file information asking for it would return Unsupported, where as the query for other types of file information would return successfully.) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||