[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]
Versions: 00 01 02 03 04 05 06 07 08 09 10 11
12
INTERNET-DRAFT Christopher R. Hertel
draft-crhertel-smb-url-04.txt Samba Team
Expires July 8, 2003 January 8, 2003
SMB Filesharing URL Scheme
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
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 obsoleted 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."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html
Discussions regarding this document and the SMB URL scheme should
take place on the jcifs@samba.org mailing list. Information on
joining this mailing list can be found at:
http://lists.samba.org/listinfo/jcifs/.
Abstract
The Server Message Block (SMB) protocol is one of the most widely
used network filesystem protocols in existence. This document
describes a format for an SMB Uniform Resource Locator (SMB URL).
The SMB URL can be used to indicate SMB workgroups, servers, shares,
files, inter-process communications pipes, print queues, and devices;
the objects in the SMB network filesystem space.
Hertel Expires July 8, 2003 [Page 1]
INTERNET-DRAFT SMB URL January 8, 2003
Table of Contents
1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. URL Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1 NBT Transport. . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1.1 nbt_name . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.2 auth_domain. . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.3 nbt_context. . . . . . . . . . . . . . . . . . . . . . . . 6
2.2. Relative SMB URLs. . . . . . . . . . . . . . . . . . . . . . . 7
2.3. Use of the 'port' Field. . . . . . . . . . . . . . . . . . . . 7
3. Relationship Between the URL and the UNC Formats. . . . . . . . . . 7
4. Authentication and Security Considerations. . . . . . . . . . . . . 8
5. SMB URL Semantics . . . . . . . . . . . . . . . . . . . . . . . . . 8
6. Character Encoding Issues . . . . . . . . . . . . . . . . . . . . . 9
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . 9
8. References. . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
9. Author's Address. . . . . . . . . . . . . . . . . . . . . . . . . .10
Hertel Expires July 8, 2003 [Page 2]
INTERNET-DRAFT SMB URL January 8, 2003
1. Introduction
The Server Message Block protocol (SMB) was created in the 1980's by
Dr. Barry Feigenbaum at IBM Corporation. It was later extended by
IBM, 3Com, Intel, and Microsoft. SMB is now also known by the name
CIFS, which stands for Common Internet FileSystem.
SMB was originally carried via a proprietary network transport, the
interface to which was called NetBIOS (Network Basic Input Output
System). Two Internet RFCs ([RFC1001], [RFC1002]) were published
which describe a mechanism for implementing the NetBIOS API on top
of TCP and UDP. Those RFCs are now known collectively as Internet
Standard #19 (STD 19), and the protocol they describe is known as
NBT (for NetBIOS over TCP).
SMB is intended to be transport independent. In addition to
transport via NBT, SMB may be carried directly on TCP/IP without the
intervening NetBIOS emulation layer.
Several attempts have been made to document and even standardize the
SMB protocol ([XOPENSMB], [ONET], [SNIACIFS]), yet the further
development of SMB remains under the control of Microsoft. Despite
its proprietary nature, the workings of SMB are sufficiently well
known that SMB filesharing has been successfully implemented by
several third-party commercial vendors, and in Open Source. SMB
server and client software is available for a wide variety of
operating system platforms. The very large number of systems which
support this form of filesharing make an SMB URL scheme both
practical and desirable.
1.1. Purpose
This document does not attempt to describe the implementation of the
SMB protocol itself. The goal is to present the syntax of the SMB
URL, and explain how it maps to the features of SMB.
Hertel Expires July 8, 2003 [Page 3]
INTERNET-DRAFT SMB URL January 8, 2003
2. URL Definition
An SMB URL is identified by one of two scheme names: "smb" or "cifs".
Both are considered to be equivalent.
The following grammar defines the syntax of the SMB URL. It is
based upon the grammar given in Appendix A of [RFC2396], and amended
by [RFC2732]. Refer to those RFCs for any token definitions missing
from the grammar below.
smb_URL = ( SMB_absURL | SMB_relURL )
smb_absURL = scheme "://"
[ smb_net_path ] [ "?" [ nbt_context ] ]
smb_relURL = abs_path | rel_path
scheme = "smb" | "cifs"
smb_net_path = smb_server [ abs_path ]
smb_server = [ smb_userinfo "@" ] smb_srv_name [ ":" port ]
smb_srv_name = nbt_name | host
nbt_name = netbiosname [ "." scope_id ]
netbiosname = 1*( netbiosnamec ) *( netbiosnamec | "*" )
netbiosnamec = ( alphanum | escaped | ":" | "=" | "+" | "$" |
"," | "-" | "_" | "!" | "~" | "'" | "(" | ")" )
scope_id = domainlabel *( "." domainlabel )
smb_userinfo = [ auth_domain ";" ] userinfo
auth_domain = smb_srv_name
nbt_context = nbt_param *(";" nbt_param )
nbt_param = ( ( "NBNS=" | "WINS=" ) host )
| ( "CALLED=" netbiosname )
| ( "CALLING=" netbiosname )
| ( ( "WORKGROUP=" | "NTDOMAIN=" ) nbt_name )
2.1 NBT Transport
Many of the syntax elements given in the above grammar are
requirements of the NBT transport. NBT creates a virtual NetBIOS LAN
on top of TCP and UDP, and provides mechanisms for mapping NetBIOS
names to IP addresses, but these mechanisms may require some
additional contextual information.
Hertel Expires July 8, 2003 [Page 4]
INTERNET-DRAFT SMB URL January 8, 2003
2.1.1 nbt_name
The SMB URL supports the use of NetBIOS names and Scope IDs for
identifying SMB servers. When included as part of an SMB URL, the
syntax of the NetBIOS name is a superset of the syntax of a DNS
domain name label. For example:
smb://jcifs/
Syntactically, the string "jcifs" in the smb_srv_name field of
the above string may be seen as either a DNS host name
(unqualified), or as a NetBIOS name. The underlying SMB
implementation must determine the namespace of the name. (This
is a common problem in SMB implementations and is typically solved
by first attempting to resolve the name as a NetBIOS name and, if
that fails, as a DNS host name.)
Likewise, given:
smb://jcifs.samba.org/
the string "jcifs.samba.org" may be interpreted either as a
qualified DNS name, or as a NetBIOS name with appended Scope ID.
A NetBIOS name may include many characters which are not permitted
in a domainlabel, including some non-printing characters. Octet
values excluded by the syntax must be escaped. A NetBIOS name may
not begin with an asterisk character. The total length of the
NetBIOS name (with escape characters translated to their octet
equivalents) may not exceed 15 octets.
The mapping of NetBIOS names to IP addresses is described in
[RFC1001] and [RFC1002].
2.1.2 auth_domain
The auth_domain string is passed to the underlying SMB layer for
interpretation. It is used to specify the SMB authentication
authority, which is known as a "Domain Controller".
Hertel Expires July 8, 2003 [Page 5]
INTERNET-DRAFT SMB URL January 8, 2003
2.1.3 nbt_context
The nbt_context may be used to provide additional information
about the NBT transport layer and related support servers.
Client systems implementing the SMB URL will interpret the
nbt_context entries locally. The nbt_params are specified as
key/value pairs. For example:
smb://jcifs/?WORKGROUP=WORLDWIDEHQ;NBNS=127.0.0.1
In the above example, the WORKGROUP keyword is assigned a value of
"WORLDWIDEHQ", and the NBNS keyword is assigned a value of
"127.0.0.1".
The following keywords are defined:
NBNS: Specifies the NetBIOS Name Server to be used for
point-to-point NBT Name Resolution. The NBNS may
be specified using a DNS hostname or an IP address.
See [RFC1001] for information on the NBNS.
WINS: A synonym for NBNS.
CALLED: Specifies the NetBIOS name of the SMB server. This
value is only used with NBT transport. It is
required by the NBT Session Request message (see
[RFC1002], Section 4.3.2).
If NBT transport is used, and the CALLED name is
not specified within the URL string, the underlying
SMB implementation must deduce the CALLED name from
available information.
CALLING: Specifies the NetBIOS name of the client. This
value is only used with NBT transport. It is
required by the NBT Session Request message (see
[RFC1002], Section 4.3.2).
If NBT transport is used, and the CALLING name is
not specified within the URL string, the underlying
SMB implementation must generate a suitable name.
WORKGROUP: Specifies workgroup membership. Workgroups are
used to organize resources. By specifying the
NetBIOS name of the workgroup, a list of member SMB
servers can be obtained. The workgroup concept was
developed after the publication of [RFC1001] and
[RFC1002], and is not described in those documents.
NTDOMAIN: A synonym for WORKGROUP.
Hertel Expires July 8, 2003 [Page 6]
INTERNET-DRAFT SMB URL January 8, 2003
NODETYPE: One of "B", "P", "M", or "H". These represent the
different mechanisms by which a NetBIOS name may
be resolved to an IP address on an NBT network.
The first three types are defined in STD 19. In
"H" mode the NBNS is queried before a broadcast
query is sent; the opposite of "M" mode.
BROADCAST: The IPv4 broadcast address to which to send
broadcast NBT name queries. This may be used on
multi-homed hosts to specify one of the connected
subnets.
SCOPEID: The syntax allows the NBT Scope to be specified as
part of the NBT name. It is preferable, however,
to specify the Scope ID as part of the NBT context.
Although all of the keywords and values are shown in upper case,
case is not significant.
2.2. Relative SMB URLs
Relative SMB URLs are supported and are resolved according to the
rules defined in [RFC2396] section 5.2.
2.3. Use of the 'port' Field
STD 19 includes a mechanism for retargeting Session Service
connections to alternate ports (see [RFC1001], section 16.1.1.)
which means that non-standard ports may be used for SMB transport.
The URL port field may be used to specify an alternate service
port for SMB over either NBT or native TCP transport.
3. Relationship Between the URL and the UNC Formats.
Some operating systems support a format known as Universal Naming
Convention (UNC). UNC is a means for identifying network resources.
SMB is one of the protocols supported by UNC.
In general, a UNC string specifying a resource available via SMB
protocol can be converted into an SMB URL string by simply adding
the "smb:" or "cifs:" prefix and reversing the direction of all of
the separating slashes. For example:
UNC form URL form
----------------------------- ---------------------------------
\\ubiqx\src\ smb://ubiqx/src/
\\ubiqx\src\jcifs\ smb://ubiqx/src/jcifs/
\\ubiqx\src\jcifs\SmbURL.java smb://ubiqx/src/jcifs/SmbURL.java
Hertel Expires July 8, 2003 [Page 7]
INTERNET-DRAFT SMB URL January 8, 2003
4. Authentication and Security Considerations
SMB authentication can be categorized as follows:
o None
o Share-based
o User-based
o Authentication Server-based (NT Domain and Kerberos)
The authentication mechanism to be used is negotiated during
client/server session setup. Client applications, therefore, are
aware of the server's authentication requirements and may prompt for
appropriate input (password, username, authentication domain). By
prompting for authentication information, an application ensures that
such information is entered by the user in a controlled manner, and
that security measures (if any) such as password encryption or
password hash generation are applied by the SMB protocol handler
before the data are transmitted.
Some authentication values may also be provided within the SMB URL
string. In particular, the following fields may be included in the
URL:
auth_domain - The authentication domain (single-signon database
server) to use for authorization
userinfo - User account identifier (username)
These fields are all optional.
5. SMB URL Semantics
The primary purpose of the SMB URL is to specify resources made
available via the SMB protocol. One such resource is the list
of available servers. Under NBT, SMB Servers are organized into
Workgroups (also called NT Domains), and the list of available
Workgroups is also available.
smb://
-- No server has been specified. In this form, the URL should
interpreted as a request for a list of x Workgroups available
on the local LAN.
smb://server
-- This form provides an SMB server, but no share path. The
interpretation of this form is dependant upon the semantics
of the specified server name. If the name resolves to an
NBT Workgroup name, then this is a request for a list of
servers offering SMB services within the workgroup. Otherwise,
the name represents an SMB file server.
Hertel Expires July 8, 2003 [Page 8]
INTERNET-DRAFT SMB URL January 8, 2003
smb://neko@scred/src/jcifs/smb/SmbURL.java
-- Indicates file /src/jcifs/smb/SmbURL.java on node "scred". The
username "neko" is to be used when connecting to the share.
If the path is specified, then the URL cannot represent a
a request for Workgroup information.
6. Character Encoding Issues
The only restriction that STD 19 places on the octet values that may
be used in a NetBIOS name is that the name may not begin with an
asterisk ('*', ASCII value 0x2A). No other values are listed as
excluded in the RFCs. For historical reasons, however,
implementations generally disallow the use of a nul byte (0x00)
within a NetBIOS name. NetBIOS names are interpreted as a string of
octets, so common mutli-byte character sets cannot be used to form
NetBIOS names.
Octet values less than 128 (0x80) in a NetBIOS name are interpreted
as US-ASCII characters. Octet values above 127 are created using the
host's own codepage, and there is no protocol mechanism to specify
the code page in use. URL escape sequences should be used to
represent characters with Octet values above 127.
NetBIOS names, share names, and the directory paths and filenames
offered by an SMB server may all contain characters from outside the
7-bit US-ASCII character set. Applications MUST support the use of
the URL escape sequence as described in [RFC2396] to accommodate
octet values that represent non-US-ASCII characters.
7. Acknowledgments
The creation of this document would not have been possible without
the help and guidance of
Michael B. Allen
David Farmer
Roy T. Fielding
Steven French
Larry Masinter
Richard Sharpe
and the aggregate knowledge and wisdom of
The Samba Team
The jCIFS Team
The Samba-TNG Team
The SNIA CIFS Work Group
and the samba-technical mailing list participants.
Hertel Expires July 8, 2003 [Page 9]
INTERNET-DRAFT SMB URL January 8, 2003
8. References
[RFC1001] Karl Auerbach, et. al., "Protocol Standard For a NetBIOS
Service on a TCP/UDP Transport: Concepts and Methods", RFC
1001, March 1987.
[RFC1002] Karl Auerbach, et. al., "Protocol Standard For a NetBIOS
Service on a TCP/UDP Transport: Detailed Specifications",
RFC 1002, March 1987.
[RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC 2396,
August 1998.
[RFC2732] R. Hinden, B. Carpenter, L. Masinter, "Format for Literal
IPv6 Addresses in URL's", RFC 2732, December 1999.
[XOPENSMB] "Protocols for X/Open PC Interworking: SMB, Version 2",
ISBN 1-872630-45-6, The Open Group, October 1992.
[ONET] Microsoft Corporation, Intel Corporation, "Microsoft
Networks/OpenNET Filesharing Protocol", Document Version
2, Intel Part No. 138446, November 7, 1988.
[SNIACIFS] Storage Network Industry Association CIFS Documentation
Work Group, "Common Internet File System (CIFS) Technical
Reference", Version: CIFS-TR 1.0, March 1, 2002.
9. Author's Address
Christopher R. Hertel
University of Minnesota
Networking and Telecommunications
2218 University Avenue SE
Minneapolis, MN 55414-3029, USA
E'mail: crh@samba.org
crh@ubiqx.org
Hertel Expires July 8, 2003 [Page 10]
Html markup produced by rfcmarkup 1.129c, available from
https://tools.ietf.org/tools/rfcmarkup/