idnits 2.17.1 draft-crhertel-smb-url-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 356: '...t. Applications MUST support the use ...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 279 has weird spacing: '...RL.java smb:...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 8, 2003) is 7779 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2732 (Obsoleted by RFC 3986) -- Possible downref: Non-RFC (?) normative reference: ref. 'XOPENSMB' -- Possible downref: Non-RFC (?) normative reference: ref. 'ONET' -- Possible downref: Non-RFC (?) normative reference: ref. 'SNIACIFS' Summary: 7 errors (**), 0 flaws (~~), 2 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 INTERNET-DRAFT Christopher R. Hertel 2 draft-crhertel-smb-url-04.txt Samba Team 3 Expires July 8, 2003 January 8, 2003 5 SMB Filesharing URL Scheme 7 Status of this Memo 9 This document is an Internet-Draft and is in full conformance with 10 all provisions of Section 10 of RFC2026. 12 Internet-Drafts are working documents of the Internet Engineering 13 Task Force (IETF), its areas, and its working groups. Note that 14 other groups may also distribute working documents as 15 Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference 20 material or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt 25 The list of Internet-Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html 28 Discussions regarding this document and the SMB URL scheme should 29 take place on the jcifs@samba.org mailing list. Information on 30 joining this mailing list can be found at: 31 http://lists.samba.org/listinfo/jcifs/. 33 Abstract 35 The Server Message Block (SMB) protocol is one of the most widely 36 used network filesystem protocols in existence. This document 37 describes a format for an SMB Uniform Resource Locator (SMB URL). 38 The SMB URL can be used to indicate SMB workgroups, servers, shares, 39 files, inter-process communications pipes, print queues, and devices; 40 the objects in the SMB network filesystem space. 42 Table of Contents 44 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 45 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 46 2. URL Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . 4 47 2.1 NBT Transport. . . . . . . . . . . . . . . . . . . . . . . . . 4 48 2.1.1 nbt_name . . . . . . . . . . . . . . . . . . . . . . . . . 5 49 2.1.2 auth_domain. . . . . . . . . . . . . . . . . . . . . . . . 5 50 2.1.3 nbt_context. . . . . . . . . . . . . . . . . . . . . . . . 6 51 2.2. Relative SMB URLs. . . . . . . . . . . . . . . . . . . . . . . 7 52 2.3. Use of the 'port' Field. . . . . . . . . . . . . . . . . . . . 7 53 3. Relationship Between the URL and the UNC Formats. . . . . . . . . . 7 54 4. Authentication and Security Considerations. . . . . . . . . . . . . 8 55 5. SMB URL Semantics . . . . . . . . . . . . . . . . . . . . . . . . . 8 56 6. Character Encoding Issues . . . . . . . . . . . . . . . . . . . . . 9 57 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . 9 58 8. References. . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 59 9. Author's Address. . . . . . . . . . . . . . . . . . . . . . . . . .10 60 1. Introduction 62 The Server Message Block protocol (SMB) was created in the 1980's by 63 Dr. Barry Feigenbaum at IBM Corporation. It was later extended by 64 IBM, 3Com, Intel, and Microsoft. SMB is now also known by the name 65 CIFS, which stands for Common Internet FileSystem. 67 SMB was originally carried via a proprietary network transport, the 68 interface to which was called NetBIOS (Network Basic Input Output 69 System). Two Internet RFCs ([RFC1001], [RFC1002]) were published 70 which describe a mechanism for implementing the NetBIOS API on top 71 of TCP and UDP. Those RFCs are now known collectively as Internet 72 Standard #19 (STD 19), and the protocol they describe is known as 73 NBT (for NetBIOS over TCP). 75 SMB is intended to be transport independent. In addition to 76 transport via NBT, SMB may be carried directly on TCP/IP without the 77 intervening NetBIOS emulation layer. 79 Several attempts have been made to document and even standardize the 80 SMB protocol ([XOPENSMB], [ONET], [SNIACIFS]), yet the further 81 development of SMB remains under the control of Microsoft. Despite 82 its proprietary nature, the workings of SMB are sufficiently well 83 known that SMB filesharing has been successfully implemented by 84 several third-party commercial vendors, and in Open Source. SMB 85 server and client software is available for a wide variety of 86 operating system platforms. The very large number of systems which 87 support this form of filesharing make an SMB URL scheme both 88 practical and desirable. 90 1.1. Purpose 92 This document does not attempt to describe the implementation of the 93 SMB protocol itself. The goal is to present the syntax of the SMB 94 URL, and explain how it maps to the features of SMB. 96 2. URL Definition 98 An SMB URL is identified by one of two scheme names: "smb" or "cifs". 99 Both are considered to be equivalent. 101 The following grammar defines the syntax of the SMB URL. It is 102 based upon the grammar given in Appendix A of [RFC2396], and amended 103 by [RFC2732]. Refer to those RFCs for any token definitions missing 104 from the grammar below. 106 smb_URL = ( SMB_absURL | SMB_relURL ) 107 smb_absURL = scheme "://" 108 [ smb_net_path ] [ "?" [ nbt_context ] ] 109 smb_relURL = abs_path | rel_path 110 scheme = "smb" | "cifs" 112 smb_net_path = smb_server [ abs_path ] 114 smb_server = [ smb_userinfo "@" ] smb_srv_name [ ":" port ] 116 smb_srv_name = nbt_name | host 117 nbt_name = netbiosname [ "." scope_id ] 118 netbiosname = 1*( netbiosnamec ) *( netbiosnamec | "*" ) 119 netbiosnamec = ( alphanum | escaped | ":" | "=" | "+" | "$" | 120 "," | "-" | "_" | "!" | "~" | "'" | "(" | ")" ) 121 scope_id = domainlabel *( "." domainlabel ) 123 smb_userinfo = [ auth_domain ";" ] userinfo 124 auth_domain = smb_srv_name 126 nbt_context = nbt_param *(";" nbt_param ) 128 nbt_param = ( ( "NBNS=" | "WINS=" ) host ) 129 | ( "CALLED=" netbiosname ) 130 | ( "CALLING=" netbiosname ) 131 | ( ( "WORKGROUP=" | "NTDOMAIN=" ) nbt_name ) 133 2.1 NBT Transport 135 Many of the syntax elements given in the above grammar are 136 requirements of the NBT transport. NBT creates a virtual NetBIOS LAN 137 on top of TCP and UDP, and provides mechanisms for mapping NetBIOS 138 names to IP addresses, but these mechanisms may require some 139 additional contextual information. 141 2.1.1 nbt_name 143 The SMB URL supports the use of NetBIOS names and Scope IDs for 144 identifying SMB servers. When included as part of an SMB URL, the 145 syntax of the NetBIOS name is a superset of the syntax of a DNS 146 domain name label. For example: 148 smb://jcifs/ 150 Syntactically, the string "jcifs" in the smb_srv_name field of 151 the above string may be seen as either a DNS host name 152 (unqualified), or as a NetBIOS name. The underlying SMB 153 implementation must determine the namespace of the name. (This 154 is a common problem in SMB implementations and is typically solved 155 by first attempting to resolve the name as a NetBIOS name and, if 156 that fails, as a DNS host name.) 158 Likewise, given: 160 smb://jcifs.samba.org/ 162 the string "jcifs.samba.org" may be interpreted either as a 163 qualified DNS name, or as a NetBIOS name with appended Scope ID. 165 A NetBIOS name may include many characters which are not permitted 166 in a domainlabel, including some non-printing characters. Octet 167 values excluded by the syntax must be escaped. A NetBIOS name may 168 not begin with an asterisk character. The total length of the 169 NetBIOS name (with escape characters translated to their octet 170 equivalents) may not exceed 15 octets. 172 The mapping of NetBIOS names to IP addresses is described in 173 [RFC1001] and [RFC1002]. 175 2.1.2 auth_domain 177 The auth_domain string is passed to the underlying SMB layer for 178 interpretation. It is used to specify the SMB authentication 179 authority, which is known as a "Domain Controller". 181 2.1.3 nbt_context 183 The nbt_context may be used to provide additional information 184 about the NBT transport layer and related support servers. 185 Client systems implementing the SMB URL will interpret the 186 nbt_context entries locally. The nbt_params are specified as 187 key/value pairs. For example: 189 smb://jcifs/?WORKGROUP=WORLDWIDEHQ;NBNS=127.0.0.1 191 In the above example, the WORKGROUP keyword is assigned a value of 192 "WORLDWIDEHQ", and the NBNS keyword is assigned a value of 193 "127.0.0.1". 195 The following keywords are defined: 197 NBNS: Specifies the NetBIOS Name Server to be used for 198 point-to-point NBT Name Resolution. The NBNS may 199 be specified using a DNS hostname or an IP address. 200 See [RFC1001] for information on the NBNS. 202 WINS: A synonym for NBNS. 204 CALLED: Specifies the NetBIOS name of the SMB server. This 205 value is only used with NBT transport. It is 206 required by the NBT Session Request message (see 207 [RFC1002], Section 4.3.2). 209 If NBT transport is used, and the CALLED name is 210 not specified within the URL string, the underlying 211 SMB implementation must deduce the CALLED name from 212 available information. 214 CALLING: Specifies the NetBIOS name of the client. This 215 value is only used with NBT transport. It is 216 required by the NBT Session Request message (see 217 [RFC1002], Section 4.3.2). 219 If NBT transport is used, and the CALLING name is 220 not specified within the URL string, the underlying 221 SMB implementation must generate a suitable name. 223 WORKGROUP: Specifies workgroup membership. Workgroups are 224 used to organize resources. By specifying the 225 NetBIOS name of the workgroup, a list of member SMB 226 servers can be obtained. The workgroup concept was 227 developed after the publication of [RFC1001] and 228 [RFC1002], and is not described in those documents. 230 NTDOMAIN: A synonym for WORKGROUP. 232 NODETYPE: One of "B", "P", "M", or "H". These represent the 233 different mechanisms by which a NetBIOS name may 234 be resolved to an IP address on an NBT network. 235 The first three types are defined in STD 19. In 236 "H" mode the NBNS is queried before a broadcast 237 query is sent; the opposite of "M" mode. 239 BROADCAST: The IPv4 broadcast address to which to send 240 broadcast NBT name queries. This may be used on 241 multi-homed hosts to specify one of the connected 242 subnets. 244 SCOPEID: The syntax allows the NBT Scope to be specified as 245 part of the NBT name. It is preferable, however, 246 to specify the Scope ID as part of the NBT context. 248 Although all of the keywords and values are shown in upper case, 249 case is not significant. 251 2.2. Relative SMB URLs 253 Relative SMB URLs are supported and are resolved according to the 254 rules defined in [RFC2396] section 5.2. 256 2.3. Use of the 'port' Field 258 STD 19 includes a mechanism for retargeting Session Service 259 connections to alternate ports (see [RFC1001], section 16.1.1.) 260 which means that non-standard ports may be used for SMB transport. 261 The URL port field may be used to specify an alternate service 262 port for SMB over either NBT or native TCP transport. 264 3. Relationship Between the URL and the UNC Formats. 266 Some operating systems support a format known as Universal Naming 267 Convention (UNC). UNC is a means for identifying network resources. 268 SMB is one of the protocols supported by UNC. 270 In general, a UNC string specifying a resource available via SMB 271 protocol can be converted into an SMB URL string by simply adding 272 the "smb:" or "cifs:" prefix and reversing the direction of all of 273 the separating slashes. For example: 275 UNC form URL form 276 ----------------------------- --------------------------------- 277 \\ubiqx\src\ smb://ubiqx/src/ 278 \\ubiqx\src\jcifs\ smb://ubiqx/src/jcifs/ 279 \\ubiqx\src\jcifs\SmbURL.java smb://ubiqx/src/jcifs/SmbURL.java 281 4. Authentication and Security Considerations 283 SMB authentication can be categorized as follows: 285 o None 286 o Share-based 287 o User-based 288 o Authentication Server-based (NT Domain and Kerberos) 290 The authentication mechanism to be used is negotiated during 291 client/server session setup. Client applications, therefore, are 292 aware of the server's authentication requirements and may prompt for 293 appropriate input (password, username, authentication domain). By 294 prompting for authentication information, an application ensures that 295 such information is entered by the user in a controlled manner, and 296 that security measures (if any) such as password encryption or 297 password hash generation are applied by the SMB protocol handler 298 before the data are transmitted. 300 Some authentication values may also be provided within the SMB URL 301 string. In particular, the following fields may be included in the 302 URL: 304 auth_domain - The authentication domain (single-signon database 305 server) to use for authorization 306 userinfo - User account identifier (username) 308 These fields are all optional. 310 5. SMB URL Semantics 312 The primary purpose of the SMB URL is to specify resources made 313 available via the SMB protocol. One such resource is the list 314 of available servers. Under NBT, SMB Servers are organized into 315 Workgroups (also called NT Domains), and the list of available 316 Workgroups is also available. 318 smb:// 319 -- No server has been specified. In this form, the URL should 320 interpreted as a request for a list of x Workgroups available 321 on the local LAN. 323 smb://server 324 -- This form provides an SMB server, but no share path. The 325 interpretation of this form is dependant upon the semantics 326 of the specified server name. If the name resolves to an 327 NBT Workgroup name, then this is a request for a list of 328 servers offering SMB services within the workgroup. Otherwise, 329 the name represents an SMB file server. 331 smb://neko@scred/src/jcifs/smb/SmbURL.java 332 -- Indicates file /src/jcifs/smb/SmbURL.java on node "scred". The 333 username "neko" is to be used when connecting to the share. 334 If the path is specified, then the URL cannot represent a 335 a request for Workgroup information. 337 6. Character Encoding Issues 339 The only restriction that STD 19 places on the octet values that may 340 be used in a NetBIOS name is that the name may not begin with an 341 asterisk ('*', ASCII value 0x2A). No other values are listed as 342 excluded in the RFCs. For historical reasons, however, 343 implementations generally disallow the use of a nul byte (0x00) 344 within a NetBIOS name. NetBIOS names are interpreted as a string of 345 octets, so common mutli-byte character sets cannot be used to form 346 NetBIOS names. 348 Octet values less than 128 (0x80) in a NetBIOS name are interpreted 349 as US-ASCII characters. Octet values above 127 are created using the 350 host's own codepage, and there is no protocol mechanism to specify 351 the code page in use. URL escape sequences should be used to 352 represent characters with Octet values above 127. 354 NetBIOS names, share names, and the directory paths and filenames 355 offered by an SMB server may all contain characters from outside the 356 7-bit US-ASCII character set. Applications MUST support the use of 357 the URL escape sequence as described in [RFC2396] to accommodate 358 octet values that represent non-US-ASCII characters. 360 7. Acknowledgments 362 The creation of this document would not have been possible without 363 the help and guidance of 365 Michael B. Allen 366 David Farmer 367 Roy T. Fielding 368 Steven French 369 Larry Masinter 370 Richard Sharpe 372 and the aggregate knowledge and wisdom of 374 The Samba Team 375 The jCIFS Team 376 The Samba-TNG Team 377 The SNIA CIFS Work Group 378 and the samba-technical mailing list participants. 380 8. References 382 [RFC1001] Karl Auerbach, et. al., "Protocol Standard For a NetBIOS 383 Service on a TCP/UDP Transport: Concepts and Methods", RFC 384 1001, March 1987. 386 [RFC1002] Karl Auerbach, et. al., "Protocol Standard For a NetBIOS 387 Service on a TCP/UDP Transport: Detailed Specifications", 388 RFC 1002, March 1987. 390 [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 391 Resource Identifiers (URI): Generic Syntax", RFC 2396, 392 August 1998. 394 [RFC2732] R. Hinden, B. Carpenter, L. Masinter, "Format for Literal 395 IPv6 Addresses in URL's", RFC 2732, December 1999. 397 [XOPENSMB] "Protocols for X/Open PC Interworking: SMB, Version 2", 398 ISBN 1-872630-45-6, The Open Group, October 1992. 400 [ONET] Microsoft Corporation, Intel Corporation, "Microsoft 401 Networks/OpenNET Filesharing Protocol", Document Version 402 2, Intel Part No. 138446, November 7, 1988. 404 [SNIACIFS] Storage Network Industry Association CIFS Documentation 405 Work Group, "Common Internet File System (CIFS) Technical 406 Reference", Version: CIFS-TR 1.0, March 1, 2002. 408 9. Author's Address 410 Christopher R. Hertel 411 University of Minnesota 412 Networking and Telecommunications 413 2218 University Avenue SE 414 Minneapolis, MN 55414-3029, USA 416 E'mail: crh@samba.org 417 crh@ubiqx.org