INTERNET-DRAFT Christopher R. Hertel draft-crhertel-smb-url-00.txt Samba Team Expires October 10, 2001 April 10, 2001 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 URL scheme for use with SMB over IETF STD #19 transport. The SMB URL scheme 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 October 10, 2001 [Page 1]
INTERNET-DRAFT SMB URL April 10, 2001 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. SMB URL Scheme . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1 Server Types . . . . . . . . . . . . . . . . . . . . . . . 3 2.2 SMB URL Semantics . . . . . . . . . . . . . . . . . . . . . 5 2.3 Relative SMB URLs . . . . . . . . . . . . . . . . . . . . . 5 2.4 Fragments . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.5 Queries . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. SMB Namespace . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Authentication and Security Considerations . . . . . . . . . . 7 5. SMB URL Examples . . . . . . . . . . . . . . . . . . . . . . . 7 6. Character Encoding Issues . . . . . . . . . . . . . . . . . . . 8 7. Use of the 'port' Field . . . . . . . . . . . . . . . . . . . . 8 8. URL Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 9 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 11. Author's Address . . . . . . . . . . . . . . . . . . . . . . . 10 Appendix A. SMB Implementation Resources . . . . . . . . . . . . . 10 Appendix B. Working with NetBIOS Names (Implementation Notes) . . 11 B.1. Resolving DNS names and IP addresses to SMB server names . 11 B.2. Determining Server Specifier Type . . . . . . . . . . . . 13 B.3. Workgroup vs. SMB Server Names . . . . . . . . . . . . . . 14 1. Introduction The SMB (Server Message Block) protocol was developed in the 1980's by IBM Corporation and later extended by 3Com Corporation, Intel Corporation, and Microsoft Corporation. SMB was originally designed to be carried on 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). Several attempts have been made to document and even standardize the SMB protocol (see [ONET], [SNIACIFS]), yet the further development of SMB remains under the control of Microsoft. Despite its proprietary nature, the workings of SMB over STD 19 transport are well known. SMB has been successfully implemented by several 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. Hertel Expires October 10, 2001 [Page 2]
INTERNET-DRAFT SMB URL April 10, 2001 2. SMB URL Scheme The SMB URL follows the generic URI scheme syntax for URLs as defined in [RFC2396], with exceptions and caveats as noted. The SMB URL takes one of the following general forms: smb:// smb://<server>/ smb://<server>/<share>/ smb://<server>/<share>/<path> A "server", in this context, is the network identification of a system that provides network access to SMB services ("shares") via STD 19 transport. Servers are identified by NetBIOS name (see [RFC1001], section 16.1.1). Alternatively, a server MAY be identified by DNS name or IP address in an SMB URL. A DNS name or IP address MUST be reverse-mapped (resolved) to a NetBIOS name in order to establish a NetBIOS Session Service connection (see section 3 and Appendix B, below). Thus, the server field of the SMB URL is said to "resolve" to a NetBIOS name. A "share" is a named service offered by a server. A share can represent the root of a directory tree, print queues, an inter-process communications (IPC) port, or other shared object. The "path" identifies a resource within a share, such as a named pipe within an IPC share or a file within a directory. Operating systems that are derived from Microsoft's MS-DOS or IBM's PC-DOS (eg. Windows and OS/2) use a format known as Universal Naming Convention (UNC) to identify objects within an SMB filesharing network. The UNC format uses backslashes ("\") to delimit path elements. In general, an SMB URL string can be formed from a UNC string by simply replacing the UNC backslashes with forward slashes and adding the "smb:" prefix. For example: UNC form URL form ----------------------------- --------------------------------- \\scred\src\ smb://scred/src/ \\scred\src\jcifs\ smb://scred/src/jcifs/ \\scred\src\jcifs\SmbURL.java smb://scred/src/jcifs/SmbURL.java The reverse mapping is not quite as simple due to additional fields that may be included in the SMB URL, such as authentication information or fragment references (see sections 2.4 and 4). 2.1 Server Types There are two server types that may be referenced using the SMB URL scheme. These are SMB servers and workgroup browse servers. A workgroup browse server is a special case of an SMB server. Hertel Expires October 10, 2001 [Page 3]
INTERNET-DRAFT SMB URL April 10, 2001 In an SMB filesharing network, SMB servers are assigned membership in workgroups. For each workgroup, a list of member servers is maintained. This list is known as the "browse list". The browse list also contains a list of all of the workgroups in use on the local IP subnet. The browse list may be obtained by connecting to the SMB service of a host that is running the workgroup browse service, accessing a specific share, and opening a specific named pipe to request the list. Thus, a workgroup browse server must also be an SMB server, and the browse service may be seen as a specific instance of an SMB service. The SMB URL form smb:// represents the root of the SMB URL hierarchy. The utility of this form is that it may be used to indicate the set of available workgroups. As described above each workgroup within the set contains, in turn, a list of SMB servers. Thus the list of workgroups is, logically, at the top of the hierarchy. When presented with this form, an application would likely request a copy of the browse list from a workgroup browse server. For applications which do not implement support for workgroups, this form has no utility. If the application does support the workgroup browse service, then the SMB URL form smb://<server>/ is overloaded. The "server" field may resolve to either a workgroup name or an SMB server name, or both, depending upon the configuration of the SMB filesharing network. Appendix B outlines a mechanism for determining the service type of a server name. If a URL string in the above format is found to represent both a workgroup and an SMB server, then the application determines which interpretation should be used. An application SHOULD choose to process both interpretations if possible. For example, consider an application such as a web browser which might process the SMB URL string "smb://nbname/" as follows: - If the name "nbname" resolves to an SMB server name, the application will display a list of shares offered by the server. - If the name "nbname" resolves to a workgroup name, the application will display a list of servers which are members of that workgroup. Hertel Expires October 10, 2001 [Page 4]
INTERNET-DRAFT SMB URL April 10, 2001 - If the name "nbname" resolves to both an SMB server name and a workgroup name, then the application will display the list of workgroup member servers followed by the list of shares. NetBIOS names that represent both a workgroup and an SMB server are not common. This situation typically represents a misconfigured SMB filesharing network (see [RFC1001], section 10). Application support for access to the workgroup browser service is optional. An application specifically designed to query the workgroup browser service need not implement support for accessing SMB servers directly. In this case, SMB shares and the objects which they contain would not be accessible via the URL. 2.2 SMB URL Semantics smb:// This form of the SMB URL represents the root of an SMB filesharing network hierarchy; that is, the hierarchy of servers and services available to the client. This form has no utility unless the application includes support for the workgroup browser service, as described above. smb://<server>/ This form of the SMB URL represents an SMB server; a system offering shares via SMB over STD 19 transport. The server field may resolve to either an SMB server name, or a workgroup browse service name, or both. smb://<server>/<share>/ This form identifies a specific share offered by an SMB server. The workgroup browse service does not offer shares. If a share name is present, then the server name is always interpreted as an SMB server name. smb://<server>/<share>/<path> This form specifies a path within the given share. The path may represent a print queue, device, named pipe, directory, or file. 2.3 Relative SMB URLs Relative SMB URLs are permitted and are resolved according to the rules defined in [RFC2396] section 5.2. Hertel Expires October 10, 2001 [Page 5]
INTERNET-DRAFT SMB URL April 10, 2001 2.4 Fragments URL fragment references are permitted if the SMB URL resolves to a file or file-like object for which fragments have meaning. The fragment syntax is: smb://<server>/<share>/<path>#<fragment> 2.5 Queries The semantics of URL queries are not defined for the SMB URL scheme. 3. SMB Namespace As previously described, STD 19 provides a mechanism for implementing the NetBIOS API on top of TCP and UPD. In doing so, these RFCs describe a NetBIOS Virtual LAN system. The virtual NetBIOS LAN has its own addressing mechanism, which is based on the use of NetBIOS "names". These names do not map directly to DNS names, and must be encoded before they are used. (See [RFC1001], section 14.) Also note that the NetBIOS namespace is flat, unlike the hierarchical DNS namespace. In order to connect to a server, a client must know the server's NetBIOS name (NetBIOS address). This is a requirement of the STD 19 Session Request Packet. Many SMB implementations, however, allow the use of DNS names and/or IP address for identifying servers. The DNS name or IP address must be reverse-mapped to a NetBIOS service name in order to establish an SMB session. A mechanism for performing this reverse-mapping is outlined in Appendix B. A NetBIOS Scope ID (see [RFC1001], section 9) is sometimes used to identify and separate virtual NetBIOS LANs from one another. Scope IDs are identical in syntax to DNS domain names. In practice, it is not possible to determine whether a name is an IP address, a DNS name, or a NetBIOS name by examining the syntax of the string. (It is possible to syntactically determine that a given string is NOT an IP address, but the reverse is not true.) A mechanism for determining the network address format provided in Appendix B. Hertel Expires October 10, 2001 [Page 6]
INTERNET-DRAFT SMB URL April 10, 2001 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) 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 manor, 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 form: smb://<ntdomain>;<username>:<password>@<server>/ This allows the specification of: ntdomain - The authentication domain (single-signon database server) to use for authorization username - User account identifier password - Password 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 Examples smb://ubiqx/ -- Indicates either a workgroup or an SMB server (or both). The underlying application must resolve the name in order to determine the service type. Hertel Expires October 10, 2001 [Page 7]
INTERNET-DRAFT SMB URL April 10, 2001 smb://scred/src/ -- Indicates the share "src" on server "scred". smb://neko@scred/src/jcifs/smb/SmbURL.java -- Indicates file /jcifs/smb/SmbURL.java within the "src" share on node "scred". Also specifies a username, "neko", to be used when connecting to the SMB 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. The SMB protocol also allows clients and servers to negotiate the use of Unicode in share and path names. Once again, however, there is no standard character set for SMB communications and no mechanism for negotiating which character set is to be used between the client and server. It is, therefore, not possible to know which character set to use on the wire. 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. Use of the 'port' Field The use of the port field is reserved. This document presents an SMB URL for use with SMB over STD 19 transport. The SMB protocol can also be transported natively over TCP. SMB over native TCP is known as CIFS (Common Internet FileSystem), and was introduced by Microsoft as part of their Windows 2000 product. CIFS uses port 445/TCP as its service port. If the SMB URL can be extended to include support for CIFS filesharing without changing the syntax provided in this document, then an SMB URL in the form: smb://<server>:445/<share>/<path> Hertel Expires October 10, 2001 [Page 8]
INTERNET-DRAFT SMB URL April 10, 2001 may be used to specify CIFS objects. The use of the SMB URL to specify CIFS objects is beyond the scope of this document. It is strongly suggested, however, that a separate CIFS URL scheme would be preferable to extending the SMB URL scheme for this purpose. 8. URL Syntax The SMB URL conforms to the BNF grammar given in [RFC2396] Appendix A, with the following extensions: host = nbtname | hostname | IPv4address nbtname = netbiosname scope netbiosname = 1*( netbiosnamec ) *( netbiosnamec | "*" ) netbiosnamec = ( aphanum | escaped | ":" | "=" | "+" | "$" | "," | "-" | "_" | "!" | "~" | "'" | "(" | ")" ) scope = *( "." domainlabel ) This change specifies that NetBIOS names, including the optional Scope ID, may be used in forming SMB URLs. Also, the userinfo field is parsed as follows: userinfo = [ ntdomain ";" ] username [ ":" password ] ntdomain = *( unreserved | escaped | "&" | "=" | "+" | "$" | "," ) username = *( unreserved | escaped | "&" | "=" | "+" | "$" | "," ) password = *( unreserved | escaped | "&" | "=" | "+" | "$" | "," ) 9. Acknowledgements The creation of this document would not have been possible without the help and guidance of Michael B. Allen, jCIFS Team Steven French, IBM Richard Sharpe, Samba Team and the aggregate knowledge and wisdom of The Samba Team The jCIFS Team The Samba-TNG Team and the members of the samba-technical mailing list. Hertel Expires October 10, 2001 [Page 9]
INTERNET-DRAFT SMB URL April 10, 2001 10. References [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)", Draft 0.9, March 2001. [RFC1001] "Protocol Standard For a NetBIOS Service on a TCP/UDP Transport: Concepts and Methods", RFC 1001, March 1987. [RFC1002] "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. 11. 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 specification based upon it. SNIA has plans to publish the new specification once it has been accepted by SNIA members and interested third-parties. Hertel Expires October 10, 2001 [Page 10]
INTERNET-DRAFT SMB URL April 10, 2001 Appendix B. Working with NetBIOS Names (Implementation Notes) The information presented in this section is intended as a guide for implementors. This information is not directly relevant to the syntax or semantics of the SMB URL scheme. NetBIOS names are addresses. They represent communication end-points within a NetBIOS LAN. [RFC1001] and [RFC1002] provide a mechanism for creating virtual NetBIOS LANs over TCP and UDP transport. Part of that mechanism is the NetBIOS name service, which provides for mapping between NetBIOS names and IP addresses. A given host system may register several NetBIOS names, each representing an application or service that can communicate with other applications or services via the NetBIOS API. SMB sessions are established and messages transferred via the NetBIOS session service (see [RFC[1001], section 5.3 and [RFC1002] section 4.3). The system that originates the connection is the "calling" node; the target node is the "called" node. In order to establish an SMB session, a TCP connection must be established between the calling and called nodes. If a TCP connection already exists, the SMB session may make use of the existing connection. Before a NetBIOS session can be established, the calling node must discover the IP address of the called node. This is done using the NetBIOS name service (see [RFC1001] section 5.2 and [RFC1002] section 4.2). NetBIOS names are always 16 octets, padded with spaces (0x20) if necessary, as specified in the RFCs. By convention, however, the 16th octet is reserved for use as a service type indicator. This field is known as the "suffix". The suffix is NEVER specified in an SMB URL string, but is appended by the implementation. B.1. Resolving DNS names and IP addresses to SMB server names. The NetBIOS session service requires that the client provide the NetBIOS names of both the calling and called nodes. When connecting to an SMB server, the calling name is the default NetBIOS name of the client, space padded as described, with a suffix byte value of 0x00. The called name is the NetBIOS name of the server with a suffix byte value of 0x20. Applications which support the SMB URL SHOULD include support for the use of DNS names or IP addresses in addition to NetBIOS names when initiating SMB connections via NetBIOS over TCP/IP transport. This functionality is an extension to the NetBIOS over TCP/IP behavior specified in RFC 1001 and RFC 1002, and is not part of that standard. As stated above, the Session Request packet requires a called and a calling name, both of which are NetBIOS names. In order to create a Session Request packet, the DNS name or IP address of the server must Hertel Expires October 10, 2001 [Page 11]
INTERNET-DRAFT SMB URL April 10, 2001 be reverse-mapped to the server's NetBIOS name. Mechanisms for doing so include: -- Issuing a NetBIOS Adapter Status Query This is the most reliable method for discovering an SMB server name. A NetBIOS Adapter Status Query is sent to the target IP address. (See [RFC1001] section 15.1.4 and [RFC1002] sections 4.2.17 & 4.2.18.) If a response is received, and if the target node is running an SMB server service, then the response will include a NetBIOS name with a suffix byte value of 0x20. This NetBIOS name may be used as the called name in a Session Request packet. -- Generic Server Name This method is not supported by all SMB server implementations. Some SMB servers will accept the generic SMB server name "*SMBSERVER". A client can simply use the name "*SMBSERVER" as the called name in a Session Request packet. As with all SMB server NetBIOS names, the "*SMBSERVER" name must be space padded and terminated with a suffix byte value of 0x20. The "*SMBSERVER" is an illegal NetBIOS name (see [RFC1001], section 5.2), so it is never registered with the NetBIOS name service and will not be returned in a NetBIOS Adapter Status Response. The target will return a CALLED NAME NOT PRESENT error to indicate indicate that it does not support the "*SMBSERVER" generic name, or that SMB services are not running. -- Parsing the DNS Name or IP address (guessing) This is the least reliable method for discovering an SMB server name. Systems which support STD 19 transport will often use the same base name within the DNS and NetBIOS name spaces. Thus, the first label of the DNS name is a good guess at the NetBIOS name of the target. If the input is an IP address rather than a DNS name, the a reverse lookup against the DNS MAY be performed to determine the DNS name. The first label of the DNS name consists of the initial portion of the DNS name string up to but not including the first dot character ('.'). If the label is greater than 15 bytes in length, it is not likely to be a NetBIOS name. It may, however, be truncated to 15 bytes. The result is then space padded to a total of 15 bytes, and a suffix value 0x20 is added. This forms a valid Hertel Expires October 10, 2001 [Page 12]
INTERNET-DRAFT SMB URL April 10, 2001 NetBIOS name that may be used as a called name in a Session Request packet. If the target returns a CALLED NAME NOT PRESENT error, then the DNS name guess is incorrect. It is difficult, syntactically, to determine whether a given string is a DNS name or an IP address. Some existing applications will interpret the decimal string representation of the first octet of an IP address as if it were a DNS label. For example, given the string "192.168.101.1" some applications try using "192" as the called name (padded, and with the 0x20 suffix, as described above). This behavior is acceptable. Any or all of the above MAY be tried in any order. B.2. Determining Server Specifier Type NetBIOS names, DNS names, and IP addresses can not be easily distinguished syntactically. For example, the string "192.168.101.1" might be an IP address, but it is also a valid NetBIOS name and may even be a valid partially qualified DNS name. The appropriate mechanism for distinguishing between these server specifier types is the trial-and-error method. Implementations SHOULD begin with the assumption that the specifier is a NetBIOS name. The following process is used to test this assumption: If the name string contains dot characters ('.', ASCII 0x2E), then separate the name into NetBIOS name and Scope ID at the first dot. REPEAT If the resulting NetBIOS name is greater than 15 octets in length, then the name is not a NetBIOS name. Exit, indicating failure. Issue an STD 19 Name Query using the NetBIOS name and Scope ID. A suffix value of 0x20 or 0x1D must be used. Both values may be used. See section B.3. If a Positive Name Query Response is received, then the the name is a NetBIOS name. Exit, indicating success and returning the NetBIOS name and scope ID as parsed. Find the next dot character in the original string and re-separate the string at that dot. END Note that the empty string is a valid Scope ID. Hertel Expires October 10, 2001 [Page 13]
INTERNET-DRAFT SMB URL April 10, 2001 If the server specifier is not a NetBIOS name, then it is either a DNS name or an IP address. These are semantically equivalent. B.3. Workgroup vs. SMB Server Names If the URL string is of the form smb://<server>/ then the server field may represent either an SMB server name or a workgroup name. The name MUST NOT be interpreted as a workgroup name if: -- Authentication information is present in the server field. This is because null authentication is used when requesting a browse list. -- The server field is entered as a DNS name or an IP address. This is because workgroups, conceptually, represent a group of servers rather than an individual server and the browse list may be retrieved from one or more browse servers. (A workgroup name is a NetBIOS group name.) In these cases, the server name is interpreted as a reference to an SMB server only. Thus, workgroups may only be accessed via their NetBIOS names. When testing the name using the algorithm presented in section B.2, a NetBIOS name suffix value of 0x20 is used to find an SMB server, and a suffix value of 0x1D is used to find a workgroup browse server. Hertel Expires October 10, 2001 [Page 14]