idnits 2.17.1 draft-crhertel-smb-url-12.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 12. -- Found old boilerplate from RFC 3978, Section 5.5 on line 832. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document seems to lack an RFC 3979 Section 5, para. 1 IPR Disclosure Acknowledgement. ** The document seems to lack an RFC 3979 Section 5, para. 2 IPR Disclosure Acknowledgement. ** The document seems to lack an RFC 3979 Section 5, para. 3 IPR Disclosure Invitation. 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 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 130: '...ing implementations MUST support both....' RFC 2119 keyword, line 131: '... Implementations SHOULD use "smb" as t...' RFC 2119 keyword, line 303: '...ded approach and SHOULD be implemented...' RFC 2119 keyword, line 464: '...ying SMB implementation MUST determine...' RFC 2119 keyword, line 482: '... MUST be escaped. Note, in particul...' (15 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 680 has weird spacing: '...bit.txt 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, 2007) is 6318 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) -- Looks like a reference, but probably isn't: '1001' on line 861 ** Obsolete normative reference: RFC 883 (Obsoleted by RFC 1034, RFC 1035) -- Possible downref: Non-RFC (?) normative reference: ref. 'XOPENSMB' -- Possible downref: Non-RFC (?) normative reference: ref. 'ONET' -- Possible downref: Non-RFC (?) normative reference: ref. 'SNIACIFS' -- Possible downref: Non-RFC (?) normative reference: ref. 'IMPCIFS' Summary: 10 errors (**), 0 flaws (~~), 3 warnings (==), 9 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-12.txt Samba Team 3 Expires July 8, 2007 January 8, 2007 5 SMB File Sharing URI Scheme 7 Intellectual Property Rights Disclosure Acknowledgment 9 By submitting this Internet-Draft, each author represents that any 10 applicable patent or other IPR claims of which he or she is aware 11 have been or will be disclosed, and any of which he or she becomes 12 aware will be disclosed, in accordance with Section 6 of BCP 79. 14 Status of this Memo 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that other 18 groups may also distribute working documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/1id-abstracts.html 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html 31 Discussions regarding this document and the SMB URI scheme should 32 take place on the uri@w3.org mailing list. 34 This Internet-Draft will expire on July 8th, 2007. 36 Abstract 38 The Server Message Block (SMB) protocol is one of the most widely 39 used network file system protocols in existence. This document 40 describes a scheme for an SMB Uniform Resource Identifier (SMB URI) 41 which can be used to identify SMB workgroups, servers, server shares, 42 directories, files, inter-process communications ports (named pipes), 43 and devices--the objects in the SMB network file system space. 45 Table of Contents 47 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 48 1.1. Purpose. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 49 2. SMB URI Scheme Overview . . . . . . . . . . . . . . . . . . . . . . 4 50 3. NetBIOS, NBT, and NBT Transport Semantics . . . . . . . . . . . . . 4 51 3.1. The NetBIOS Name Service . . . . . . . . . . . . . . . . . . . 5 52 3.2. The NetBIOS Datagram Service . . . . . . . . . . . . . . . . . 5 53 3.3. The NetBIOS Session Service. . . . . . . . . . . . . . . . . . 5 54 3.4 Accommodating NBT in the SMB URI . . . . . . . . . . . . . . . 5 55 4. NetBIOS-Based Workgroups. . . . . . . . . . . . . . . . . . . . . . 6 56 5. SMB URI Definition. . . . . . . . . . . . . . . . . . . . . . . . . 9 57 6. SMB URI Syntax Elements . . . . . . . . . . . . . . . . . . . . . .10 58 6.1. scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 59 6.2. smb-service. . . . . . . . . . . . . . . . . . . . . . . . . .10 60 6.3. auth-domain. . . . . . . . . . . . . . . . . . . . . . . . . .11 61 6.4. smb-srv-name . . . . . . . . . . . . . . . . . . . . . . . . .11 62 6.5. port . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12 63 6.6. scope-id . . . . . . . . . . . . . . . . . . . . . . . . . . .12 64 6.7. nbt-context. . . . . . . . . . . . . . . . . . . . . . . . . .13 65 7. The Relationship Between the SMB URI and the UNC Format . . . . . .15 66 8. Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . .16 67 9. Security Considerations . . . . . . . . . . . . . . . . . . . . . .16 68 10. Character Encoding Issues. . . . . . . . . . . . . . . . . . . . .17 69 11. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . . .17 70 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . . .18 71 13. Author's Address . . . . . . . . . . . . . . . . . . . . . . . . .18 72 14. Copyright Notice . . . . . . . . . . . . . . . . . . . . . . . . .19 73 15. Disclaimer of Validity . . . . . . . . . . . . . . . . . . . . . .19 74 Appendix A. Working with NetBIOS Names (Implementation Notes). . . . .19 75 A.1. NetBIOS Names. . . . . . . . . . . . . . . . . . . . . . . . .19 76 A.2. SMB Sessions via NBT . . . . . . . . . . . . . . . . . . . . .19 77 A.3. Resolving DNS names and IP addresses to SMB server names . . .20 78 A.4. Determining the Namespace of the smb-srv-name. . . . . . . . .22 79 A.5. Workgroup vs. SMB Server Names . . . . . . . . . . . . . . . .23 81 1. Introduction 83 The Server Message Block protocol (SMB) was created in the 1980's by 84 Dr. Barry Feigenbaum at IBM Corporation. It was later extended by 85 various contributors at 3Com, IBM, Intel, and Microsoft. During the 86 mid 1990's SMB was renamed CIFS (Common Internet File System). Both 87 names are in general use today. In common parlance, however, the 88 term "SMB" is typically used when referring to the core filesharing 89 protocol itself, while "CIFS" includes the set of sub-protocols and 90 extensions used to create the complete filesharing suite. 92 SMB was originally carried via a proprietary network transport, the 93 interface to which was called NetBIOS (Network Basic Input Output 94 System). Two Internet RFCs ([RFC1001], [RFC1002]) were published 95 which describe a mechanism for implementing the NetBIOS API on top 96 of TCP and UDP, thus allowing SMB to be transported over IP inter- 97 networks. Those RFCs are now known collectively as Internet 98 Standard #19, and the transport protocol that they describe is 99 commonly called NBT (or, sometimes, NetBT) for "NetBIOS over 100 TCP/IP." 102 In addition to transport via NBT, newer implementations of SMB 103 typically support SMB over TCP/IP without the intervening NetBIOS 104 emulation layer. This is known as SMB over "native TCP" or "naked 105 transport". 107 Several attempts have been made to document and even standardize the 108 CIFS suite ([XOPENSMB], [ONET], [SNIACIFS], [IMPCIFS]), yet the 109 further development of CIFS remains under the control of Microsoft. 110 Despite its proprietary nature, the workings of SMB are sufficiently 111 well known that SMB file sharing has been successfully implemented 112 by several third-party commercial vendors and in Open Source. SMB 113 server and client software is available for a wide variety of 114 operating system platforms. The very large number of systems which 115 support this form of file sharing make an SMB URI scheme both 116 practical and desirable. 118 1.1. Purpose 120 This document does not attempt to detail the proper implementation of 121 SMB/CIFS or the workings of the NBT transport layer. The goal is to 122 present the syntax of the SMB URI and to describe how that syntax is 123 mapped to the semantics of the CIFS suite. A limited set of 124 implementation guidelines is provided in the appendices. 126 2. SMB URI Scheme Overview 128 An SMB URI is identified by one of two scheme names: "smb" or "cifs". 129 There are existing implementations that support one or the other or 130 both of these names, so conforming implementations MUST support both. 131 Implementations SHOULD use "smb" as the scheme name when generating 132 SMB URIs. 134 The SMB URI conforms to the general syntax of URI described in 135 [RFC3986]. The scheme is comparable to other URI schemes that are in 136 common use, and should be familiar to anyone who uses popular user 137 agents such as web browsers. For example, consider the following 138 URIs: 140 ftp://server/dirpath/file.name 141 smb://server/dirpath/file.name 143 Both strings might identify the same file, differing only in the 144 protocol used to access the file. 146 As with other URI schemes, servers (hosts) may be identified by DNS 147 name, IPv4 address, or IPv6 address. The SMB URI scheme also 148 supports the use of NetBIOS names to identify SMB services. NetBIOS 149 names are resolved via the NBT Name Service, as described in 150 [RFC1001] and detailed in [RFC1002]. 152 3. NetBIOS, NBT, and NBT Transport Semantics 154 NBT was created so that applications and services that made use of 155 the NetBIOS API could communicate over IP internetworks. The NBT 156 transport maps the semantics of the NetBIOS API onto TCP and UDP, 157 hiding the fact that the underlying transport mechanism has changed. 159 In order to make this work, RFC1001/1002 define three key services: 161 - The NetBIOS Name Service 162 - The NetBIOS Datagram Service 163 - The NetBIOS Session Service 165 These three services collaborate to create a "virtual NetBIOS LAN" 166 on top of IP networks. 168 The use of NBT as a transport for SMB is widespread, so the syntax 169 and semantics of the SMB URI scheme have been adapted to accommodate 170 NetBIOS naming conventions and NBT context requirements. 172 3.1. The NetBIOS Name Service 174 The NetBIOS API uses names (strings of 16 octets) to identify 175 communications endpoints. These names are the addresses used in 176 "NetBIOS LANs". The NetBIOS Name Service is responsible for 177 transparently mapping these names to the IP addresses at which they 178 are registered, so that NetBIOS applications and services can find 179 one another. 181 The set of nodes that are connected to the same virtual NetBIOS LAN 182 is known as the "scope" of the LAN. NBT scopes are always given a 183 name, or Scope Identifier (Scope ID), though this normally goes 184 unnoticed because the default Scope ID is the empty string (""). 185 Multiple scopes, each having a different Scope ID, may intersect 186 across the same IP internetwork without conflict. 188 The SMB URI scheme provides a mechanism for specifying the NBT 189 Scope ID in the URI string. 191 3.2. The NetBIOS Datagram Service 193 The SMB URI scheme does not make direct use of the Datagram Service, 194 so there is no special syntax to support the handling of NetBIOS 195 datagram messages. 197 3.3. The NetBIOS Session Service 199 The Session Service provides a one-to-one mapping of NetBIOS Sessions 200 to TCP sessions. NetBIOS sessions over TCP are initiated by sending 201 an NBT SESSION REQUEST message. An NBT POSITIVE SESSION RESPONSE 202 indicates that the session has been established successfully. (See 203 [RFC1001], section 16.2.) 205 The SMB URI scheme supports the exchange of SMB messages over either 206 NBT sessions or "naked" TCP sessions. Other than the SESSION 207 REQUEST/POSITIVE SESSION RESPONSE, there is no difference between 208 the two transport types. 210 3.4 Accommodating NBT in the SMB URI 212 The SMB URI scheme supports both NBT and native TCP transport of SMB 213 messages. The syntax of the scheme provides for the inclusion of NBT 214 context information so that NetBIOS names can be properly resolved 215 and NetBIOS sessions established. 217 The scheme provides the ability to specify the following NBT context 218 information: 220 - Broadcast Address for NBT broadcast name resolution (B mode) 221 - NBNS Address for point-to-point name resolution (P mode) 222 - Name resolution mode selection (B, P, M, or H mode) 223 - NBT Scope ID 224 - NetBIOS CALLED name (destination address) 225 - NetBIOS CALLING name (source address) 227 Most SMB implementations use configuration files or DHCP to 228 establish an initial NBT context. The starting context is referred 229 to as the "base context" in the remainder of this document. NBT 230 context information given in absolute URIs is applied against the 231 base context to create the "current context". NBT context 232 information given in relative URIs is applied against the current 233 context to modify the current context. 235 The current NBT context is always used to interpret the meaning of a 236 given URI string. A relative URI containing updated NBT context 237 information will cause the resulting URI to be re-evaluated. 239 4. NetBIOS-Based Workgroups 241 The "workgroup" system is a part of the SMB/CIFS protocol suite. 242 Workgroups are built on top of NetBIOS, and are identified by their 243 NetBIOS names. The workgroup system allows SMB file servers to be 244 organized into named groups, with the goal of making it easier to 245 locate resources by categorizing them. 247 Within each workgroup, a list of member servers is maintained. In 248 addition to the server list, each workgroup maintains a list of all 249 other known workgroups. The combined list is known as the "browse 250 list". A copy of the browse list may be obtained by sending a 251 specific query via SMB. 253 The SMB URI scheme views the SMB file sharing environment 254 hierarchically. Conceptually, the hierarchy is arranged as follows: 256 List of workgroups (from the browse list) 257 + List of servers within a given workgroup (from the browse list) 258 + List of shares (shared objects) offered by a server 259 + Directories, files, etc. within a share 261 That hierarchy is mapped to the SMB URI scheme as follows: 263 URI Format Indicates 264 ========================= ======================================= 265 smb:// List of known workgroups 266 smb://smb-wrkgrp/ + SMB servers within the workgroup 267 smb://smb-server/ + Shares offered by an SMB server 268 smb://smb-server/abs-path + Directories, files, etc. 270 As shown above, the SMB URI provides syntax that indicates requests 271 for subsets of the browse list. In particular, the form: 273 smb:// 275 represents a request for the list of all known workgroups, while the 276 form: 278 smb://smb-wrkgrp/ 280 represents a request for the list of servers that are members of a 281 particular workgroup. 283 A problem arises, however, because the syntax used for requesting the 284 list of servers in a workgroup is indistinguishable from that of a 285 request for the list of shares (shared objects, such as exported 286 filesystems) offered by an SMB file server. Thus, the two requests 287 are differentiated semantically. Consider the following example: 289 smb://corgi/ 291 If the name "corgi" is a NetBIOS name and it resolves (via the NBT 292 Name Service) to a workgroup name, then a user agent would return a 293 list of servers in the CORGI workgroup. If, however, the name 294 resolves to a server name, then the user agent would return a list 295 of shares offered by the SMB server named CORGI. 297 It is rare, but possible (in a misconfigured NBT network), that a 298 NetBIOS name will resolve to both a workgroup and an SMB file server. 299 In this situation, SMB file services take precedence. Some user 300 agents may be capable of returning both the list of servers in the 301 workgroup and the list of shares provided by the SMB file server, 302 allowing the user to determine which is the desired result. This 303 is the recommended approach and SHOULD be implemented, where 304 possible. 306 There is a special case to be considered when using relative 307 references to move between a workgroup reference and a reference to a 308 server in the workgroup. Consider a workgroup named "corgis" and a 309 server named "cue" that is a member of that workgroup. 311 Presented with the URI string 313 smb://corgis/ 315 a user agent may return a list of servers that are members of the 316 CORGIS workgroup, including node CUE, and allow the user to select 317 one of those SMB servers. 319 The relative reference used to transition from 320 smb://corgis/ 321 to 322 smb://cue/ 323 would be "../cue". 325 When moving upward in the hierarchy, one might might expect: 327 "smb://cue/" + ".." ==> "smb://" 329 In this example, however, the user agent is aware that node "cue" is 330 a member of the "corgis" workgroup, so: 332 "smb://cue/" + ".." ==> "smb://corgis/" 334 The NBT workgroup membership of an SMB server may be determined 335 either by sending a Node Status Request query to the server (see 336 [RFC1001], section 15.1.4) or by maintaining a local cache of 337 workgroup information, or both. Obviously, the choice is 338 implementation dependent. If the server's workgroup membership is 339 not available via either of these methods, then it is acceptable to 340 move directly to the top of the hierarchy (smb://). 342 5. SMB URI Definition 344 The following grammar defines the syntax of the SMB URI. It is 345 based upon the grammar given in Appendix A of [RFC3986]. Refer to 346 that RFC for token definitions missing from the grammar below. 348 smb-URI = ( smb-absURI / smb-relURI ) 349 smb-absURI = scheme "://" smb-service [ "?" [ nbt-context ] ] 350 smb-relURI = ( path-absolute / path-rootless ) 351 [ "?" [ nbt-context ] ] 353 scheme = "smb" / "cifs" 354 smb-service = ( smb-wrkgrp / smb-net-path ) 356 smb-wrkgrp = [ smb-userinfo "@" ] [ smb-srv-name ] 357 [ ":" port ] [ "/" ] 358 smb-net-path = smb-server [ path-absolute ] 359 smb-server = [ smb-userinfo "@" ] smb-srv-name [ ":" port ] 361 smb-srv-name = nbt-name / host 362 nbt-name = netbiosname [ "." scope-id ] 363 netbiosname = netbiosnamec 1*14( netbiosnamec / "*" ) 364 netbiosnamec = ( ALPHA / DIGIT / pct-encoded 365 / "-" / "_" / "~" 366 / "!" / "$" / "&" / "'" / "(" / ")" 367 / "+" / "," / ";" / "=" 368 ) 370 scope-id = [ scope-label *( "." scope-label ) ] 371 scope-label = 1*63( scope-char ) 372 scope-char = ALPHA / DIGIT / "-" / "_" / "~" 373 / sub-delims / pct-encoded 375 smb-userinfo = [ auth-domain ";" ] userinfo-nosem 376 auth-domain = smb-srv-name 377 userinfo-nosem = *( unreserved / pct-encoded 378 / "!" / "$" / "&" / "'" / "(" / ")" 379 / "*" / "+" / "," / "=" / ":" 380 ) 382 nbt-context = nbt-param *(";" nbt-param ) 383 nbt-param = ( "BROADCAST=" IPv4address [ ":" port ] 384 / "CALLED=" netbiosname 385 / "CALLING=" netbiosname 386 / ( "NBNS=" / "WINS=" ) host [ ":" port ] 387 / "NODETYPE=" ("B" / "P" / "M" / "H") 388 / ( "SCOPEID=" / "SCOPE=" ) scope-id 389 ) 391 6. SMB URI Syntax Elements 393 The SMB URI scheme is more or less comparable to other URI schemes 394 used for remote filesystem access. It differs primarily in its 395 support for the NBT transport and NBT workgroups. This section 396 provides further explanation and description of those syntax 397 elements that are most likely to require clarification. 399 6.1. scheme 401 As described in section 2, above, an SMB URI is identified by one of 402 two scheme names: "smb" or "cifs". These are equivalent, but the 403 former is preferred. 405 6.2. smb-service 407 The SMB URI can be used to access workgroup information or SMB file 408 server services. There are minor differences in SMB URI syntax 409 depending up on which of these service types is being accessed. 411 It is possible, for instance, to request workgroup information 412 without specifying a destination server name. In particular, 413 the URI: 415 smb:// 417 represents a request for the list of locally available NBT 418 workgroups. 420 In some situations the workgroup list may not be available to 421 unauthenticated users, so the SMB URI scheme allows inclusion of 422 smb-userinfo information without the need to specify an smb-srv-name 423 (a workgroup name). Thus, the following is permitted: 425 smb://user@/ 427 In the above, the username "user" is being supplied. (The user agent 428 should prompt for a password to prevent the password from being 429 exposed.) 431 As with the smb-userinfo field, an SMB URI may include a port 432 reference without an smb-srv-name, as in the following example: 434 smb://:4220/ 436 (This is an example of an attempt to retrieve an NBT workgroup list 437 via SMB using destination TCP port 4220.) 438 Another difference between workgroup and SMB file server references 439 is that workgroup references can not be followed by a path. The 440 browse list does not offer shares, directories, or files so an SMB 441 URI string such as the following cannot represent a workgroup query: 443 smb://corgis/puppies/ 445 6.3. auth-domain 447 The auth-domain field is passed to the underlying SMB layer for 448 interpretation. It is used to specify the SMB authentication 449 authority (typically a "Domain Controller"). The interpretation of 450 this field is specific to the workings of the SMB protocol and should 451 be handled by the underlying SMB implementation. 453 6.4. smb-srv-name 455 The SMB URI supports the use of NetBIOS names and Scope IDs to 456 identify SMB servers and services. When included as part of an SMB 457 URI, the syntax of the NetBIOS name is a superset of the syntax of a 458 DNS domain name label. For example: 460 smb://jcifs/ 462 Syntactically, the string "jcifs" in the smb-srv-name field of the 463 above string may be seen as either a DNS host name (unqualified), or 464 as a NetBIOS name. The underlying SMB implementation MUST determine 465 the namespace of the name. (This is a common problem in SMB 466 implementations and is typically solved by first attempting to 467 resolve the name as a NetBIOS name and then, if that fails, as a DNS 468 host name.) 470 Likewise, given: 471 smb://jcifs.samba.org/ 473 the string "jcifs.samba.org" may be interpreted either as a qualified 474 DNS name, or as a NetBIOS name with appended Scope ID. 476 A NetBIOS name is simply a string of octets with a maximum length of 477 15 octets. (The actual maximum length of the NetBIOS name is 478 16-octets, but the 16th is reserved.) In practice, the only 479 restriction on the syntax of a NetBIOS name is that it may not begin 480 with an ASCII asterisk character (0x2A). Octet values that are 481 permitted by NetBIOS name syntax but excluded by the SMB URI syntax 482 MUST be escaped. Note, in particular, that the dot character (0x2E) 483 MUST be escaped if used in a NetBIOS name. 485 The resolution of NetBIOS names to IP addresses is described in 486 [RFC1001] and [RFC1002]. 488 6.5. port 490 RFC1001/1002 includes a mechanism for retargeting Session Service 491 connections to alternate ports (see [RFC1001], section 16.1.1.) 492 which means that non-standard ports may be used for SMB over NBT 493 transport. There may be other valid reasons for providing SMB 494 services on on-standard ports. 496 The URI port field may be used to specify an alternate service 497 port for SMB over either NBT or native TCP transport. When a 498 nonstandard port is used, the transport type (NBT or naked TCP) MUST 499 be deduced by the underlying SMB implementation. 501 6.6. scope-id 503 The correct syntax of an NBT Scope Identifier is described in section 504 9 of [RFC1001] as 506 "...a character string meeting the requirements of the domain name 507 system for domain names." 509 The intent was that the Scope ID should match the "preferred syntax" 510 for domain names, as given in Appendix 1 of [RFC883] (which has since 511 been superceded). Specifically: 513 "The labels must follow the rules for ARPANET host names. They 514 must start with a letter, end with a letter or digit, and have as 515 interior characters only letters, digits, and hyphen. There are 516 also some restrictions on the length. Labels must be 63 517 characters or less." 519 Several implementations of NBT now exist that disregard the character 520 set restrictions described above. The SMB URI is, therefore, 521 a bit more flexible with regard to the octet values that may be 522 used. In fact, the grammar given above allows the use of pct-encoded 523 values, so any octet value may be specified. Note, however, that 524 implementations MUST discard zero values ("%00") in the Scope ID 525 because many implementations interpret the Scope ID as being a 526 nul-terminated string. 528 Although the syntax allows Scope IDs that do not match the 529 original preferred syntax, the use of nonconforming Scope IDs is 530 generally considered unwise because the interpretation of 531 nonconforming Scope IDs is likely to be inconsistent. 533 The requirement that the Scope ID consist of dot-delimited labels of 534 one to sixty-three octets is enforced by the on-the-wire encoding 535 used by NBT. 537 The SMB URI scheme provides two mechanisms for specifying an NBT 538 Scope ID. The first, as shown in the grammar above, is to append the 539 Scope ID to the NetBIOS name as part of the smb-srv-name field, using 540 a dot (".") as a delimiter. This mechanism is included to support 541 existing implementations. 543 The other mechanism is to specify the Scope ID as part of the 544 nbt-context. The two examples given below are equivalent: 546 smb://netbios.scope.id/ 547 smb://netbios/?SCOPE=scope.id 549 The latter format is less ambiguous and, therefore, preferred. User 550 agents that rewrite URI strings for display purposes SHOULD rewrite 551 SMB URI strings that contain a Scope ID to conform to the nbt-context 552 format. 554 Note also that the scope-id syntax specifically permits a Scope ID 555 that is the empty string (""). The empty string is a valid Scope 556 ID and is, in fact, the default on all known implementations. 558 6.7. nbt-context 560 NBT context information is appended to the tail end of an SMB URI 561 string in the form of a URI query string. Context information is 562 specified using key/value pairs. Multiple context elements may be 563 specified by separating the key/value pairs with semi-colons. 565 The nbt-context may be used to provide information about the NBT 566 transport layer and related support servers. Information provided 567 in the nbt-context overrides the current NBT context maintained by 568 the user agent. The nbt-context is interpreted locally by the user 569 agent. 571 The nbt-context is made up of zero or more nbt-params fields, which 572 are specified as key/value pairs. For example: 574 smb://jcifs/?CALLED=VIRTSERV;NBNS=172.24.19.18 576 In the above example, the CALLED parameter is assigned a value of 577 "VIRTSERV", and the NBNS parameter is assigned a value of 578 "172.24.19.18". 580 The following keywords are defined: 582 BROADCAST: The IPv4 broadcast address to which to send NBT 583 broadcast name queries. This may, for example, be 584 used on multi-homed hosts to specify a target subnet. 586 The value assigned to the BROADCAST keyword may 587 optionally include a port number (delimited by 588 a colon). The standard port for NBT name resolution 589 is UDP/137. It is rare that a different port will 590 be used for broadcast name resolution. 592 CALLED: Specifies the NetBIOS name of the SMB server (the 593 NetBIOS destination address.) A CALLED name is 594 required by the NBT Session Request message (see 595 [RFC1002], Section 4.3.2). 597 If NBT transport is used and the CALLED name is not 598 specified within the URI string, the underlying SMB 599 implementation MUST deduce the CALLED name from 600 available information. (See Appendix A, below.) 602 CALLING: Specifies the NetBIOS name of the client (the NetBIOS 603 source address.) This value is only used with NBT 604 transport. It is required by the NBT Session Request 605 message (see [RFC1002], Section 4.3.2). 607 If NBT transport is used and the CALLING name is not 608 specified in the current NBT context, the underlying 609 SMB implementation MUST generate a suitable name. 610 (Typically, this will be based on the system's host 611 name.) 613 NBNS: Specifies the NetBIOS Name Server (NBNS) to be used 614 for point-to-point NBT Name Resolution. The NBNS may 615 be specified using a DNS name or an IP address. See 616 [RFC1001] for information on the NBNS. 618 The value assigned to this parameter may, optionally, 619 include a port number (delimited by a colon). The 620 standard port for NBT name resolution is UDP/137. 621 The use of a non-standard port for point-to-point NBT 622 name resolution is rare (but less so than it is for 623 broadcast name resolution). 625 NODETYPE: One of B, P, M, H, or the empty string. These 626 represent the different mechanisms by which a NetBIOS 627 name may be resolved to an IP address on an NBT 628 network. The first three types are defined in RFC 629 1001/1002. H mode is the inverse of M mode (in H mode 630 the NBNS is queried before a broadcast query is sent). 631 An empty NODETYPE indicates that NBT name resolution 632 should not be attempted (use DNS name resolution 633 instead). Some examples: 635 smb://smedley/?NBNS=172.24.19.18;NODETYPE=H 636 smb://corgis/?NODETYPE=B 637 smb://jcifs.samba.org/?NODETYPE=;CALLED=SMBSERV 639 SCOPE: Specifies the NBT Scope Identifier. Use of the SCOPE 640 keyword is preferred over inclusion of the Scope ID in 641 the nbt-name field. User agents MUST support both 642 mechanisms. 644 The default Scope ID is the empty string. This can be 645 specified in the SMB URI by assigning an empty value 646 to the SCOPE keyword. For example: 648 smb://bran/SCOPE= 649 smb://marika/SCOPE=;NODETYPE=B 651 SCOPEID: A synonym for SCOPE. 653 WINS: A synonym for NBNS. 655 Although all of the keywords and values are shown in upper case, case 656 is not significant. 658 The client implementation should provide a means for setting the base 659 context. The nbt-context is used to override default values or to 660 supply values missing from the local configuration. Most of all, the 661 nbt-context makes it possible for an SMB URI string to maintain a 662 consistent interpretation as it travels from one NBT scope to 663 another. 665 7. The Relationship Between the SMB URI and the UNC Format 667 Some operating systems support a format known as Universal Naming 668 Convention (UNC). UNC is a means for identifying network resources. 669 SMB is one of the protocols supported by UNC. 671 In general, a UNC string specifying a resource available via SMB 672 protocol can be converted into an SMB URI string by simply adding 673 the "smb:" (or "cifs:") prefix and reversing the direction of all 674 of the separating slashes. For example: 676 UNC form URI form 677 ------------------------------- ----------------------------------- 678 \\corgis\docs\ smb://corgis/docs/ 679 \\corgis\docs\jolyon\ smb://corgis/docs/jolyon/ 680 \\corgis\docs\jolyon\rabbit.txt smb://corgis/docs/jolyon/rabbit.txt 682 8. Authentication 684 SMB authentication can be divided into the following categories: 686 o None 687 o Share-based 688 o User-based 689 o Authentication-Server-based (NT Domain, AD Domain, or Kerberos) 691 The authentication mechanism to be used is negotiated during 692 client/server session setup. Client applications, therefore, are 693 aware of the server's authentication requirements and may prompt for 694 appropriate input (username, password, authentication domain). By 695 prompting for authentication information, an application ensures that 696 such information is entered by the user in a controlled manner, and 697 that security measures (if any), such as password encryption or 698 password hash generation, are applied by the SMB protocol handler 699 before the data are transmitted. 701 Some authentication values may also be provided within the SMB URI 702 string. In particular, the following fields may optionally be 703 included in the URI: 705 auth-domain - The authentication domain (single-signon database 706 server) to use for authorization 707 userinfo - User account identifier (username) 709 9. Security Considerations 711 All of the implementations of the SMB URI that are known to exist at 712 the time of this writing support inclusion of a password in the 713 URI string. This is generally considered to be dangerous, since 714 it may encourage exposure of the plaintext password. User agents 715 should provide a mechanism for prompting the user to enter passwords, 716 separate from the URI itself, in a reasonably secure fashion. 718 All other general security considerations relate to the workings of 719 the SMB/CIFS protocol suite and are beyond the scope of this 720 document. 722 10. Character Encoding Issues 724 The only restriction that RFC1001/1002 places on the octet values 725 that may be used in a NetBIOS name is that the name may not begin 726 with an asterisk ('*', ASCII value 0x2A). No other values are 727 excluded by those RFCs. For historical reasons, however, some 728 implementations disallow the use of a nul byte (0x00) within a 729 NetBIOS name. NetBIOS names are interpreted as fixed-length 730 strings of octets, so common mutli-byte character sets may cause 731 problems with older implementations. 733 Octet values less than 128 (0x80) in a NetBIOS name are typically 734 interpreted as US-ASCII characters. The interpretation of octet 735 values above 127 is dependent upon host configuration; there is no 736 protocol mechanism to specify which codepage or character set is in 737 use. In general, URI escape sequences should be used to represent 738 characters with octet values above 127. 740 NetBIOS names, share names, and the directory paths and filenames 741 offered by an SMB server may all contain characters from outside the 742 7-bit US-ASCII character set. Applications MUST support the use of 743 the URI escape sequence as described in [RFC3986] to accommodate 744 octet values that represent non-US-ASCII characters. 746 The SMB protocol has evolved over time to include support for various 747 character encoding schemes. A complete discussion of SMB and NBT 748 character encoding issues is way beyond the scope of this document. 750 11. Acknowledgments 752 The creation of this document would not have been possible without 753 the help and guidance of 755 Michael B. Allen 756 David Farmer 757 Roy T. Fielding 758 Steven French 759 Larry Masinter 760 Richard Sharpe 762 and the aggregate knowledge and wisdom of 764 The jCIFS Team 765 The Samba Team 766 The Samba-TNG Team 767 The SNIA CIFS Working Group 768 The samba-technical and jCIFS mailing list participants 769 The IETF URI-review and W3C URI mailing list participants 771 Funding for the RFC Editor function is currently provided by the 772 Internet Society. 774 12. References 776 [RFC883] Mockapetris, P., "DOMAIN NAMES - IMPLEMENTATION and 777 SPECIFICATION", RFC 883, November 1983. 779 [RFC1001] Karl Auerbach, et. al., "Protocol Standard For a NetBIOS 780 Service on a TCP/UDP Transport: Concepts and Methods", RFC 781 1001, March 1987. 783 [RFC1002] Karl Auerbach, et. al., "Protocol Standard For a NetBIOS 784 Service on a TCP/UDP Transport: Detailed Specifications", 785 RFC 1002, March 1987. 787 [RFC3986] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform 788 Resource Identifier (URI): Generic Syntax", RFC 3986, 789 January 2005. 791 [XOPENSMB] "Protocols for X/Open PC Interworking: SMB, Version 2", 792 ISBN 1-872630-45-6, The Open Group, October 1992. 794 [ONET] Microsoft Corporation, Intel Corporation, "Microsoft 795 Networks/OpenNET Filesharing Protocol", Document Version 796 2, Intel Part No. 138446, November 7, 1988. 798 [SNIACIFS] Storage Network Industry Association CIFS Documentation 799 Work Group, "Common Internet File System (CIFS) Technical 800 Reference", Version: CIFS-TR 1.0, March 1, 2002. 802 [IMPCIFS] Hertel, Christopher R., "Implementing CIFS -- the Common 803 Internet File System", ISBN 0-13-047116-X, Prentice Hall 804 PTR, August 2003 805 (http://ubiqx.org/cifs/) 807 13. Author's Address 809 Christopher R. Hertel 810 Alvarri, Inc. 811 15 South Fifth Street 812 Suite 1010 813 Minneapolis MN 55402 815 E'mail: crh@samba.org 816 crh@ubiqx.mn.org 818 14. Copyright Notice 820 Copyright (C) The Internet Society (2007). This document is subject 821 to the rights, licenses and restrictions contained in BCP 78, and 822 except as set forth therein, the authors retain all their rights. 824 15. Disclaimer of Validity 826 This document and the information contained herein are provided on an 827 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 828 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 829 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 830 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 831 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 832 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 834 Appendix A. Working with NetBIOS Names (Implementation Notes) 836 The information presented in this section is intended as a guide for 837 implementors. 839 Name resolution, particularly with the inclusion of support for 840 RFC1001/1002 NBT naming, may result in ambiguous meaning for some SMB 841 URI strings. This problem is reduced if correct NBT context 842 information is included in URI strings, and can be eliminated if all 843 implementations follow the same basic sequence when resolving server 844 names to addresses. 846 A.1. NetBIOS Names 848 NetBIOS names are addresses. They represent communication end-points 849 within a NetBIOS LAN. [RFC1001] and [RFC1002] provide a mechanism 850 for creating virtual NetBIOS LANs over TCP and UDP transport. The 851 core of that mechanism is the NetBIOS Name Service, which provides 852 for mapping between NetBIOS names and the IP addresses at which 853 they are registered. A given host system may register several 854 NetBIOS names, each representing an application or service that can 855 communicate with other applications or services through the NetBIOS 856 API. 858 A.2. SMB Sessions via NBT 860 SMB sessions are established and messages transferred via the NetBIOS 861 session service (see [RFC[1001], section 5.3 and [RFC1002] section 862 4.3). The system that originates the connection is the "calling" 863 node, and the target node is the "called" node. In order to 864 establish an SMB session, a TCP connection is created between the 865 calling and called nodes. 867 Before a NetBIOS session can be established, the calling node will 868 need to discover the IP address of the called node. This is done 869 using the NetBIOS Name Service (see [RFC1001] section 5.2 and 870 [RFC1002] section 4.2). NetBIOS names are always 16 octets, padded 871 with spaces (0x20) if necessary, as specified in the RFCs. By 872 convention, however, the 16th octet is reserved for use as a service 873 type indicator. This field is known as the "suffix". 875 The suffix byte is NEVER specified in an SMB URI string; it is 876 appended by the client implementation. 878 A.3. Resolving DNS names and IP addresses to SMB server names 880 The NetBIOS Session Service requires that the client provide the 881 NetBIOS names of both the calling and called nodes in the NBT 882 SESSION REQUEST. When connecting to an SMB server, the calling name 883 (source address) is typically the default NetBIOS name of the client, 884 space padded as described, with a suffix byte value of 0x00. The 885 called name (destination address) is the NetBIOS name of the server 886 with a suffix byte value of 0x20. 888 Applications which support the SMB URI MUST include support for the 889 use of DNS names or IP addresses in addition to NetBIOS names when 890 initiating SMB connections via NetBIOS over TCP/IP (NBT) transport. 891 This functionality is an extension to the NetBIOS over TCP/IP 892 behavior specified in RFC 1001 and RFC 1002, and is not part of that 893 standard. It is, however, a common extension and MUST be supported 894 for compatibility reasons, and to provide access to SMB shares in 895 situations in which the NetBIOS name space cannot be guaranteed to be 896 consistent. 898 As stated above, the Session Request packet requires a called and a 899 calling name, both of which are NetBIOS names. In order to create an 900 NBT Session Request packet, the DNS name or IP address of the server 901 MUST be reverse-mapped to the server's NetBIOS name. Mechanisms for 902 doing so include: 904 - Issuing a NetBIOS Adapter Status Query 906 A NetBIOS Adapter Status Query is sent to the target IP address. 907 (See [RFC1001] section 15.1.4 and [RFC1002] sections 4.2.17 & 908 4.2.18.) If a response is received, and if the target node is 909 running an SMB server service, then the response will include a 910 NetBIOS name with a suffix byte value of 0x20. This NetBIOS name 911 may be used as the called name in a Session Request packet. 913 It is possible that multiple entries will have a suffix byte of 914 0x20. If this is the case each name may be tried in turn, or one 915 of the other methods MUST be used to discover the name of the SMB 916 server service. 918 - Generic Server Name 920 This method is not supported by all SMB server implementations. 922 Some SMB servers will accept the generic SMB server name 923 "*SMBSERVER". A client can simply use the name "*SMBSERVER" as 924 the called name in a Session Request packet. As with all SMB 925 server NetBIOS names, the "*SMBSERVER" name MUST be space padded 926 and terminated with a suffix byte value of 0x20. 928 The "*SMBSERVER" name begins with an asterisk character, so it is 929 an illegal NetBIOS name (see [RFC1001], section 5.2). Thus, it is 930 never registered with the NetBIOS Name Service and will not be 931 returned in a NetBIOS Adapter Status Response. 933 If the target does not support the "*SMBSERVER" generic name, or 934 if it is not running SMB services, it will return a CALLED NAME 935 NOT PRESENT error. 937 Some SMB servers are capable of providing multiple SMB file 938 services, each under a different NetBIOS name. In order to support 939 the generic server name, these servers will designate one service 940 as a default that will answer to "*SMBSERVER". 942 - Parsing the DNS Name or IP address (guessing) 944 This is the least reliable method for discovering an SMB server 945 name. 947 Systems which support STD 19 transport will often use the same 948 base host name within the DNS and NetBIOS name spaces. Thus, the 949 first label of the DNS name is a good guess at the NetBIOS name of 950 the target. If the input is an IP address rather than a DNS name, 951 the a reverse lookup against the DNS may be performed to determine 952 the DNS name. 954 The first label of the DNS name consists of the initial portion of 955 the DNS name string up to but not including the first dot 956 character ('.'). If the label is greater than 15 bytes in length, 957 it cannot be a NetBIOS name. The label MUST be space padded to a 958 total of 15 bytes, with a suffix value 0x20 (space) added. This 959 forms a valid NetBIOS name that may be used as a called name in a 960 Session Request packet. 962 If the target returns a CALLED NAME NOT PRESENT error, then the 963 DNS name guess is incorrect. 965 Any of the above may be tried in any order. 967 A.4. Determining the Namespace of the smb-srv-name 969 NetBIOS names, DNS names, and IP addresses can not be easily 970 distinguished syntactically. Unfortunately, given the nature and 971 history of the SMB/CIFS suite, the appropriate mechanism for 972 distinguishing between these server specifier types is the 973 trial-and-error method. 975 Implementations should begin with the assumption that the specifier 976 is a NetBIOS name. The following process is used to test this 977 assumption: 979 If the NODETYPE (which is part of the NBT context) is the empty 980 string, then no NetBIOS name resolution mechanism has been 981 selected and the name cannot be resolved as a NetBIOS name. Exit. 983 If the name string contains dot characters ('.', ASCII 0x2E), then 984 separate the name into NetBIOS name and Scope ID at the first dot. 985 Otherwise use the entire string as the NetBIOS name, and assume an 986 Scope ID of "" unless the Scope ID is specified in the 987 nbt-context. 989 REPEAT 991 If the resulting NetBIOS name is greater than 15 octets in 992 length, then the name is not a NetBIOS name. Exit. 994 Issue STD 19 Name Queries using the NetBIOS name and Scope ID. 995 Suffix values of 0x20, 0x1B, and/or 0x1D should be used. (See 996 section A.5., below.) 998 If a Positive Name Query Response is received, then the name is 999 a NetBIOS name. Exit, indicating success and returning the 1000 NetBIOS name and scope ID as parsed. 1002 END 1004 If the server specifier is not a NetBIOS name, then it is either a 1005 DNS name or an IP address. These are semantically equivalent. 1007 A.5. Workgroup vs. SMB Server Names 1009 If the URI string is of the form 1011 smb://smb-srv-name/ 1013 then the smb-srv-name may represent either an SMB server name or a 1014 workgroup name. The name MUST NOT be interpreted as a workgroup name 1015 if: 1017 - There is path information following the trailing slash. 1019 Workgroups do not make shares or directories available. 1021 - The server field is entered as a DNS name or an IP address. 1023 A workgroup name is a NetBIOS group name. Workgroups, 1024 conceptually, represent a group of servers rather than an 1025 individual server, and the browse list may be retrieved 1026 from one or more browse servers. 1028 In these cases, the smb_srv_name is interpreted as a reference to an 1029 SMB server only. Workgroups may only be accessed via their NetBIOS 1030 names. 1032 When testing the name using the algorithm presented in section A.4, a 1033 NetBIOS name suffix value of 0x20 is used to find an SMB server, and 1034 a suffix value of 0x1D or 0x1B is used to find a workgroup browse 1035 server. 1037 A system operating in B mode will use the 0x1D suffix to search for 1038 a Local Master Browser operating on the same subnet. A system 1039 operating in P mode, however, will use the 0x1B suffix to query the 1040 NBNS for the Domain Master Browser. An M mode system will first send 1041 a broadcast query for the 0x1D name and, if that fails, query the 1042 NBNS for the 0x1B name. H mode behavior is reverse that of M mode.