INTERNET-DRAFT Christopher R. Hertel draft-crhertel-smb-url-03.txt Samba Team Expires January 8, 2003 July 8, 2002 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. 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 January 8, 2003 [Page 1]
INTERNET-DRAFT SMB URL July 8, 2002 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 ntdomain . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.1.3 nbt_context. . . . . . . . . . . . . . . . . . . . . . . . 5 2.2. Relative SMB URLs. . . . . . . . . . . . . . . . . . . . . . . 6 2.3. Fragments. . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.4. Use of the 'port' Field. . . . . . . . . . . . . . . . . . . . 7 3. Relationship Between the URL and the UNC Formats. . . . . . . . . . 7 4. Authentication and Security Considerations. . . . . . . . . . . . . 7 5. SMB URL Semantics . . . . . . . . . . . . . . . . . . . . . . . . . 8 6. Character Encoding Issues . . . . . . . . . . . . . . . . . . . . . 9 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . 9 8. References. . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 9. Author's Address. . . . . . . . . . . . . . . . . . . . . . . . . .10 Appendix A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 Hertel Expires January 8, 2003 [Page 2]
INTERNET-DRAFT SMB URL July 8, 2002 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 January 8, 2003 [Page 3]
INTERNET-DRAFT SMB URL July 8, 2002 2. URL Definition An SMB URL may begin with one of two protocol prefixes: "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], as amended by [RFC2732]. Refer to those RFCs for any token definitions missing from the grammar below. smb_URL = ( SMB_absURL | SMB_relURL ) [ "#" fragment ] 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 = [ ntdomain ";" ] username [ ":" password ] ntdomain = *( unreserved | escaped | "&" | "=" | "+" | "$" | "," ) username = *( unreserved | escaped | "&" | "=" | "+" | "$" | "," ) password = *( unreserved | escaped | "&" | "=" | "+" | "$" | "," ) 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 January 8, 2003 [Page 4]
INTERNET-DRAFT SMB URL July 8, 2002 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 ntdomain The ntdomain 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". 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=OURGROUP;NBNS=127.0.0.1 In the above example, the WORKGROUP keyword is assigned a value of "OURGROUP" and NBNS is assigned a value of "127.0.0.1". Hertel Expires January 8, 2003 [Page 5]
INTERNET-DRAFT SMB URL July 8, 2002 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]. NTDOMAIN: A synonym for WORKGROUP. 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 permitted and are resolved according to the rules defined in [RFC2396] section 5.2. Hertel Expires January 8, 2003 [Page 6]
INTERNET-DRAFT SMB URL July 8, 2002 2.3. Fragments URL fragment references are permitted if the SMB URL resolves to a file or file-like object for which fragments have meaning. The meaning depends upon the interpretation of the designated object by the client application. For example, if the SMB URL indicates a file with HTML formatting, then the application (a web browser, for instance) may make use of fragment indicators. Otherwise, fragments are ignored. 2.4. Use of the 'port' Field STD 19 includes a mechanism for retargeting Session Service connections to alternate ports. (See [RFC1001], section 16.1.1.) That indicates that non-standard ports may be used. With that in mind, 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 the Universal Naming Convention (UNC) as 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 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 Hertel Expires January 8, 2003 [Page 7]
INTERNET-DRAFT SMB URL July 8, 2002 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. This specification also provides an authentication shorthand, though it does collide rather spectacularly with the warning in [RFC2396], section 3.2.2, which recommends against exactly this sort of thing. The shorthand mechanism takes the following general form: smb://<ntdomain>;<username>:<password>@<smb_srv_name>[:port] which allows the specification of: ntdomain - The authentication domain (single-signon database server) to use for authorization username - User account identifier password - Password These fields are all optional. This syntax is of particular use with command-line applications, batch scripts, configuration files, etc. That is, any situation in which a multi-step exchange between a user and an application is awkward or impossible. It is recommended that application authors consider carefully the security implications of providing support for this form. Likewise, authors of documentation in HTML or other formats are advised not to include authentication information in such documents, either within a URL string or otherwise. 5. SMB URL Semantics The primary purpose of the SMB URL is to specify resources made available via the SMB protocol. Ancillary protocols exist, however, which make it possible for SMB servers to announce or register the service they offer. The SMB URL provides access to those protocols as well as SMB itself. smb:// -- In this form, no SMB server has been specified. This should be taken as a request for a list of available servers. Under NBT transport, it is a request for the local browse list. smb://server -- Indicates an SMB server, but no share path. This is a request for a list of shared resources available on the specified server. Hertel Expires January 8, 2003 [Page 8]
INTERNET-DRAFT SMB URL July 8, 2002 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. 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. Octet values less than 128 (0x80) in a NetBIOS name are commonly interpreted as US-ASCII characters. Unfortunately, there is no convention or best practice for octet values 128 and above. 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. Applications which support extended character sets provide the end user with a means of hand-configuring compatible character sets. 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 members of the samba-technical mailing list. Hertel Expires January 8, 2003 [Page 9]
INTERNET-DRAFT SMB URL July 8, 2002 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 Appendix A. SMB Implementation Resources As of the time of this writing, there is no standard specification for the SMB protocol. An attempt was made to provide such a standard in 1996, when a draft specification was submitted to the IETF. That draft have since expired, but the Storage Network Industry Association (SNIA) has recently developed a new document based upon the earlier work ([SNIACIFS]). Hertel Expires January 8, 2003 [Page 10]