[prev in list] [next in list] [prev in thread] [next in thread]
List: best-of-security
Subject: BoS: CIFS draft
From: Julian Assange <proff () suburbia ! net>
Date: 1996-06-25 16:31:26
[Download RAW message or body]
Network Working Group I. Heizer
Request for Comments: DRAFT P. Leach
Category: Informational D. Perry
Title: draft-heizer-cifs-v1-spec-00.txt Microsoft
June 13, 1996
Common Internet File System Protocol (CIFS/1.0)
Status of this Memo
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>.
Abstract
This document describes the CIFS file sharing protocol. 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.
Heizer, et al expires December 1996 [Page 1]
INTERNET-DRAFT CIFS/1.0 June 1996
Table of Contents
1. INTRODUCTION 6
1.1 Summary of features 6
1.1.1 File and printer access 7
1.1.2 File and record locking 7
1.1.3 Safe caching, read-ahead, and write-behind 7
1.1.4 File change notification 7
1.1.5 Protocol version negotiation 7
1.1.6 Extended attributes 7
1.1.7 Distributed replicated virtual volumes 8
1.1.8 Server name resolution via DNS 8
1.1.9 Batched requests 8
2. PROTOCOL OPERATION OVERVIEW 9
2.1 Server Name Determination 9
2.2 Server Name Resolution 9
2.3 SAMPLE MESSAGE FLOW 10
2.4 MESSAGE FORMAT 12
2.5 SMB PROTOCOL DIALECT NEGOTIATION 14
2.6 Message Transport 14
2.6.1 Reliable Connection Oriented Transports 15
2.6.2 Connectionless Transports 16
2.7 OPPORTUNISTIC LOCKS 20
2.7.1 Exclusive Oplocks 20
2.7.2 Batch Oplocks 22
2.7.3 Level II Oplocks 24
2.8 Security Model 25
2.9 Resource Share/Access Example 26
2.10 Authentication 28
2.10.1 Pre NT LM 0.12 29
2.10.2 NT LM 0.12 29
Heizer, et al expires December 1996 [Page 2]
INTERNET-DRAFT CIFS/1.0 June 1996
2.11 DISTRIBUTED FILESYSTEM (DFS) SUPPORT 30
3. SMB MESSAGES AND FORMATS 31
3.1 SMB HEADER 31
3.1.1 Flags field 32
3.1.2 Flags2 Field 33
3.1.3 Tid Field 34
3.1.4 Pid Field 35
3.1.5 Mid Field 35
3.1.6 Status Field 35
3.1.7 Timeouts 36
3.1.8 Data Buffer (BUFFER) and String Formats 36
3.2 FILE NAMES 37
3.3 WILDCARDS 38
3.4 DFS PATHNAMES 38
3.5 TIME AND DATE ENCODING 39
3.6 ACCESS MODE ENCODING 40
3.7 FILE ATTRIBUTE ENCODING 42
3.8 "ANDX" SMB MESSAGES 43
3.9 SMB MESSAGES 45
3.9.1 Valid SMB Messages by Negotiated Dialect 45
3.9.2 NEGOTIATE: Negotiate Protocol 47
3.9.3 SESSION_SETUP_ANDX: Session Setup And X 53
3.9.4 LOGOFF_ANDX: User Logoff And X 59
3.9.5 TREE_CONNECT: Tree Connect 60
3.9.6 TREE_CONNECT_ANDX: Tree Connect And X 62
3.9.7 TREE_DISCONNECT: Tree Disconnect 65
3.9.8 CREATE_DIRECTORY: Create Directory 66
3.9.9 DELETE_DIRECTORY: Delete Directory 67
3.9.10 CHECK_DIRECTORY: Check Directory 67
3.9.11 OPEN: Open File 68
3.9.12 CREATE: Create File 71
3.9.13 CLOSE: Close File 72
3.9.14 FLUSH: Flush File 73
3.9.15 DELETE: Delete File 74
3.9.16 RENAME: Rename File 75
3.9.17 QUERY_INFORMATION: Get File Attributes 77
3.9.18 SET_INFORMATION: Set File Attributes 78
3.9.19 READ: Read File 79
3.9.20 WRITE: Write Bytes 81
3.9.21 LOCK_BYTE_RANGE: Lock Bytes 83
Heizer, et al expires December 1996 [Page 3]
INTERNET-DRAFT CIFS/1.0 June 1996
3.9.22 UNLOCK_BYTE_RANGE: Unlock Bytes 85
3.9.23 CREATE_TEMPORARY: Create Temporary File 85
3.9.24 CREATE_NEW: Create File 87
3.9.25 PROCESS_EXIT: Process Exit 88
3.9.26 SEEK: Seek in File 89
3.9.27 SMB_QUERY_INFORMATION_DISK: Get Disk Attributes 90
3.9.28 SEARCH: Search Directory 92
3.9.29 OPEN_PRINT_FILE: Create Print Spool file 95
3.9.30 WRITE_PRINT_FILE: Write to Print File 96
3.9.31 CLOSE_PRINT_FILE: Close and Spool Print Job 98
3.9.32 GET_PRINT_QUEUE: Get Printer Queue Entries 98
3.9.33 LOCK_AND_READ: Lock and Read Bytes 101
3.9.34 WRITE_AND_UNLOCK: Write Bytes and Unlock Range 102
3.9.35 READ_RAW: Read Raw 104
3.9.36 READ_MPX: Read Block Multiplex 107
3.9.37 WRITE_RAW: Write Raw Bytes 109
3.9.38 WRITE_MPX: Write Block Multiplex 114
3.9.39 SET_INFORMATION2: Set File Information 117
3.9.40 QUERY_INFORMATION2: Get File Information 118
3.9.41 LOCKING_ANDX: Lock or UnLock Bytes 119
3.9.42 MOVE: Rename File 124
3.9.43 COPY: Copy File 126
3.9.44 ECHO: Ping the Server 128
3.9.45 WRITE_AND_CLOSE: Write Bytes and Close File 130
3.9.46 OPEN_ANDX: Open File And X 132
3.9.47 NT_CREATE_ANDX: Create File 137
3.9.48 READ_ANDX: Read Data 140
3.9.49 WRITE_ANDX: Write Bytes to file or resource 144
3.9.50 TRANSACTIONS 147
3.9.51 NT_CANCEL: Cancel request 218
3.9.52 FIND_CLOSE2: Close Search 218
4. SMB COMMAND CODES 220
5. ERROR CODES AND CLASSES 223
6. LEGAL NOTICE 230
7. REFERENCES 230
8. SECURITY CONSIDERATIONS 231
Heizer, et al expires December 1996 [Page 4]
INTERNET-DRAFT CIFS/1.0 June 1996
8.1 Share level protection 231
8.2 Plaintext Password Authentication 231
8.3 LANMAN 2.1 (and earlier) Challenge/Response 231
8.3.1 Known Plaintext Attacks 232
8.3.2 Small Key Space 232
8.3.3 Chosen Plaintext Attacks 232
8.3.4 Dictionary Attacks 232
8.3.5 Badly Chosen Passwords 232
8.4 NT LM 0.12 Challenge/Response 232
8.5 Other attacks 233
8.5.1 Hijack connections 233
8.5.2 Downgrade attack 233
8.5.3 Spoofing by Counterfeit Servers 233
8.5.4 Storing Passwords Safely 234
9. AUTHOR'S ADDRESSES 234
10. APPENDICES 235
10.1 APPENDIX A: SMB PROTOCOL DIALECT CONSTANTS 235
10.2 APPENDIX B: IPX ON CONNECTIONLESS TRANSPORT 236
10.2.1 Naming On Ipx 237
10.3 APPENDIX C: NAMED PIPES 238
10.3.1 Named Pipe Features 239
Heizer, et al expires December 1996 [Page 5]
INTERNET-DRAFT CIFS/1.0 June 1996
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 and printer 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 using DNS
o Batched requests
o Operates over connection-oriented or connection-less transports
o Unicode file names
Heizer, et al expires December 1996 [Page 6]
INTERNET-DRAFT CIFS/1.0 June 1996
1.1.1 File and printer access
The protocol supports the usual set of file operations: open, close,
read, write, and seek. Opening a printer resources as a file and writing
to it causes a print job to be queued.
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.
Heizer, et al expires December 1996 [Page 7]
INTERNET-DRAFT CIFS/1.0 June 1996
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
protocol uses referrals to transparently direct a client to the server
that stores it.
1.1.8 Server name resolution via DNS
The protocol supports resolving server names 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.
Heizer, et al expires December 1996 [Page 8]
INTERNET-DRAFT CIFS/1.0 June 1996
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 using a connection-oriented
transport and no connection has yet been made)
o Exchange SMB 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
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
Once the server name has been determined, then the client needs to
resolve that name to a transport address. This specification defines
three ways of doing so: using the Domain Name System (DNS) [1,2],
NETBIOS name resolution (see RFC 1001 and RFC 1002 [3,4]), or IPX naming
(see appendix B). Which method is used is configuration dependent; the
default is DNS to encourage interoperability over the Internet. The name
Heizer, et al expires December 1996 [Page 9]
INTERNET-DRAFT CIFS/1.0 June 1996
resolution mechanism used will place constraints on the form of the
server name. In the case of NETBIOS, the server name must be 15
characters or less, and be upper case.
The server name can also be specified as the string form an IPv4 address
in the usual dotted notation, e.g., "157.33.135.101" In this case,
"resolution" consists of converting to the 32 bit IPv4 address.
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 SMB 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.
Heizer, et al expires December 1996 [Page 10]
INTERNET-DRAFT CIFS/1.0 June 1996
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.
Heizer, et al expires December 1996 [Page 11]
INTERNET-DRAFT CIFS/1.0 June 1996
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. Multi-byte values are always
transmitted least significant byte first.
Heizer, et al expires December 1996 [Page 12]
INTERNET-DRAFT CIFS/1.0 June 1996
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 {
ULONG LowTime;
LONG HighTime;
} TIME;
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 NtStatus; // NT-style 32-bit error code
} Status;
UCHAR Flags; // Flags
USHORT Flags2; // More flags
union {
USHORT Pad[6]; // Ensure this section is 12
// bytes long
struct {
USHORT PidHigh; // High part of PID
// (NT Create And X)
ULONG Unused; // Not used
USHORT Sid; // Session ID
USHORT SequenceNumber; // Sequence number
} Connectionless; // IPX
};
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
Heizer, et al expires December 1996 [Page 13]
INTERNET-DRAFT CIFS/1.0 June 1996
PARAMETERWORDS and BUFFER. All reserved fields in the SMB header must
be zero. All quantities are sent in native Intel format.
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
returns, the status is returned in STATUS.NTSTATUS 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
o CONNECTIONLESS. SID, and CONNECTIONLESS.SEQUENCENUMBER are used when
the client to server connection is on a datagram oriented protocol
such as IPX.
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
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
Virtual Circuit (VC). A response message will always contain the
same value as the corresponding request message.
2.5 SMB PROTOCOL DIALECT NEGOTIATION
The first message sent from an SMB client to an SMB 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 SMB 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
Clients and servers can exchange messages over a NETBIOS reliable
connection oriented transport, or a connectionless transport.
Heizer, et al expires December 1996 [Page 14]
INTERNET-DRAFT CIFS/1.0 June 1996
2.6.1 Reliable Connection Oriented Transports
When using a reliable connection oriented transport, the SMB 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.
2.6.1.1 Connection Establishment
How the connection gets established depends on how the server name was
resolved to the transport address: with DNS, with an explicit IP
address, or with NETBIOS.
2.6.1.1.1 DNS
When using DNS, the server name is mapped onto an IP address and the
connection is established by using the session establishment protocol as
outlined in RFC 1001 and RFC 1002. The client should initiate the
session setup using a called name which is obtained by taking the first
component of the server name, converting it to upper case, and padding
it up to a length of 16 with banks (hex 20 value).
2.6.1.1.2 Explicit IP Address
The connection is established by using the session establishment
protocol as outlined in RFC 1001 and RFC 1002; the client should use
"*SMBSERVER " as the called name in the session establishment
protocol (since it does not know the server name).
2.6.1.1.3 NETBIOS
When using NETBIOS name resolution, the NETBIOS session establishment
protocol as outlined in RFC 1001 and RFC 1002 must also be used. The
NETBIOS name used for session establishment is the server name converted
to upper case and padded to a length of 16 with blanks (hex 20 value).
Server-side Connection Procedures
The server should register a listen on at least one of the following
names on the network using the NETBIOS name registration services. If
the server wishes to support clients that use NETBIOS name resolution,
it registers a 16 character name that is obtained by padding the server
machine name with additional blanks if required. If the server wishes
to support clients that use DNS name resolution, the name to register is
obtained by taking the first component of the server name and padding it
Heizer, et al expires December 1996 [Page 15]
INTERNET-DRAFT CIFS/1.0 June 1996
up to a length of 16 with blanks, and the 16th character of the name
must be a blank (20 hex). Note: while the local server name and the
registered DNS server name may differ, it usually makes administration
easier to have them the same.
If servers wish to allow access via explicit IP address, they should
register the name "*SMBSERVER " (padded to 16 characters with
blanks) as a local name in NETBIOS. This name must not be defended on
the network.
2.6.1.2 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..
2.6.2 Connectionless Transports
The SMB protocol can be run over connectionless transports such as IPX
and UDP/IP. Since connectionless transports do not support reliable
delivery, this has to be implemented in the SMB protocol itself when
utilizing such transports.
Unlike a traditional transport protocol, the connectionless SMB protocol
is asymmetric. Wherever possible, processing overhead has been moved
from the server to the client so that the server can scale to a large
number of clients efficiently. For example, the server does not
initiate retransmission of lost responses. It is entirely up to the
Heizer, et al expires December 1996 [Page 16]
INTERNET-DRAFT CIFS/1.0 June 1996
client to resend the request in the case of lost packets in either
direction.
The SMB header includes two fields specifically designed for use on
connectionless transports. "Sid" is the server's session ID and
"SequenceNumber" is the message sequence number. The Sid value is
generated by the server, and returned to the client in the
NegotiateProtocol response. The client must use this Sid value in all
future SMB exchanges with this server during this resource sharing
session. SequenceNumber is supplied by the client. A valid
SequenceNumber is either zero or one greater than the previous sequence
number sent by the client.
For sequenced commands, the server requires that the sequence numbers
progress in order, S, S+1, S+2, ... The sequence number wraps to one
(1) not zero. The wrap around progression is: 65534, 65535, 1, 2, ...
Out of sequence commands are ignored by the server.
For unsequenced commands (i.e. SequenceNumber is 0) the redirector must
use the Mid field to identify SMB responses. The redirector should take
steps to generate relatively unique values for Mid for each request. In
particular, the client must ensure that it never has two or more
distinct requests outstanding to the server whose SequenceNumbers are 0
and whose Mids are identical.
The client must limit the negotiated buffer size to the maximum MTU of
the connectionless transport. If desired, the client could dynamically
determine the maximum packet size by sending echo SMBs to the server
using various packet sizes and then selecting the largest size which
worked correctly.
For SMB operation over connectionless transports, commands are divided
into two classes: sequenced commands and unsequenced commands. Sequenced
commands are used for operations which cause a state change on the
server that cannot be repeated, and which have relatively few bytes in
the response. For example, file open/close or record locking.
Unsequenced commands are used for operations which can be performed as
many times as necessary with the same result each time or which have
multi-packet responses. For example, reading or writing to a disk file.
The client should must send all commands with a large response size as
unsequenced; such commands include file read and file search.
2.6.2.1 Errors specific to connectionless transport operation
If the response to a sequenced command is too large, the server will
fail the request with a Status.DosError.ErrorClass set to
SMB_ERR_CLASS_SERVER and Status.DosError.Error set to ERRerror. If the
Sid value is incorrect, the server will fail the request with a
Status.DosError.ErrorClass set to SMB_ERR_CLASS_SERVER and
Status.DosError.Error set to SMB_ERR_BAD_SID. If the server has an SMB
in progress which matches either SequenceNumber for sequenced commands
Heizer, et al expires December 1996 [Page 17]
INTERNET-DRAFT CIFS/1.0 June 1996
or Mid for unsequenced commands, it will respond with
Status.DosError.ErrorClass set to SMB_ERR_CLASS_SERVER and
Status.DosError.Error set to SMB_ERR_WORKING.
2.6.2.2 Transaction SMBs
The exceptions to the "large response requires unsequenced" rule are
transaction SMBs. These SMBs are used both to retrieve bulk data from
the server (EG: enumerate shares, etc.) and to change the server's state
(EG: add a new share, change file permissions, etc.) Transaction
requests are also unusual because they can have a multiple part request
and/or a multiple part response. For this reason, transactions are
handled as a set of sequenced commands to the server. Each part of a
request is sent as a sequenced command using the same Mid value and an
increasing Seq value. The server responds to each request 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 a 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
redirector must send another sequenced command (an echo SMB will do
fine) 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 is as follows, where (S) is the SequenceNumber, (N) is the
number of request packets to be sent from the client to the server, and
(M) is the number of response packets to be sent by the server to the
client:
Heizer, et al expires December 1996 [Page 18]
INTERNET-DRAFT CIFS/1.0 June 1996
Client <-> Server
======================= === ===========================
SMB(S) Transact ->
<- OK (S) send more data
[ repeat N-1 times:
SMB(S+1) Transact ->
secondary
<- OK (S+1) send more data
SMB(S+N-1)
]
<- OK (S+N-1) transaction
response (1)
[ repeat M-1 times:
SMB(S+N) Transact ->
secondary
<- OK (S+N) transaction
response (2)
SMB(S+N+M-2) Transact ->
secondary
<- OK (S+N+M-2] transaction
response (M)
]
SMB(S+N+M-1) Echo ->
<- OK (S+N+M-1) echoed
In order to allow the server to detect clients which have been powered
off, have crashed, etc., the client must send commands to the server
periodically if it has resources open on the server. If nothing has
been received from a client for awhile, the server will assume that the
client is no longer running and disconnect the client. This includes
closing any files that the client had open at the time and releasing any
Heizer, et al expires December 1996 [Page 19]
INTERNET-DRAFT CIFS/1.0 June 1996
resources being used on behalf of the client. Clients should at least
send an echo SMB to the server every four (4) minutes if there is
nothing else to send. The server will disconnect clients after a
configurable amount of time which cannot be less than five (5) minutes.
(Note: the NT server has a default timeout value of 15 minutes.)
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 SMB 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.
Oplocks are not supported over connectionless transports.
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
Heizer, et al expires December 1996 [Page 20]
INTERNET-DRAFT CIFS/1.0 June 1996
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.
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.
Heizer, et al expires December 1996 [Page 21]
INTERNET-DRAFT CIFS/1.0 June 1996
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.
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:
Heizer, et al expires December 1996 [Page 22]
INTERNET-DRAFT CIFS/1.0 June 1996
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
Heizer, et al expires December 1996 [Page 23]
INTERNET-DRAFT CIFS/1.0 June 1996
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
Heizer, et al expires December 1996 [Page 24]
INTERNET-DRAFT CIFS/1.0 June 1996
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.
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 SMB 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 SMB 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
Heizer, et al expires December 1996 [Page 25]
INTERNET-DRAFT CIFS/1.0 June 1996
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.
The user level security model was added after the original dialect of
the SMB 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
Heizer, et al expires December 1996 [Page 26]
INTERNET-DRAFT CIFS/1.0 June 1996
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.
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.
Heizer, et al expires December 1996 [Page 27]
INTERNET-DRAFT CIFS/1.0 June 1996
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 SMB 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
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.
Heizer, et al expires December 1996 [Page 28]
INTERNET-DRAFT CIFS/1.0 June 1996
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 SMB
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:
o P14 is a 14 byte string containing the user's password in clear text,
upper cased, padded with spaces
o S8 is an eight byte string whose value is available from Microsoft
upon request.
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)
Heizer, et al expires December 1996 [Page 29]
INTERNET-DRAFT CIFS/1.0 June 1996
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.
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.
Heizer, et al expires December 1996 [Page 30]
INTERNET-DRAFT CIFS/1.0 June 1996
3. SMB Messages And Formats
This section describes the entire set of SMB commands and responses
exchanged between SMB 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.
Heizer, et al expires December 1996 [Page 31]
INTERNET-DRAFT CIFS/1.0 June 1996
3.1.1 Flags field
This field contains 8 individual flags, numbered from least significant
to most significant, and have the following meanings:
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
acknowledgement 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
treated as caseless. When off, the pathnames
LANMAN1.0
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
Heizer, et al expires December 1996 [Page 32]
INTERNET-DRAFT CIFS/1.0 June 1996
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
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, the client knows how to handle names
which do not conform to the MS-DOS 8.3 naming
convention.
1 If set, the client is aware of extended
attributes
2 If set, SMB_FLAGS2_IS_LONG_NAME
12 If set, any request pathnames in this SMB NT LM 0.12
should be resolved in the Distributed File
Heizer, et al expires December 1996 [Page 33]
INTERNET-DRAFT CIFS/1.0 June 1996
System
13 If set, indicates that a read
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic