Network Working Group Paul J. Leach, Microsoft
INTERNET-DRAFT Dilip C. Naik, Microsoft
draft-leach-cifs-v1-spec-02.txt
Category: Informational
Expires September 13, 1997 March 13, 1997
A Common Internet File System (CIFS/1.0) Protocol
Preliminary Draft
(Annotated)
Status of this Memo
[This document is an expired draft.]
This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas, and
its working groups. Note that other groups may also distribute working
documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or made obsolete by other documents at any
time. It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as "work in progress".
To learn the current status of any Internet-Draft, please check the
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
ftp.isi.edu (US West Coast).
Distribution of this document is unlimited. Please send comments to the
authors at <cifs@microsoft.com>. Discussion of CIFS is on the mailing
list <cifs@listserv.msn.com>; subscribe by sending a message to
<ListServ@listserv.msn.com> with a body of "subscribe CIFS
you@your.domain". There is a CIFS home page at
<http://www.microsoft.com/intdev/cifs>.
Abstract
This document describes the CIFS file sharing protocol, version 1.0.
Client systems use this protocol to request file and print services
from server systems over a network. It is based on the Server Message
Block protocol widely in use by personal computers and workstations
running a wide variety of operating systems.
Table Of Contents
STATUS OF THIS MEMO......................................................1
ABSTRACT.................................................................1
TABLE OF CONTENTS........................................................1
1 INTRODUCTION...........................................................5
1.1 SUMMARY OF FEATURES.................................................5
Leach, Naik expires September, 1997 [Page 1]
INTERNET-DRAFT CIFS/1.0 03/19/97
1.1.1 File access.....................................................5
1.1.2 File and record locking.........................................6
1.1.3 Safe caching, read-ahead, and write-behind......................6
1.1.4 File change notification........................................6
1.1.5 Protocol version negotiation....................................6
1.1.6 Extended attributes.............................................6
1.1.7 Distributed replicated virtual volumes..........................6
1.1.8 Server name resolution independence.............................7
1.1.9 Batched requests................................................7
2 PROTOCOL OPERATION OVERVIEW............................................7
2.1 SERVER NAME DETERMINATION...........................................7
2.2 SERVER NAME RESOLUTION..............................................8
2.3 SAMPLE MESSAGE FLOW.................................................8
2.4 MESSAGE FORMAT......................................................9
2.4.1 Notation........................................................9
2.4.2 SMB header.....................................................10
2.5 CIFS PROTOCOL DIALECT NEGOTIATION..................................11
2.6 MESSAGE TRANSPORT..................................................11
2.6.1 Connection Establishment.......................................11
2.6.2 Server-side Connection Procedures..............................12
2.6.3 Connection Management..........................................12
2.7 OPPORTUNISTIC LOCKS................................................13
2.7.1 Exclusive Oplocks..............................................13
2.7.2 Batch Oplocks..................................................14
2.7.3 Level II Oplocks...............................................16
2.8 SECURITY MODEL.....................................................17
2.9 RESOURCE SHARE/ACCESS EXAMPLE......................................18
2.10 AUTHENTICATION....................................................19
2.10.1 Pre NT LM 0.12.................................................20
2.10.2 NT LM 0.12.....................................................21
2.11 DISTRIBUTED FILESYSTEM (DFS) SUPPORT..............................21
3 SMB MESSAGE FORMATS AND DATA TYPES....................................22
3.1 SMB HEADER.........................................................22
3.1.1 Flags field....................................................22
3.1.2 Flags2 Field...................................................24
3.1.3 Tid Field......................................................24
3.1.4 Pid Field......................................................25
3.1.5 Mid Field......................................................25
3.1.6 Status Field...................................................26
3.1.7 Timeouts.......................................................26
3.1.8 Data Buffer (BUFFER) and String Formats........................26
3.2 FILE NAMES.........................................................27
3.3 WILDCARDS..........................................................28
3.4 DFS PATHNAMES......................................................28
3.5 TIME AND DATE ENCODING.............................................29
3.6 ACCESS MODE ENCODING...............................................30
3.7 ACCESS MASK ENCODING...............................................31
3.8 OPEN FUNCTION ENCODING.............................................32
3.9 OPEN ACTION ENCODING...............................................32
3.10 FILE ATTRIBUTE ENCODING...........................................33
3.11 EXTENDED FILE ATTRIBUTE ENCODING..................................33
3.12 BATCHING REQUESTS ("ANDX" MESSAGES)...............................36
3.13 "TRANSACTION" STYLE SUBPROTOCOLS..................................37
3.13.1 SMB_COM_TRANSACTION and SMB_COM_TRANSACTION2 Formats...........38
Leach, Naik expires September, 1997 [Page 2]
INTERNET-DRAFT CIFS/1.0 03/19/97
3.13.2 SMB_COM_NT_TRANSACTION Formats.................................40
3.13.3 Functional Description.........................................42
3.14 VALID SMB REQUESTS BY NEGOTIATED DIALECT..........................46
4 SMB REQUESTS..........................................................47
4.1 SESSION REQUESTS...................................................48
4.1.1 NEGOTIATE: Negotiate Protocol..................................48
4.1.2 SESSION_SETUP_ANDX: Session Setup..............................51
4.1.3 LOGOFF_ANDX: User Logoff.......................................56
4.1.4 TREE_CONNECT_ANDX: Tree Connect...............................56
4.1.5 TREE_DISCONNECT: Tree Disconnect..............................59
4.1.6 TRANS2_QUERY_FS_INFORMATION: Get File System Information.......59
4.1.7 ECHO: Ping the Server..........................................65
4.1.8 NT_CANCEL: Cancel request......................................65
4.2 FILE REQUESTS......................................................66
4.2.1 NT_CREATE_ANDX: Create or Open File............................66
4.2.2 NT_TRANSACT_CREATE: Create or Open File with EAs or SD.........69
4.2.3 CREATE_TEMPORARY: Create Temporary File........................70
4.2.4 READ_ANDX: Read Bytes..........................................71
4.2.5 WRITE_ANDX: Write Bytes to file or resource....................72
4.2.6 LOCKING_ANDX: Lock or Unlock Byte Ranges.......................73
4.2.7 SEEK: Seek in File.............................................76
4.2.8 FLUSH: Flush File..............................................78
4.2.9 CLOSE: Close File..............................................78
4.2.10 DELETE: Delete File............................................79
4.2.11 RENAME: Rename File............................................80
4.2.12 MOVE: Rename File..............................................81
4.2.13 COPY: Copy File................................................83
4.2.14 TRANS2_QUERY_PATH_INFORMATION: Get File Attributes given Path..84
4.2.15 TRANS2_QUERY_FILE_INFORMATION: Get File Attributes Given FID...91
4.2.16 TRANS2_SET_PATH_INFORMATION: Set File Attributes given Path....91
4.2.17 TRANS2_SET_FILE_INFORMATION: Set File Attributes Given FID.....93
4.3 DIRECTORY REQUESTS.................................................94
4.3.1 DELETE_DIRECTORY: Delete Directory.............................95
4.3.2 CHECK_DIRECTORY: Check Directory...............................95
4.3.3 TRANS2_FIND_FIRST2: Search Directory using Wildcards...........96
4.3.4 TRANS2_FIND_NEXT2: Resume Directory Search Using Wildcards....101
4.3.5 FIND_CLOSE2: Close Directory Search...........................102
4.3.6 NT_TRANSACT_NOTIFY_CHANGE: Request Change Notification........102
4.4 DFS OPERATIONS....................................................104
4.4.1 TRANS2_GET_DFS_REFERRAL: Retrieve Distributed Filesystem
Referral......................................................104
4.4.2 TRANS2_REPORT_DFS_INCONSISTENCY: Inform a server about DFS
Error.........................................................107
4.5 PRINT SPOOLING OPERATIONS.........................................107
4.5.1 OPEN_PRINT_FILE: Create Print Spool file......................107
4.5.2 GET_PRINT_QUEUE: Get Printer Queue Entries....................108
4.6 MISCELLANEOUS OPERATIONS..........................................110
4.6.1 NT_TRANSACT_IOCTL.............................................110
4.6.2 NT_TRANSACT_QUERY_SECURITY_DESC...............................110
4.6.3 NT_TRANSACT_SET_SECURITY_DESC.................................111
5 OBSOLESCENT SMB REQUESTS.............................................111
Leach, Naik expires September, 1997 [Page 3]
INTERNET-DRAFT CIFS/1.0 03/19/97
5.1 CLOSE_PRINT_FILE: CLOSE AND SPOOL PRINT JOB......................111
5.2 CREATE: CREATE FILE...............................................112
5.3 CREATE_DIRECTORY: CREATE DIRECTORY................................113
5.4 CREATE_NEW: CREATE FILE...........................................113
5.5 LOCK_AND_READ: LOCK AND READ BYTES................................114
5.6 LOCK_BYTE_RANGE: LOCK BYTES.......................................115
5.7 OPEN: OPEN FILE...................................................116
5.8 OPEN_ANDX: OPEN FILE.............................................118
5.9 PROCESS_EXIT: PROCESS EXIT........................................119
5.10 QUERY_INFORMATION: GET FILE ATTRIBUTES..........................120
5.11 QUERY_INFORMATION2: GET FILE INFORMATION.........................120
5.12 READ: READ FILE..................................................121
5.13 READ_MPX: READ BLOCK MULTIPLEX...................................122
5.14 READ_RAW: READ RAW...............................................124
5.15 SEARCH: SEARCH DIRECTORY USING WILDCARDS.........................126
5.16 SET_INFORMATION: SET FILE ATTRIBUTES.............................128
5.17 SET_INFORMATION2: SET FILE INFORMATION...........................129
5.18 QUERY_INFORMATION_DISK: GET DISK ATTRIBUTES......................129
5.19 TRANS2_OPEN2: CREATE OR OPEN FILE WITH EXTENDED ATTRIBUTES.......130
5.20 TREE_CONNECT: TREE CONNECT.......................................132
5.21 UNLOCK_BYTE_RANGE: UNLOCK BYTES..................................132
5.22 WRITE: WRITE BYTES...............................................133
5.23 WRITE_AND_UNLOCK: WRITE BYTES AND UNLOCK RANGE...................134
5.24 WRITE_AND_CLOSE: WRITE BYTES AND CLOSE FILE.....................135
5.25 WRITE_MPX: WRITE BLOCK MULTIPLEX.................................136
5.26 WRITE_PRINT_FILE: WRITE TO PRINT FILE............................138
5.27 WRITE_RAW: WRITE RAW BYTES.......................................139
6 SMB SYMBOLIC CONSTANTS...............................................142
6.1 SMB COMMAND CODES.................................................142
6.2 SMB_COM_TRANSACTION2 SUBCOMMAND CODES.............................144
6.3 SMB_COM_NT_TRANSACTION SUBCOMMAND CODES...........................145
6.4 SMB PROTOCOL DIALECT CONSTANTS....................................145
7 ERROR CODES AND CLASSES..............................................146
8 LEGAL NOTICE.........................................................150
9 REFERENCES...........................................................150
10 SECURITY CONSIDERATIONS.............................................151
10.1 SHARE LEVEL PROTECTION...........................................151
10.2 PLAINTEXT PASSWORD AUTHENTICATION................................151
10.3 LANMAN 2.1 (AND EARLIER) CHALLENGE/RESPONSE......................151
10.3.1 Known Plaintext Attacks.......................................152
10.3.2 Small Key Space...............................................152
10.3.3 Chosen Plaintext Attacks......................................152
10.3.4 Dictionary Attacks............................................152
10.3.5 Badly Chosen Passwords........................................152
10.4 NT LM 0.12 CHALLENGE/RESPONSE....................................153
10.5 OTHER ATTACKS....................................................153
10.5.1 Hijack connections............................................153
10.5.2 Downgrade attack..............................................153
10.5.3 Spoofing by Counterfeit Servers...............................154
10.5.4 Storing Passwords Safely......................................154
11 AUTHORS' ADDRESSES..................................................154
Leach, Naik expires September, 1997 [Page 4]
INTERNET-DRAFT CIFS/1.0 03/19/97
1 Introduction
This document describes the file and print sharing protocol for a
proposed Common Internet File System (CIFS). CIFS is intended to provide
an open cross-platform mechanism for client systems to request file and
print services from server systems over a network. It is based on the
standard Server Message Block (SMB) protocol widely in use by personal
computers and workstations running a wide variety of operating systems.
An earlier version of this protocol was documented as part of the X/OPEN
(now Open Group) CAE series of standards [7]; this document updates the
specification to include the latest shipping versions, and is published
to allow the creation of implementations that interoperate with those
implementations.
Use of the Internet and the World Wide Web has been characterized by
read-only access. Existing protocols such as FTP are good solutions for
one-way file transfer. However, new read/write interfaces will become
increasingly necessary as the Internet becomes more interactive and
collaborative. Adoption of a common file sharing protocol having modern
semantics such as shared files, byte-range locking, coherent caching,
change notification, replicated storage, etc. would provide important
benefits to the Internet community.
1.1 Summary of features
The protocol supports the following features:
o File access
o File and record locking
o Safe caching, read-ahead, and write-behind
o File change notification
o Protocol version negotiation
o Extended attributes
o Distributed replicated virtual volumes
o Server name resolution independence
o Batched requests
o Unicode file names
1.1.1 File access
The protocol supports the usual set of file operations: open, close,
read, write, and seek.
Leach, Naik expires September, 1997 [Page 5]
INTERNET-DRAFT CIFS/1.0 03/19/97
1.1.2 File and record locking
The protocol supports file and record locking, as well as unlocked
access to files. Applications that lock files can not be improperly
interfered with by applications that do not; once a file or record is
locked, non-locking applications are denied access to the file.
1.1.3 Safe caching, read-ahead, and write-behind
The protocol supports caching, read-ahead, and write-behind, even for
unlocked files, as long as they are safe. All these optimizations are
safe as long as only one client is accessing a file; read-caching and
read-ahead are safe with many clients accessing a file as long as all
are just reading. If many clients are writing a file simultaneously,
then none are safe, and all file operations have to go to the server.
The protocol notifies all clients accessing a file of changes in the
number and access mode of clients accessing the file, so that they can
use the most optimized safe access method.
1.1.4 File change notification
Applications can register with a server to be notified if and when file
or directory contents are modified. They can use this to (for example)
know when a display needs to be refreshed, without having to constantly
poll the server.
1.1.5 Protocol version negotiation
There are several different versions and sub-versions of this protocol;
a particular version is referred to as a dialect. When two machines
first come into network contact they negotiate the dialect to be used.
Different dialects can include both new messages as well as changes to
the fields and semantics of existing messages in other dialects.
1.1.6 Extended attributes
In addition to many built-in file attributes, such as creation and
modification times, non-file system attributes can be added by
applications, such as the author's name, content description, etc.
1.1.7 Distributed replicated virtual volumes
The protocol supports file system subtrees which look like to clients as
if they are on a single volume and server, but which actually span
multiple volumes and servers. The files and directories of such a
subtree can be physically moved to different servers, and their names do
not have to change, isolating clients from changes in the server
configuration. These subtrees can also be transparently replicated for
load sharing and fault tolerance. When a client requests a file, the
Leach, Naik expires September, 1997 [Page 6]
INTERNET-DRAFT CIFS/1.0 03/19/97
protocol uses referrals to transparently direct a client to the server
that stores it.
1.1.8 Server name resolution independence
The protocol allows clients to resolve server names using any name
resolution mechanism. In particular, it allows using the DNS, permitting
access to the file systems of other organizations over the Internet, or
hierarchical organization of servers' names within an organization.
Earlier versions of the protocol only supported a flat server name
space.
1.1.9 Batched requests
The protocol supports the batching of multiple requests into a single
message, in order to minimize round trip latencies, even when a later
request depends on the results of an earlier one.
2 Protocol Operation Overview
In order to access a file on a server, a client has to:
o Parse the full file name to determine the server name, and the
relative name within that server.
o Resolve the server name to a transport address (this may be cached)
o Make a connection to the server (if no connection is already
available)
o Exchange CIFS messages (see below for an example)
This process may be repeated as many times as desired. Once the
connection has been idle for a while, it may be torn down.
2.1 Server Name Determination
How the client determines the name of the server and the relative name
within the server is outside of the scope of this specification.
However, just for expository purposes, here are three examples.
In the URL "file://fs.megacorp.com/users/fred/stuff.txt", the client
could take the part between the leading double slashes and the next
slash as the server name and the remainder as the relative name -- in
this example "fs.megacorp.com" and "/users/fred/stuff.txt",
respectively.
In the path name "\\corpserver\public\policy.doc" the client could take
the part between the leading double backslashes and the next slash as
Leach, Naik expires September, 1997 [Page 7]
INTERNET-DRAFT CIFS/1.0 03/19/97
the server name, and the remainder as the relative name -- in this
example, "corpserver" and "\public\policy.doc" respectively.
In the path name "x:\policy.doc" the client could use "x" as an index
into a table that contains a server name and a file name prefix. If the
contents of such a table for "x" were "corpserver" and "\public", then
the server name and relative name would be the same as in the previous
example.
2.2 Server Name Resolution
Like server name determination, how the client resolves the name to the
transport address of the server is outside the scope of this
specification. All that is required by CIFS is that a CIFS client MUST
have some means to resolve the name of a CIFS server to a transport
address, and that a CIFS server MUST register its name with a name
resolution service known its clients.
Some examples of name resolution mechanisms include: using the Domain
Name System (DNS) [1,2], and using NETBIOS name resolution (see RFC 1001
and RFC 1002 [3,4]). The server name can also be specified as the string
form of an IPv4 address in the usual dotted decimal notation, e.g.,
"157.33.135.101"; in this case, "resolution" consists of converting to
the 32 bit IPv4 address.
Which method is used is configuration dependent; the default SHOULD be
DNS to encourage interoperability over the Internet.
Note: The name resolution mechanism used may place constraints on the
form of the server name; for example, in the case of NETBIOS, the server
name must be 15 characters or less, and be upper case.
2.3 Sample Message Flow
The following illustrates a typical message exchange sequence for a
client connecting to a user level server, opening a file, reading its
data, closing the file, and disconnecting from the server. Note: using
the CIFS request batching mechanism (called the "AndX" mechanism), the
second to sixth messages in this sequence can be combined into one, so
there are really only three round trips in the sequence, and the last
one can be done asynchronously by the client.
Leach, Naik expires September, 1997 [Page 8]
INTERNET-DRAFT CIFS/1.0 03/19/97
Client Command Server Response
========================== =========================================
SMB_COM_NEGOTIATE Must be the first message sent by client
to the server. Includes a list of SMB
dialects supported by the client. Server
response indicates which SMB dialect
should be used.
SMB_COM_SESSION_SETUP_ANDX Transmits the user's name and credentials
to the server for verification.
Successful server response has Uid field
set in SMB header used for subsequent
SMBs on behalf of this user.
SMB_COM_TREE_CONNECT Transmits the name of the disk share the
client wants to access. Successful
server response has Tid field set in SMB
header used for subsequent SMBs referring
to this resource.
SMB_COM_OPEN Transmits the name of the file, relative
to Tid, the client wants to open.
Successful server response includes a
file id (Fid) the client should supply
for subsequent operations on this file.
SMB_COM_READ Client supplies Tid, Fid, file offset,
and number of bytes to read. Successful
server response includes the requested
file data.
SMB_COM_CLOSE Client closes the file represented by Tid
and Fid. Server responds with success
code.
SMB_COM_TREE_DISCONNECT Client disconnects from resource
represented by Tid.
2.4 Message Format
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.
2.4.1 Notation
This specification 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 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.
Leach, Naik expires September, 1997 [Page 9]
INTERNET-DRAFT CIFS/1.0 03/19/97
2.4.2 SMB header
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
ULONG Unused; // Not used
ULONG Unused2;
} 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 have identical format up to the ParameterWords fields.
Different SMBs have a different number and interpretation of
ParameterWords and Buffer. All reserved fields in the SMB header must
be zero.
o Command is the operation code which this SMB is requesting, or
responding to.
o Status.DosError.ErrorClass and Status.DosError.Error are set by the
server and combine to give the error code of any failed server
operation. If the client is capable of receiving 32 bit error
Leach, Naik expires September, 1997 [Page 10]
INTERNET-DRAFT CIFS/1.0 03/19/97
returns, the status is returned in Status.Status instead. When an
error is returned, the server may choose to return only the header
portion of the response SMB.
o Flags and Flags2 contain bits which, depending on the negotiated
protocol dialect, indicate various client capabilities.
o PidHigh is used in the NtCreateAndX request SMB
[The PidHigh field is described in the SNIA CIFS Technical
Reference as an extention to the Pid field, to provide for
32-bit Process IDs. There is nothing in the description of the
NT_CREATE_ANDX message that suggests a special usage of the
PidHigh field in that request. Most likely, the field isn't used
at all and should always be zero.]
o Tid identifies the subdirectory, or "tree", on the server which the
client is accessing. SMBs which do not reference a particular tree
should set Tid to 0xFFFF.
[In practice, a value of 0x0000 is used
rather than 0xFFFF *except* when sending an SMB_COM_ECHO. The value
0xFFFF is listed as the NULL Tid in several references, including
Microsoft's LAN Manager
1.0 documentation.]
[Regarding the Uid: Microsoft's LAN Manager
1.0 documentation states that -2 (0xFFFE, presumably) is a reserved
Uid value and should not be used. See page 4 of the Microsoft document.
(I have not seen any other reference to this value with respect to the Uid
field. --crh)]
o Pid is the caller's process id, and is generated by the client to
uniquely identify a process within the client computer.
o Mid is reserved for multiplexing multiple messages on a single
transport connection. A response message will always contain the
same value as the corresponding request message. The client MUST not
have multiple outstanding requests to a server with the same Mid.
2.5 CIFS Protocol Dialect Negotiation
The first message sent from an CIFS client to an CIFS server must be one
whose Command field is SMB_COM_NEGOTIATE. The format of this client
request includes an array of NULL terminated strings indicating the
dialects of the CIFS protocol which the client supports. The server
compares this list against the list of dialects the server supports and
returns the index of the chosen dialect in the response message.
2.6 Message Transport
When using a reliable connection oriented transport, the CIFS protocol
makes no higher level attempts to ensure sequenced delivery of messages
between the client and server. The transport must have some mechanism
to detect failures of either the client or server node, and to deliver
such an indication to the client or server software so they can clean up
state. When a reliable transport connection from a client terminates,
all work in progress by that client is terminated by the server and all
resources open by that client on the server are closed. Message
transport is done using NETBIOS session service (see section 5.3 of RFC
1001 and section 4.3 of RFC 1002).
2.6.1 Connection Establishment
After the server name has been resolved to an IP address, then a
connection to the server needs to be established if one has not already
been set up. Connection establishment is done using the Call primitive
of the NETBIOS session service, which requires the client to provide a
"calling name" and a "called name". The calling name is not significant
in CIFS, except that an identical name from the same transport address
Leach, Naik expires September, 1997 [Page 11]
INTERNET-DRAFT CIFS/1.0 03/19/97
is assumed to represent the same client; the called name is always
"*SMBSERVER ". Over TCP, the Call primitive results in a "Session
Request" packet to port 139 (see section 4.3.2 of RFC 1002).
2.6.1.1 Backwards compatability
If a CIFS client wishes to interoperate with older SMB servers, then if
the Call is rejected by the server, it can retry with a new called name.
The choice of the new called name depends on the name resolution
mechanism used. If DNS was used, the called name should be constructed
from the first component of the server's DNS name, truncated to 15
characters if necessary, and then padded to 16 characters with blank (20
hex) characters. If NETBIOS was used, then the called named is just the
NETBIOS name. If these fail, then a NETBIOS "Adapter Status" request may
be made to obtain the server's NETBIOS name, and the connection
establishment retried with that as the called name.
2.6.2 Server-side Connection Procedures
A CIFS server MUST register a NETBIOS Listen that accepts any calling
name on the name "*SMBSERVER ".
In addition, if it wishes to support older SMB clients, it MAY have a
NETBIOS name and register a Listen on that name.
2.6.3 Connection Management
Once a connection is established, the rules for reliable transport
connection dissolution are:
o If a server receives a transport establishment request from a client
with which it is already conversing, the server may terminate all
other transport connections to that client. This is to recover from
the situation where the client was suddenly rebooted and was unable
to cleanly terminate its resource sharing activities with the server.
o A server may drop the transport connection to a client at any time if
the client is generating malformed or illogical requests. However,
wherever possible the server should first return an error code to the
client indicating the cause of the abort.
o If a server gets a hard error on the transport (such as a send
failure) the transport connection to that client may be aborted.
o A server may terminate the transport connection when the client has
no open resources on the server, however, we recommend that the
termination be performed only after some time has passed or if
resources are scarce on the server. This will help performance in
that the transport connection will not need to be reestablished if
activity soon begins anew. Client software is expected to be able to
automatically reconnect to the server if this happens..
Leach, Naik expires September, 1997 [Page 12]
INTERNET-DRAFT CIFS/1.0 03/19/97
2.7 Opportunistic Locks
Network performance can be increased if the client can locally buffer
file data. For example, the client does not have to write information
into a file on the server if the client knows that no other process is
accessing the data. Likewise, the client can buffer read-ahead data
from the file if the client knows that no other process is writing the
data.
The mechanism which allows clients to dynamically alter their buffering
strategy in a consistent manner is knows as "opportunistic locks", or
oplocks for short. Versions of the CIFS file sharing protocol including
and newer than the "LANMAN1.0" dialect support oplocks.
There are three different types of oplocks:
o An exclusive oplock allows a client to open a file for exclusive
access and allows the client to perform arbitrary buffering
o A batch oplock allows a client to keep a file open on the server even
though the local accessor on the client machine has closed the file.
o A Level II oplock indicates there are multiple readers of a file, and
no writers. Level II oplocks are supported if the negotiated dialect
is NT LM 0.12 or later.
When a client opens a file, it requests the server to grant it a
particular type of oplock on the file. The response from the server
indicates the type of oplock granted to the client. The client uses the
granted oplock type to adjust its buffering policy.
The SMB_COM_LOCKING_ANDX SMB is used to convey oplock break and response
information.
2.7.1 Exclusive Oplocks
If a client is granted an exclusive oplock, it may buffer lock
information, read-ahead data, and write data on the client because the
client knows that it is the only accessor to the file. The basic
protocol is that the redirector on the client opens the file requesting
that an oplock be given to the client. If the file is open by anyone
else, then the client is refused the oplock and no local buffering may
be performed on the local client. This also means that no readahead may
be performed to the file, unless the redirector knows that it has the
read ahead range locked. If the server grants the exclusive oplock, the
client can perform certain optimizations for the file such as buffering
lock, read, and write data.
Leach, Naik expires September, 1997 [Page 13]
INTERNET-DRAFT CIFS/1.0 03/19/97
The exclusive oplock protocol is:
Client <-> Server
A B
============== =========== === ================================
Open ("foo") ->
<- Open OK. Exclusive oplock
granted.
Open("foo") ->
<- oplock break to A
lock(s) ->
<- lock(s) response(s)
write(s) ->
<- write(s) response(s)
close or done ->
<- open response to B
As can be seen, when client A opens the file, it can request an
exclusive oplock. Provided no one else has the file open on the server,
then the oplock is granted to client A. If, at some point in the
future, another client, such as client B, requests an open to the same
file, then the server must have client A break its oplock. Breaking the
oplock involves client A sending the server any lock or write data that
it has buffered, and then letting the server know that it has
acknowledged that the oplock has been broken. This synchronization
message informs the server that it is now permissible to allow client B
to complete its open.
Client A must also purge any readahead buffers that it has for the file.
This is not shown in the above diagram since no network traffic is
needed to do this.
2.7.2 Batch Oplocks
Batch oplocks are used where common programs on a client behave in such
a way that causes the amount of network traffic on a wire to go beyond
an acceptable level for the functionality provided by the program.
For example, the command processor executes commands from within a
command procedure by performing the following steps:
o Opening the command procedure.
o Seeking to the "next" line in the file.
o Reading the line from the file.
o Closing the file.
o Executing the command.
Leach, Naik expires September, 1997 [Page 14]
INTERNET-DRAFT CIFS/1.0 03/19/97
This process is repeated for each command executed from the command
procedure file. As is obvious, this type of programming model causes an
inordinate amount of processing of files, thereby creating a lot of
network traffic that could otherwise be curtailed if the program were to
simply open the file, read a line, execute the command, and then read
the next line.
Batch oplocking curtails the amount of network traffic by allowing the
client to skip the extraneous open and close requests. When the command
processor then asks for the next line in the file, the client can either
ask for the next line from the server, or it may have already read the
data from the file as readahead data. In either case, the amount of
network traffic from the client is greatly reduced.
If the server receives either a rename or a delete request for the file
that has a batch oplock, it must inform the client that the oplock is to
be broken. The client can then change to a mode where the file is
repeatedly opened and closed.
The batch oplock protocol is:
Client <-> Server
A B
=========== ============ ==== ===============================
Open("foo") ->
<- Open OK. Batch oplock granted.
Read ->
<- data
<close>
<open>
<seek>
-> read
<- data
<close>
Open("foo") ->
<- Oplock break to A
Close ->
<- Close OK to A
<- Open OK to B
When client A opens the file, it can request an oplock. Provided no one
else has the file open on the server, then the oplock is granted to
client A. Client A, in this case, keeps the file open for its caller
across multiple open/close operations. Data may be read ahead for the
caller and other optimizations, such as buffering locks, can also be
performed.
When another client requests an open, rename, or delete operation to the
server for the file, however, client A must cleanup its buffered data
and synchronize with the server. Most of the time this involves
actually closing the file, provided that client A's caller actually
Leach, Naik expires September, 1997 [Page 15]
INTERNET-DRAFT CIFS/1.0 03/19/97
believes that he has closed the file. Once the file is actually closed,
client B's open request can be completed.
2.7.3 Level II Oplocks
Level II oplocks allow multiple clients to have the same file open,
providing that no client is performing write operations to the file.
This is important for many environments because most compatibility mode
opens from down-level clients map to an open request for shared
read/write access to the file. While it makes sense to do this, it also
tends to break oplocks for other clients even though neither client
actually intends to write to the file.
The Level II oplock protocol is:
Client <-> Server
A B
=========== =========== ==== ====================================
Open("foo") ->
<- Open OK. Exclusive oplock granted.
Read ->
<- data
Open("foo") ->
<- Break to Level II oplock to A
lock(s) ->
<- lock(s) response(s)
done ->
<- Open OK. Oplock II oplock granted
to B
This sequence of events is very much like an exclusive oplock. The
basic difference is that the server informs the client that it should
break to a level II lock when no one has been writing the file. That
is, client A, for example, may have opened the file for a desired access
of READ, and a share access of READ/WRITE. This means, by definition,
that client A will not performed any writes to the file.
When client B opens the file, the server must synchronize with client A
in case client A has any buffered locks. Once it is synchronized,
client B's open request may be completed. Client B, however, is
informed that he has a level II oplock, rather than an exclusive oplock
to the file.
In this case, no client that has the file open with a level II oplock
may buffer any lock information on the local client machine. This
allows the server to guarantee that if any write operation is performed,
it need only notify the level II clients that the lock should be broken
without having to synchronize all of the accessors of the file.
The level II oplock may be broken to none, meaning that some client that
had the file opened has now performed a write operation to the file.
Leach, Naik expires September, 1997 [Page 16]
INTERNET-DRAFT CIFS/1.0 03/19/97
Because no level II client may buffer lock information, the server is in
a consistent state. The writing client, for example, could not have
written to a locked range, by definition. Read ahead data may be
buffered in the client machines, however, thereby cutting down on the
amount of network traffic required to the file. Once the level II
oplock is broken, however, the buffering client must flush its buffers
and degrade to performing all operations on the file across the network.
No oplock break response is expected from a client when the server
breaks a client from level II to none.
2.8 Security Model
Each server makes a set of resources available to clients on the
network. A resource being shared may be a directory tree, named pipe,
printer, etc. So far as clients are concerned, the server has no
storage or service dependencies on any other servers; a client considers
the server to be the sole provider of the file (or other resource) being
accessed.
The CIFS protocol requires server authentication of users before file
accesses are allowed, and each server authenticates its own users. A
client system must send authentication information to the server before
the server will allow access to its resources.
The CIFS protocol defines two methods which can be selected by the
server for security: share level and user level:
o A share level server makes some directory on a disk device (or other
resource) available. An optional password may be required to gain
access. Thus any user on the network who knows the name of the
server, the name of the resource and the password has access to the
resource. Share level security servers may use different passwords
for the same shared resource with different passwords allowing
different levels of access.
o A user level server makes some directory on a disk device (or other
resource) available but in addition requires the client to provide a
user name and corresponding user password to gain access. User level
servers are preferred over share level servers for any new server
implementation, since organizations generally find user level servers
easier to administer as employees come and go. User level servers may
use the account name to check access control lists on individual
files, or may have one access control list that applies to all files
in the directory.
When a user level server validates the account name and password
presented by the client, an identifier representing that authenticated
instance of the user is returned to the client in the Uid field of the
response SMB. This Uid must be included in all further requests made on
behalf of the user from that client. A share level server returns no
useful information in the Uid field.
Leach, Naik expires September, 1997 [Page 17]
INTERNET-DRAFT CIFS/1.0 03/19/97
The user level security model was added after the original dialect of
the CIFS protocol was issued, and subsequently some clients may not be
capable of sending account name and passwords to the server. A server
in user level security mode communicating with one of these clients will
allow a client to connect to resources even if the client has not sent
account name and password information:
1. If the client's computer name is identical to an account-name known
on the server, and if the password supplied to connect to the shared
resource matches that account's password, an implicit "user logon" will
be performed using those values.
If the above fails, the server may fail the request or assign a default
account name of its choice.
2. The value of Uid in subsequent requests by the client will be ignored
and all access will be validated assuming the account name selected
above.
2.9 Resource Share/Access Example
The following examples illustrate a possible command line user interface
for a server to offer a disk resource, and for a client to connect to
and use that resource.
a) NET SHARE
The NET SHARE command, when executed on the server, specifies a
directory name to be made available to clients on the network. A share
name must be given, and this name is presented by clients wishing to
access the directory.
Examples:
NET SHARE src=c:\dir1\src "bonzo"
assigns password bonzo to all files within directory c:\dir1\src
and its subdirectories with the share name src being the name used
to connect to this resource.
NET SHARE c=c:\ " " RO
NET SHARE work=c:\work "flipper" RW
offers read-only access to everything on the C drive. Offers read-
write access to all files within the C:\work directory and its
subdirectories.
The above example is appropriate for servers operating as a share level
server. A user level server would not require the permissions or
password, since the combination of the client's account name and
specific access control lists on files is sufficient to govern access.
Leach, Naik expires September, 1997 [Page 18]
INTERNET-DRAFT CIFS/1.0 03/19/97
b) NET USE
Clients can gain access to one or more offered directories 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"
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).
For user level servers, the client would not provide a password with the
NET USE command.
The client software must remember the drive identifier supplied with the
NET USE request and associate it with the Tid value returned by the
server in the SMB header. Subsequent requests using this Tid must
include only the pathname relative to the connected subtree as the
server treats the subtree as the root directory (virtual root). When
the user references one of the remote drives, the client software looks
through its list of drives for that node and includes the tree id
associated with this drive in the Tid field of each request.
Note that one shares a directory and all files underneath that directory
are then affected. If a particular file is within the range of multiple
shares, connecting to any of the share 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 with more restrictive
permissions.
2.10 Authentication
An CIFS server keeps an encrypted form of a client's password. To gain
authenticated access to server resources, the server sends a challenge
to the client, which the client responds to in a way that proves it
knows the client's password.
Authentication makes use of DES encryption [5] in block mode. We denote
the DES encryption function as E(K,D), which accepts a seven byte key
(K) and an eight byte data block (D) and produces an eight byte
Leach, Naik expires September, 1997 [Page 19]
INTERNET-DRAFT CIFS/1.0 03/19/97
encrypted data block as its value. If the data to be encrypted is
longer than eight bytes, the encryption function is applied to each
block of eight bytes in sequence and the results are appended together.
If the key is longer than seven bytes, the data is first completely
encrypted using the first seven bytes of the key, then the second seven
bytes, etc., appending the results each time. In other words, to
encrypt the 16 byte quantity D0D1 with the 14 byte key K0K1,
E(K0K1,D0D1) = E(K0,D0)E(K0,D1)E(K1,D0)E(K1,D1)
The EncryptionKey field in the SMB_COM_NEGPROT response contains an 8
byte challenge denoted below as "C8", chosen to be unique to prevent
replay attacks; the client responds with a 24 byte response denoted
"P24", and computed as described below. (Note: the name "EncryptionKey"
is historical -- it doesn't actually hold an encryption key.)
Clients send the response to the challenge in the SMB_COM_TREE_CONNECT,
SMB_COM_TREE_CONNECT_ANDX, and/or SMB_COM_SESSION_SETUP_ANDX request
which follows the SMB_COM_NEGPROT message exchange. The server must
validate the response by performing the same computations the client did
to create it, and ensuring the strings match.
If the comparisons fail, the client system may be incapable of
encryption; if so the string may be the user password in clear text.
The server should try to validating the string as though it were the
unencrypted password.
The SMB field used to store the response depends upon the request:
o Password in SMB_COM_TREE_CONNECT
o Password in SMB_COM_TREE_CONNECT_ANDX
o AccountPassword in SMB_COM_SESSION_SETUP_ANDX
(Note: again, the names are historical, and do not reflect this usage.)
The contents of the response to the challenge depends on the CIFS
dialect, as outlined in the following sections:
2.10.1 Pre NT LM 0.12
o The client and server both compute
P16 = E(P14,S8)
and
P24 = E(P21,C8)
where:
Leach, Naik expires September, 1997 [Page 20]
INTERNET-DRAFT CIFS/1.0 03/19/97
o P14 is a 14 byte string containing the user's password in clear
text, upper cased, padded with spaces
[The 14 byte string is padded with nul bytes, not spaces.]
o S8 is an eight byte string whose value is available from Microsoft
upon request.
[The string is: "KGS!@#$%", or {0x4b, 0x47, 0x53, 0x21,
0x40, 0x23, 0x24, 0x25} in hexidecimal.]
o P21 is a twenty one byte string obtained by appending five null
bytes to the string P16, just computed
o C8 is the value of the challenge sent in the EncryptionKey field in
the SMB_COM_NEGPROT response for this connection.
2.10.2 NT LM 0.12
The client and server both compute
P16 = MD4(U(PN))
and
P24 = E(P21, C8)
where:
o PN is a string containing the user's password in clear text, case
sensitive, no maximum length
o U(x) of an ASCII string "x" is that string converted to Unicode
o MD4(x) of an octet string "x" is the 16 byte MD4 message digest [6]
of that string
o P21 and C8 are as above.
2.11 Distributed Filesystem (DFS) Support
Protocol dialects of NT LM 0.12 and later support distributed filesystem
operations. The distributed filesystem gives a way for this protocol to
use a single consistent file naming scheme which may span a collection
of different servers and shares. The distributed filesystem model
employed is a referral - based model. This protocol specifies the manner
in which clients receive referrals.
The client can set a flag in the request SMB header indicating that the
client wants the server to resolve this SMB's paths within the DFS known
to the server. The server attempts to resolve the requested name to a
file contained within the local directory tree indicated by the TID of
the request and proceeds normally. If the request pathname resolves to a
file on a different system, the server returns the following error:
STATUS_DFS_PATH_NOT_COVERED - the server does not support the part
of the DFS namespace needed to resolved the pathname in the request.
Leach, Naik expires September, 1997 [Page 21]
INTERNET-DRAFT CIFS/1.0 03/19/97
The client should request a referral from this server for further
information.
A client asks for a referral with the TRANS2_DFS_GET_REFERRAL request
containing the DFS pathname of interest. The response from the server
indicates how the client should proceed.
The method by which the topological knowledge of the DFS is stored and
maintained by the servers is not specified by this protocol.
3 SMB Message Formats and Data Types
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 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.
3.1.1 Flags field
This field contains 8 individual flags, numbered from least significant
to most significant, and have the following meanings:
Leach, Naik expires September, 1997 [Page 22]
INTERNET-DRAFT CIFS/1.0 03/19/97
Bit Meaning Earliest
=== ================================================ Dialect
============
0 When set (returned) from the server in the LANMAN1.0
SMB_COM_NEGOTIATE response SMB, this bit
indicates that the server supports the "sub
dialect" consisting of the LockandRead and
WriteandUnlock protocols defined later in this
document.
1 When on (on an SMB request being sent to the
server), the client guarantees that there is a
receive buffer posted such that a send without
acknowledgment can be used by the server to
respond to the client's request.
2 Reserved (must be zero).
3 When on, all pathnames in this SMB must be LANMAN1.0
treated as caseless. When off, the pathnames
are case sensitive.
4 When on (in SMB_COM_SESSION_SETUP_ANDX defined LANMAN1.0
later in this document), all paths sent to the
server by the client are already canonicalized.
This means that file/directory names are in
upper case, are valid characters, . and .. have
been removed, and single backslashes are used as
separators.
5 When on (in SMB_COM_OPEN, SMB_COM_CREATE and LANMAN1.0
SMB_COM_CREATE_NEW), this indicates that the
client is requesting that the file be
"opportunistically" locked if this process 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 corresponding response
SMB to indicate to the client that the oplock
request was granted. See the discussion of
"oplock" in the sections defining the
SMB_COM_OPEN_ANDX and SMB_COM_LOCKING_ANDX
protocols later in this document (this bit has
the same function as bit 1 of Flags if the
SMB_COM_OPEN_ANDX SMB).
6 When on (in core protocols SMB_COM_OPEN_ANDX, LANMAN1.0
SMB_COM_CREATE and SMB_COM_CREATE_NEW), this
indicates that the server should notify the
client on any action which can modify the file
(delete, setattrib, rename, etc.) by another
client. If not set, the server need only notify
the client about another open request by a
different client. See the discussion of
"oplock" in the sections defining the
SMB_COM_OPEN_ANDX and SMB_COM_LOCKING_ANDX SMBs
later in this document (this bit has the same
function as bit 2 of smb_flags of the
SMB_COM_OPEN_ANDX SMB). Bit6 only has meaning
Leach, Naik expires September, 1997 [Page 23]
INTERNET-DRAFT CIFS/1.0 03/19/97
if bit5 is set..
7 When on, this SMB is being sent from the server PC NETWORK
in response to a client request. The Command PROGRAM 1.0
field usually contains the same value in a
protocol request from the client to the server
as in the matching response from the server to
the client. This bit unambiguously
distinguishes the command request from the
command response.
3.1.2 Flags2 Field
This field contains six individual flags, numbered from least
significant bit to most significant bit, which are defined below. Flags
which not defined must be set to zero.
Bit Meaning Earliest
=== =============================================== Dialect
============
0 If set in a request, the server may return long
components in path names in the response.
1 If set, the client is aware of extended
attributes.
12 If set, any request pathnames in this SMB NT LM 0.12
should be resolved in the Distributed File
System.
13 If set, indicates that a read will be permitted
if the client does not have read permission but
does have execute permission. This flag is
only useful on a read request.
14 If set, specifies that the returned error code NT LM 0.12
is a 32 bit error code in Status.Status.
Otherwise the Status.DosError.ErrorClass and
Status.DosError.Error fields contain the DOS-
style error information. When passing NT
status codes is negotiated, this flag should be
set for every SMB.
15 If set, any fields of datatype STRING in this NT LM 0.12
SMB message are encoded as UNICODE. Otherwise,
they are in ASCII.
3.1.3 Tid Field
Tid represents an instance of an authenticated connection to a server
resource. Tid is returned by the server to the client when the client
successfully connects to a resource, and the client uses Tid in
subsequent requests referring to the resource.
If the server is executing in share level security mode, Tid is the only
thing used to allow access to the shared resource. Thus if the user is
able to perform a successful connection to the server specifying the
appropriate netname and passwd (if any) the resource may be accessed
Leach, Naik expires September, 1997 [Page 24]
INTERNET-DRAFT CIFS/1.0 03/19/97
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 security mode, access
to the resource is based on the Uid (validated on the
SMB_COM_SESSION_SETUP_ANDX request) and the Tid is NOT associated with
access control but rather merely defines the resource (such as the
shared directory tree).
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.
[In practice, a value of 0x0000 is often used instead of 0xFFFF.
Windows/9x systems will not respond to an SMB_COM_ECHO unless there is a
valid TID *or* a TID of 0xFFFF is used.]
3.1.4 Pid Field
Pid uniquely identifies a client process. Clients inform servers of the
creation of a new process by simply introducing a new Pid value into the
dialogue for new processes.
In the core protocol, the SMB_COM_PROCESS_EXIT SMB was used to indicate
the catastrophic termination of a process on the client. In the single
tasking DOS system, it was possible for hard errors to occur causing the
destruction of the process with files remaining open. Thus a
SMB_COM_PROCESS_EXIT SMB was sent for this occurrence to allow the
server to close all files opened by that process.
In the LANMAN 1.0 and newer dialects, no SMB_COM_PROCESS_EXIT SMB is
sent. The client operating system must ensure that the appropriate
close and cleanup SMBs 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 transport
connection and Tid. There is no process creation SMB sent to the
server; it is up to the client to ensure only valid client processes
gain access to Fids (and Tids). On SMB_COM_TREE_DISCONNECT (or when the
client and server session is terminated) the server will invalidate any
files opened by any process on that client.
3.1.5 Mid Field
Clients using the LANMAN 1.0 and newer dialects will typically be
multitasked and allow multiple asynchronous input/output requests per
task. Therefore a 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.
Regardless of negotiated dialect, the server is responsible for ensuring
that every response contains the same Mid and Pid values as its request.
The client may then use the Mid and Pid values for associating requests
Leach, Naik expires September, 1997 [Page 25]
INTERNET-DRAFT CIFS/1.0 03/19/97
and responses and may have up to the negotiated number of requests
outstanding at any time to a particular server.
3.1.6 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 is 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.1.7 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 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.1.8 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.
Identifier Description Value
=============== ========================= =====
Data Block See Below 1
Dialect Null terminated String 2
Pathname Null terminated String 3
ASCII Null terminated String 4
Variable block See Below 5
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
Leach, Naik expires September, 1997 [Page 26]
INTERNET-DRAFT CIFS/1.0 03/19/97
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:
o The protocol strings in the Negotiate SMB request.
o The service name string in the Tree Connect And X 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 an WordCount nor
ByteCount of value 0 at the end of a message may be omitted.
3.2 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.
Leach, Naik expires September, 1997 [Page 27]
INTERNET-DRAFT CIFS/1.0 03/19/97
3.3 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.4 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.
Leach, Naik expires September, 1997 [Page 28]
INTERNET-DRAFT CIFS/1.0 03/19/97
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.5 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;
Leach, Naik expires September, 1997 [Page 29]
INTERNET-DRAFT CIFS/1.0 03/19/97
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.6 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 (???)
Leach, Naik expires September, 1997 [Page 30]
INTERNET-DRAFT CIFS/1.0 03/19/97
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.7 Access Mask Encoding
typedef ULONG ACCESS_MASK;
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 Meaning
0 Specific rights. Contains the access mask specific to the
through object type associated with the mask.
15
16 Standard rights. Contains the object's standard access rights
through and can be a combination of the following predefined flags:
23
Bit Flag Meaning
16 DELETE Delete access
17 READ_CONTROL Read access to the owner, group, and
discretionary access-control list (ACL) of the
security descriptor
18 WRITE_DAC Write access to the discretionary access-
control list (ACL)
19 WRITE_OWNER Write access to owner
20 SYNCHRONIZE Windows NT: Synchronize access
Bits Meaning
Leach, Naik expires September, 1997 [Page 31]
INTERNET-DRAFT CIFS/1.0 03/19/97
24 Access system security (ACCESS_SYSTEM_SECURITY). This flag is
not a typical access type. It is used to indicate access to a
system ACL. This type of access requires the calling process
to have a specific privilege.
25 Maximum allowed (MAXIMUM_ALLOWED)
26 Reserved
through
27
28 Generic all (GENERIC_ALL)
29 Generic execute (GENERIC_EXECUTE)
30 Generic write (GENERIC_WRITE)
31 Generic read (GENERIC_READ)
3.8 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.9 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.
Leach, Naik expires September, 1997 [Page 32]
INTERNET-DRAFT CIFS/1.0 03/19/97
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.10 File Attribute Encoding
When SMB messages exchange file attribute information, it is encoded in
16 bits as:
Value Description
======= =====================
0x01 Read only file
0x02 Hidden file
0x04 System file
0x08 Volume
0x10 Directory
0x20 Archive file
others Reserved - must be 0
3.11 Extended File Attribute Encoding
The extended file attributes is a 32 bit value composed of attributes
and flags.
Leach, Naik expires September, 1997 [Page 33]
INTERNET-DRAFT CIFS/1.0 03/19/97
Any combination of the following attributes is acceptable, except all
other file attributes override FILE_ATTR_NORMAL:
Name Value Meaning
==== ===== =======
ATTR_ARCHIVE 0x020 The file has not been archived since it was
last modified. Applications use this
attribute to mark files for backup or
removal.
ATTR_COMPRESSED 0x800 The file or directory is compressed. For a
file, this means that all of the data in the
file is compressed. For a directory, this
means that compression is the default for
newly created files and subdirectories.
ATTR_NORMAL 0x080 The file has no other attributes set. This
attribute is valid only if used alone.
ATTR_HIDDEN 0x002 The file is hidden. It is not to be included
in an ordinary directory listing.
ATTR_READONLY 0x001 The file is read only. Applications can read
the file but cannot write to it or delete it.
ATTR_TEMPORARY 0x100 The file is temporary
ATTR_DIRECTORY 0x010 The file is a directory
ATTR_SYSTEM 0x004 The file is part of or is used exclusively by
the operating system.
Leach, Naik expires September, 1997 [Page 34]
INTERNET-DRAFT CIFS/1.0 03/19/97
Any combination of the following flags is acceptable:
Name Value Meaning
==== ===== =======
WRITE_THROUGH 0x80000000 Instructs the operating system to write
through any intermediate cache and go
directly to the file. The operating
system can still cache write
operations, but cannot lazily flush
them.
NO_BUFFERING 0x20000000 Requests the server to open the file
with no intermediate buffering or
caching; the server is not obliged to
honor the request. An application must
meet certain requirements when working
with files opened with
FILE_FLAG_NO_BUFFERING. File access
must begin at offsets within the file
that are integer multiples of the
volume's sector size; and must be for
numbers of bytes that are integer
multiples of the volume's sector size.
For example, if the sector size is 512
bytes, an application can request reads
and writes of 512, 1024, or 2048 bytes,
but not of 335, 981, or 7171 bytes.
RANDOM_ACCESS 0x10000000 Indicates that the application intends
to access the file randomly. The server
MAY use this flag to optimize file
caching.
SEQUENTIAL_SCAN 0x08000000 Indicates that the file is to be
accessed sequentially from beginning to
end. Windows uses this flag to optimize
file caching. If an application moves
the file pointer for random access,
optimum caching may not occur; however,
correct operation is still guaranteed.
Specifying this flag can increase
performance for applications that read
large files using sequential access.
Performance gains can be even more
noticeable for applications that read
large files mostly sequentially, but
occasionally skip over small ranges of
bytes.
DELETE_ON_CLOSE 0x04000000 Requests that the server is delete the
file immediately after all of its
handles have been closed.
BACKUP_SEMANTICS 0x02000000 Indicates that the file is being opened
or created for a backup or restore
operation. The server SHOULD allow the
client to override normal file security
checks, provided it has the necessary
permission to do so.
Leach, Naik expires September, 1997 [Page 35]
INTERNET-DRAFT CIFS/1.0 03/19/97
POSIX_SEMANTICS 0x01000000 Indicates that the file is to be
accessed according to POSIX rules. This
includes allowing multiple files with
names differing only in case, for file
systems that support such naming. (Use
care when using this option because
files created with this flag may not be
accessible by applications written for
MS-DOS, Windows 3.x, or Windows NT.)
3.12 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:
o The embedded command does not repeat the SMB header information.
Rather the next SMB starts at the WordCount field.
o 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.
o 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.
o 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.
o 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.
o 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.
o 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.
Leach, Naik expires September, 1997 [Page 36]
INTERNET-DRAFT CIFS/1.0 03/19/97
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
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 which failed. In all cases the error information are
returned in 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
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.13 "Transaction" Style Subprotocols
SMB_COM_TRANSACTION performs a symbolically named transaction. This
transaction is known only by a name (no file handle used).
SMB_COM_TRANSACTION2 likewise performs a transaction, but a word
parameter is used to identify the transaction instead of a name.
SMB_COM_NT_TRANSACTION is used for commands that potentially need to
transfer a large amount of data (greater than 64K bytes).
Leach, Naik expires September, 1997 [Page 37]
INTERNET-DRAFT CIFS/1.0 03/19/97
3.13.1 SMB_COM_TRANSACTION and SMB_COM_TRANSACTION2 Formats
Primary Client Request Description
=============================== ====================================
Command SMB_COM_TRANSACTION or
SMB_COM_TRANSACTION2
UCHAR WordCount; Count of parameter words; value =
(14 + SetupCount)
USHORT TotalParameterCount; Total parameter bytes being sent
USHORT TotalDataCount; Total data bytes being sent
USHORT MaxParameterCount; Max parameter bytes to return
USHORT MaxDataCount; Max data bytes to return
UCHAR MaxSetupCount; Max setup words to return
UCHAR Reserved;
USHORT Flags; Additional information:
bit 0 - also disconnect TID in TID
bit 1 - one-way transaction (no
response)
ULONG Timeout;
USHORT Reserved2;
USHORT ParameterCount; Parameter bytes sent this buffer
USHORT ParameterOffset; Offset (from header start) to
Parameters
USHORT DataCount; Data bytes sent this buffer
USHORT DataOffset; Offset (from header start) to data
UCHAR SetupCount; Count of setup words
UCHAR Reserved3; Reserved (pad above to word)
USHORT Setup[SetupCount]; Setup words (# = SetupWordCount)
USHORT ByteCount; Count of data bytes
STRING Name[]; Name of transaction (NULL if
SMB_COM_TRANSACTION2)
UCHAR Pad[]; Pad to SHORT or LONG
UCHAR Parameters[ Parameter bytes (# = ParameterCount)
ParameterCount];
UCHAR Pad1[]; Pad to SHORT or LONG
UCHAR Data[ DataCount ]; Data bytes (# = DataCount)
Interim Server Response Description
=============================== ====================================
UCHAR WordCount; Count of parameter words = 0
USHORT ByteCount; Count of data bytes = 0
Leach, Naik expires September, 1997 [Page 38]
INTERNET-DRAFT CIFS/1.0 03/19/97
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 Parameter bytes (# = ParameterCount)
Parameters[ParameterCount];
UCHAR Pad1[]; Pad to SHORT or LONG
UCHAR Data[DataCount]; Data bytes (# = DataCount)
Leach, Naik expires September, 1997 [Page 39]
INTERNET-DRAFT CIFS/1.0 03/19/97
Server Response Description
=============================== ====================================
UCHAR WordCount; Count of data bytes; value = 10 +
SETUPCOUNT
USHORT TotalParameterCount; Total parameter bytes being sent
USHORT TotalDataCount; Total data bytes being sent
USHORT Reserved;
USHORT ParameterCount; Parameter bytes sent this buffer
USHORT ParameterOffset; Offset (from header start) to
Parameters
USHORT ParameterDisplacement; Displacement of these Parameter
bytes
USHORT DataCount; Data bytes sent this buffer
USHORT DataOffset; Offset (from header start) to data
USHORT DataDisplacement; Displacement of these data bytes
UCHAR SetupCount; Count of setup words
UCHAR Reserved2; Reserved (pad above to word)
USHORT Setup[SetupWordCount]; Setup words (# = SetupWordCount)
USHORT ByteCount; Count of data bytes
UCHAR Pad[]; Pad to SHORT or LONG
UCHAR Parameter bytes (# = ParameterCount)
Parameters[ParameterCount];
UCHAR Pad1[]; Pad to SHORT or LONG
UCHAR Data[DataCount]; Data bytes (# = DataCount)
3.13.2 SMB_COM_NT_TRANSACTION Formats
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 Parameter bytes
Parameters[ParameterCount];
UCHAR Pad2[]; Pad to LONG
UCHAR Data[DataCount]; Data
bytes
Leach, Naik expires September, 1997 [Page 40]
INTERNET-DRAFT CIFS/1.0 03/19/97
Interim Server Response Description
=============================== ====================================
UCHAR WordCount; Count of parameter words = 0
USHORT ByteCount; Count of data bytes = 0
Secondary Client Request Description
=============================== ====================================
UCHAR WordCount; Count of parameter words = 18
UCHAR Reserved[3]; MBZ
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 Parameter bytes
Parameters[ParameterCount];
UCHAR Pad2[]; Pad to LONG
UCHAR Data[DataCount]; Data bytes
Leach, Naik expires September, 1997 [Page 41]
INTERNET-DRAFT CIFS/1.0 03/19/97
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 Parameter bytes
Parameters[ParameterCount];
UCHAR Pad2[]; Pad to SHORT or LONG
UCHAR Data[DataCount]; Data bytes
3.13.3 Functional Description
The SMB_COM_TRANSACTION command's scope includes named pipes and
mailslots. Where the resource is unidirectional (such as class 2 writes
to mailslots), bit1 of Flags in the request can be set indicating that
no response is needed. The other transactions accommodate IOCTL
requests and file system requests which require the transfer of an
extended attribute list.
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 protocol, but by client and
server implementations. 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.
Leach, Naik expires September, 1997 [Page 42]
INTERNET-DRAFT CIFS/1.0 03/19/97
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 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, 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.
If a connectionless transport is being used, the transaction requests
must be properly sequenced in the Connectionless.SequenceNumber SMB
header field. The Mid of any secondary client requests must match the
Mid of the primary client request. The server responds to each request
Leach, Naik expires September, 1997 [Page 43]
INTERNET-DRAFT CIFS/1.0 03/19/97
piece except the last one with a response indicating that the server is
ready for the next piece. The last piece is responded to with the first
piece of the result data. The client then sends an
SMB_COM_TRANSACTION_SECONDARY SMB with ParameterDisplacement set to the
number of parameter bytes received so far and DataDisplacement set to
the number of data bytes received so far and ParameterCount,
ParameterOffset, DataCount, and DataOffset set to zero (0). The server
responds with the next piece of the transaction result. The process is
repeated until all of the response information has been received. When
the transaction has been completed, the client must send another
sequenced command (such as an SMB_COM_ECHO) to the server to allow the
server to know that the final piece was received and that resources
allocated to the transaction command may be released.
The flow 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) which are 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:
Leach, Naik expires September, 1997 [Page 44]
INTERNET-DRAFT CIFS/1.0 03/19/97
Client <-> Server
=============================== ==== ==============================
Primary TRANSACTION request ->
<- Interim Server Response
Secondary TRANSACTION request 1 ->
Secondary TRANSACTION request 2 ->
Secondary TRANSACTION request N ->
<- TRANSACTION response 1
<- TRANSACTION response 2
<- TRANSACTION response m
The flow for the transaction protocol when the request parameters and
data does all fit in a single buffer is:
Client <-> Server
=============================== ==== ==============================
Primary TRANSACTION request ->
<- TRANSACTION response 1
<- TRANSACTION response 2
<- TRANSACTION response m
The flow for the transaction protocol over a connectionless transport
is:
1. The client sends the primary client request identifying the total
bytes (both parameters and data) which are 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 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.
The server responds with an interim server response. 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).
6. The client responds with a transaction secondary request. The
server sends back more response data. This step is repeated until all
result bytes have been returned.
7. The client sends a sequenced request to the server such as
SMB_COM_ECHO
Leach, Naik expires September, 1997 [Page 45]
INTERNET-DRAFT CIFS/1.0 03/19/97
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.14 Valid SMB Requests by Negotiated Dialect
The following SMB messages may be exchanged by CIFS clients and servers
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:
Leach, Naik expires September, 1997 [Page 46]
INTERNET-DRAFT CIFS/1.0 03/19/97
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 SMB_COM_READ_BULK
SMB_COM_WRITE_BULK SMB_COM_WRITE_BULK_DATA
4 SMB Requests
This section lists the "best practice" SMB requests -- ones that would
permit a client to exercise full CIFS functionality and optimum
performance when interoperating with a server speaking the latest
dialect as of this writing ("NT LM 0.12").
Note that, as of this writing, no existing client restricts itself to
only these requests, so no useful server can be written that supports
just them. The classification is provided so that future clients will be
written to permit future servers to be simpler.
Leach, Naik expires September, 1997 [Page 47]
INTERNET-DRAFT CIFS/1.0 03/19/97
4.1 Session Requests
4.1.1 NEGOTIATE: Negotiate Protocol
Client Request Description
============================ =======================================
UCHAR WordCount; Count of parameter words = 0
USHORT ByteCount; Count of data bytes; min = 2
struct {
UCHAR BufferFormat; 0x02 -- Dialect
UCHAR DialectName[]; ASCII null-terminated string
} Dialects[];
The Client sends a list of dialects that it can communicate with. The
response is a selection of one of those dialects (numbered 0 through n)
or -1 (hex FFFF) indicating that none of the dialects were acceptable.
The negotiate message is binding on the virtual circuit and must be
sent. One and only one negotiate message may be sent, subsequent
negotiate requests will be rejected with an error response and no action
will be taken.
The protocol does not impose any particular structure to the dialect
strings. Implementers of particular protocols may choose to include,
for example, version numbers in the string.
If the server does not understand any of the dialect strings, or if PC
NETWORK PROGRAM 1.0 is the chosen dialect, the response format is
Server Response Description
============================ =======================================
UCHAR WordCount; Count of parameter words = 1
USHORT DialectIndex; Index of selected dialect
USHORT ByteCount; Count of data bytes = 0
Leach, Naik expires September, 1997 [Page 48]
INTERNET-DRAFT CIFS/1.0 03/19/97
If the chosen dialect is greater than core up to and including
LANMAN2.1, the protocol response format is
Server Response Description
============================ =======================================
UCHAR WordCount; Count of parameter words = 13
USHORT DialectIndex; Index of selected dialect
USHORT SecurityMode; Security mode:
bit 0: 0 = share, 1 = user
bit 1: 1 = use challenge/response
authentication
USHORT MaxBufferSize; Max transmit buffer size (>= 1024)
USHORT MaxMpxCount; Max pending multiplexed requests
USHORT MaxNumberVcs; Max VCs between client and server
USHORT RawMode; Raw modes supported:
bit 0: 1 = Read Raw supported
bit 1: 1 = Write Raw supported
ULONG SessionKey; Unique token identifying this session
SMB_TIME ServerTime; Current time at server
SMB_DATE ServerDate; Current date at server
USHORT ServerTimeZone; Current time zone at server
USHORT EncryptionKeyLength; MBZ if this is not LM2.1
USHORT Reserved; MBZ
USHORT ByteCount Count of data bytes
UCHAR EncryptionKey[]; The challenge encryption key
STRING PrimaryDomain[]; The server's primary domain
MaxBufferSize is the size of the largest message which the client can
legitimately send to the server
If bit0 of the Flags field is set in the negotiate response, this
indicates the server supports the SMB_COM_LOCK_AND_READ and
SMB_COM_WRITE_AND_UNLOCK client requests.
If the SecurityMode field indicates the server is running in user mode,
the client must send appropriate SMB_COM_SESSION_SETUP_ANDX requests
before the server will allow the client to access resources. If the
SecurityMode fields indicates the client should use challenge/response
authentication, the client should use the authentication mechanism
specified in section 2.10.
Clients should submit no more than MaxMpxCount distinct unanswered SMBs
to the server when using multiplexed reads or writes (see sections 5.13
and 5.25)
Clients using the "MICROSOFT NETWORKS 1.03" dialect use a different
form of raw reads than documented here, and servers are better off
setting RawMode in this response to 0 for such sessions.
If the negotiated dialect is "DOS LANMAN2.1" or "LANMAN2.1", then
PrimaryDomain string should be included in this response.
Leach, Naik expires September, 1997 [Page 49]
INTERNET-DRAFT CIFS/1.0 03/19/97
If the negotiated dialect is NT LM 0.12, the response format is
Server Response Description
========================== =========================================
UCHAR WordCount; Count of parameter words = 17
USHORT DialectIndex; Index of selected dialect
UCHAR SecurityMode; Security mode:
bit 0: 0 = share, 1 = user
bit 1: 1 = encrypt passwords
USHORT MaxMpxCount; Max pending multiplexed requests
USHORT MaxNumberVcs; Max VCs between client and server
ULONG MaxBufferSize; Max transmit buffer size
ULONG MaxRawSize; Maximum raw buffer size
ULONG SessionKey; Unique token identifying this session
ULONG Capabilities; Server capabilities
ULONG SystemTimeLow; System (UTC) time of the server (low).
ULONG SystemTimeHigh; System (UTC) time of the server (high).
USHORT ServerTimeZone; Time zone of server (min from UTC)
UCHAR EncryptionKeyLength; Length of encryption key.
USHORT ByteCount; Count of data bytes
UCHAR EncryptionKey[]; The challenge encryption key
UCHAR OemDomainName[]; The name of the domain (in OEM chars)
In addition to the definitions above, MaxBufferSize is the size of the
largest message which the client can legitimately send to the server.
If the client is using a connectionless protocol, MaxBufferSize must be
set to the smaller of the server's internal buffer size and the amount
of data which can be placed in a response packet.
MaxRawSize specifies the maximum message size the server can send or
receive for SMB_COM_WRITE_RAW or SMB_COM_READ_RAW.
Connectionless clients must set Sid to 0 in the SMB request header.
Leach, Naik expires September, 1997 [Page 50]
INTERNET-DRAFT CIFS/1.0 03/19/97
Capabilities allows the server to tell the client what it supports. The
bit definitions are:
Capability Name Encoding Meaning
==================== ======== =====================================
CAP_RAW_MODE 0x0001 The server supports SMB_COM_READ_RAW
and SMB_COM_WRITE_RAW
CAP_MPX_MODE 0x0002 The server supports SMB_COM_READ_MPX
and SMB_COM_WRITE_MPX
CAP_UNICODE 0x0004 The server supports Unicode strings
CAP_LARGE_FILES 0x0008 The server supports large files with
64 bit offsets
CAP_NT_SMBS 0x0010 The server supports the SMBs
particular to the NT LM 0.12 dialect
CAP_RPC_REMOTE_APIS 0x0020 The sever supports remote API
requests via RPC
CAP_STATUS32 0x0040 The server can respond with 32 bit
status codes in Status.Status
CAP_LEVEL_II_OPLOCKS 0x0080 The server supports level 2 oplocks
CAP_LOCK_AND_READ 0x0100 The server supports the
SMB_COM_LOCK_AND_READ SMB
CAP_NT_FIND 0x0200
CAP_DFS 0x1000 This server is DFS aware
4.1.1.1 Errors
SUCCESS/SUCCESS
ERRSRV/ERRerror
4.1.2 SESSION_SETUP_ANDX: Session Setup
This SMB is used to further "Set up" the session normally just
established via the negotiate protocol.
One primary function is to perform a "user logon" in the case where the
server is in user level security mode. The Uid in the SMB header is set
by the client to be the userid desired for the AccountName and validated
by the AccountPassword.
Leach, Naik expires September, 1997 [Page 51]
INTERNET-DRAFT CIFS/1.0 03/19/97
If the negotiated protocol is prior to NT LM 0.12, the format of
SMB_COM_SESSION_SETUP_ANDX is:
Client Request Description
============================== =====================================
UCHAR WordCount; Count of parameter words = 10
UCHAR AndXCommand; Secondary (X) command; 0xFF = none
UCHAR AndXReserved; Reserved (must be 0)
USHORT AndXOffset; Offset to next command WordCount
USHORT MaxBufferSize; Client maximum buffer size
USHORT MaxMpxCount; Actual maximum multiplexed pending
requests
USHORT VcNumber; 0 = first (only), nonzero=additional
VC number
ULONG SessionKey; Session key (valid iff VcNumber != 0)
USHORT PasswordLength; Account password size
ULONG Reserved; Must be 0
USHORT ByteCount; Count of data bytes; min = 0
UCHAR AccountPassword[]; Account Password
STRING AccountName[]; Account Name
STRING PrimaryDomain[]; Client's primary domain
STRING NativeOS[]; Client's native operating system
STRING NativeLanMan[]; Client's native LAN Manager type
and the response is:
Server Response Description
================================== =================================
UCHAR WordCount; Count of parameter words = 3
UCHAR AndXCommand; Secondary (X) command; 0xFF =
none
UCHAR AndXReserved; Reserved (must be 0)
USHORT AndXOffset; Offset to next command WordCount
USHORT Action; Request mode:
bit0 = logged in as GUEST
USHORT ByteCount; Count of data bytes
STRING NativeOS[]; Server's native operating system
STRING NativeLanMan[]; |