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]