3.0 SMB Message Formats and Data Types

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 specification makes use of "C"-like notation to describe the formats of messages. Unlike the "C" language, which allows implementation flexibility in laying out structures, this specification 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.

3.2 SMB Header

Although each SMB command has specific encodings, some fields in the SMB header 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 security
        } Extra;
    };
    USHORT Tid;                       // Tree identifier
    USHORT Pid;                       // Caller's process id
    USHORT Uid;                       // Unauthenticated 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 specification have identical format up to the ParameterWords fields. (Some obsolescent ones do not.) Different SMBs have a different number and interpretation of ParameterWords and Buffer. All reserved fields in the SMB header must be zero.

Note   Command is the operation code that this SMB is requesting or responding to.

3.2.1 Flags Field

This field contains eight individual flags, numbered from least significant to most significant, which have the following meanings:

3.3.2 Flags2 Field

This field contains six individual flags that are defined below and numbered from least significant bit to most significant bit. Flags that are not defined must be set to zero.

3.2.3 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 include prior to getting a Tid established, including SMB_COM_NEGOTIATE, SMB_COM_TREE_CONNECT, 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.

3.2.4 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.

3.2.5 Uid Field

Uid is a user ID assigned by the server after a user authenticates to it, and that will be associated 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 than the one who authenticated. (It is permitted that a single user 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.6 Mid Field

The multiplex ID (Mid) is used along with 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) 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.7 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. 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.8 Timeouts

In general, SMBs are not expected to block at the server; they should return "immediately." But some SMB requests do indicate timeout periods for the completion of the request on the server. If a server implementation cannot support timeouts, an error can be returned just as if a timeout had occurred—if the resource is not available immediately upon request.

3.2.9 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, which in every case 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:

• The protocol strings in the Negotiate SMB request.
  
  
• The service name string in the Tree_Connect_AndX SMB.

When Unicode is negotiated, bit 15 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 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 that returns file names to the client may return names that 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.

3.4 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.

If the client is using 8.3 names, each part of the name ( base (8) or extension (3) ) is treated separately. For long filenames, the . in the name is significant even though there is no longer a restriction on the size of each of the components.

The ? character is a wild card for a single character. If a 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.

The * character matches an entire part of the name, as does an empty specification for that part. A part consisting of * means that the rest of the component should be filled with ?, and the search should be performed with this wildcard character. For example, "*.abc" or ".abc" match any file with an extension of "abc". "*.*," "*" or "null" match 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:

Translate the ? literal to >

Translate the . literal to " if it is followed by a ? or a *

Translate the * literal to < if it is followed by a .

The translation can be performed in-place.

3.5 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, there must be 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.6 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, where the base time (the 64-bit integer with value 0) is the beginning of the year 1601 AD in the Gregorian calendar. 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.7 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 file control block (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.8 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:

3.9 Open Function Encoding

OpenFunction specifies the action to be taken depending on whether or not the file exists. This word has the following format:

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.

3.10 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:

bits:

    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.11 File Attribute Encoding

When SMB messages exchange file attribute information, it is encoded in 16 bits as:

3.12 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.13 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:

• The embedded command does not repeat the SMB header information. Rather the next SMB starts at the WordCount field.
  
  
• All multiple (chained) requests must fit within the negotiated transmit size. For example, if SMB_COM_TREE_CONNECT_ANDX included OPENandX SMB_COM_OPEN_ANDX, which included SMB_COM_WRITE were sent, they would all have to fit within the negotiated buffer size. This would limit the size of the write.
  
  
• There is one message sent containing the chained requests, and there is one response message to the chained requests. The server may NOT elect to send separate responses to each of the chained requests.
  
  
• All chained responses must fit within the negotiated transmit size. This limits the maximum value on an embedded SMB_COM_READ, for example. It is the client's responsibility to not request more bytes than will fit within the multiple response.
  
  
• The server will implicitly use the result of the first command in the "X" command. For example, the Tid obtained via SMB_COM_TREE_CONNECT_ANDX would be used in the embedded SMB_COM_OPEN_ANDX, and the Fid obtained in the SMB_COM_OPEN_ANDX would be used in the embedded SMB_COM_READ.
  
  
• Each chained request can only reference 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) operation on the same resource.
  
  
• The first Command to encounter an error will stop all further processing of embedded commands. The server will not back out commands that succeeded. Thus, if a chained request contained SMB_COM_OPEN_ANDX and SMB_COM_READ, 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.
  
  
• If an error occurs while processing chained requests, the last response (of the chained responses in the buffer) will be the one that 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 AndXCommand (if any) will represent the SMB on which the error occurred. If no valid AndXCommand is present, then the error occurred on the first request/response, and Command contains the command that failed. In all cases, the error information is returned in the SMB header at the start of the response buffer.
  
  
• Each chained request and response contains the offset (from the start of the SMB header) to the next chained request/response (in the AndXOffset field in the various "and X" protocols defined later, e.g., SMB_COM_OPEN_ANDX). This allows building the requests unpacked. There may be space between the end of the previous request (as defined by WordCount and ByteCount) and the start of the next chained request. This simplifies the building of chained protocol requests. Note that because the client must know the size of the data being returned in order to post the correct number of receives (e.g., SMB_COM_TRANSACTION, SMB_COM_READ_MPX), the data in each response SMB is expected to be truncated to the maximum number of 512 byte blocks (sectors), which will fit (starting at a 32-bit boundary) in the negotiated buffer size with the odd bytes remaining (if any) in the final buffer.

3.14 "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.14.1 SMB_COM_TRANSACTION2 Format

3.14.2 The 3.13.2 SMB_COM_NT_TRANSACTION Formats

3.14.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 subprotocol. 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, the server has then 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, the server has then 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, no interim response is expected, and no secondary request is sent.

The client knows the maximum amount of data bytes and parameter bytes that the server may return (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, the client has then 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, the client has then 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:

1. The client sends the primary client request identifying the total bytes (both parameters and data) expected to be sent, and contains the set up words and as many of the parameter and data bytes as will fit in a negotiated size buffer. This request also identifies the maximum number of bytes (setup, parameters, and data) the server is to return on the transaction 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" or (if error response) terminate the transaction.
   
   
3. The client then sends another buffer full of bytes to the server. This step is repeated until all of the bytes are sent and received.
   
   
4. The Server sets up and performs the transaction with the information provided.
   
   
5. Upon completion of the transaction, 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.

The flow for the transaction protocol when the request parameters and data do not all fit in a single buffer is:

When the request parameters and data all fit in a single buffer, the flow for the transaction protocol is:

The primary transaction request through the final response makes 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 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:

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:

The "LM1.2X002" dialect introduces these new SMBs:

"NT LM 0.12" dialect introduces: