idnits 2.17.1 draft-ietf-appsawg-file-scheme-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC1738, but the abstract doesn't seem to directly say this. It does mention RFC1738 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 15, 2016) is 2903 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'UTR15' -- Obsolete informational reference (is this intentional?): RFC 1738 (Obsoleted by RFC 4248, RFC 4266) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Applications Area Working Group M. Kerwin 3 Internet-Draft QUT 4 Obsoletes: 1738 (if approved) May 15, 2016 5 Intended status: Standards Track 6 Expires: November 16, 2016 8 The file URI Scheme 9 draft-ietf-appsawg-file-scheme-09 11 Abstract 13 This document specifies the "file" Uniform Resource Identifier (URI) 14 scheme, obsoleting the definition in RFC 1738. 16 It defines a common syntax which is intended to interoperate across 17 the broad spectrum of existing usages. At the same time it notes 18 some other current practices around the use of file URIs. 20 Note to Readers (To be removed by the RFC Editor) 22 This draft should be discussed on the IETF Applications Area Working 23 Group discussion list . 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on November 16, 2016. 42 Copyright Notice 44 Copyright (c) 2016 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 61 2. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 3. Operations Involving file URIs . . . . . . . . . . . . . . . 5 63 4. File Name Encoding . . . . . . . . . . . . . . . . . . . . . 5 64 5. Security Considerations . . . . . . . . . . . . . . . . . . . 5 65 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 66 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 8.1. Normative References . . . . . . . . . . . . . . . . . . 7 69 8.2. Informative References . . . . . . . . . . . . . . . . . 8 70 Appendix A. Differences from Previous Specifications . . . . . . 9 71 Appendix B. Example URIs . . . . . . . . . . . . . . . . . . . . 9 72 Appendix C. Similar Technologies . . . . . . . . . . . . . . . . 10 73 Appendix D. System-specific Operations . . . . . . . . . . . . . 10 74 D.1. POSIX Systems . . . . . . . . . . . . . . . . . . . . . . 11 75 D.2. DOS- and Windows-Like Systems . . . . . . . . . . . . . . 11 76 D.3. Mac OS X Systems . . . . . . . . . . . . . . . . . . . . 11 77 D.4. OpenVMS Files-11 Systems . . . . . . . . . . . . . . . . 11 78 Appendix E. Nonstandard Syntax Variations . . . . . . . . . . . 11 79 E.1. User Information . . . . . . . . . . . . . . . . . . . . 11 80 E.2. DOS and Windows Drive Letters . . . . . . . . . . . . . . 12 81 E.2.1. Relative Paths . . . . . . . . . . . . . . . . . . . 12 82 E.2.2. Vertical Bar Character . . . . . . . . . . . . . . . 13 83 E.3. UNC Strings . . . . . . . . . . . . . . . . . . . . . . . 14 84 E.3.1. file URI with Authority . . . . . . . . . . . . . . . 14 85 E.3.2. file URI with UNC Path . . . . . . . . . . . . . . . 15 86 E.4. Backslash as Separator . . . . . . . . . . . . . . . . . 16 87 Appendix F. UNC Syntax . . . . . . . . . . . . . . . . . . . . . 16 88 Appendix G. Collected Rules . . . . . . . . . . . . . . . . . . 16 89 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18 91 1. Introduction 93 A file URI identifies an object (a "file") stored in a structured 94 object naming and accessing environment on a host (a "file system.") 95 The URI can be used in discussions about the file, and if other 96 conditions are met it can be dereferenced to directly access the 97 file. 99 This document specifies a syntax based on the generic syntax of 100 [RFC3986] that is compatible with most existing usages. Optional 101 extensions to the syntax which might be encountered in practice are 102 listed in appendices; these extensions are listed for informational 103 purposes only. 105 The file URI scheme is not coupled with a specific protocol, nor with 106 a specific media type [RFC6838]. See Section 3 for a discussion of 107 operations that can be performed on the object identified by a file 108 URI. 110 1.1. Notational Conventions 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 114 document are to be interpreted as described in [RFC2119]. 116 Throughout this document the term "local file" is used to describe 117 files that can be accessed through the local file system API using 118 only the information included in the file path, not relying on other 119 information such as network addresses. It is important to note that 120 a local file may not be physically located on the local machine, for 121 example if a networked file system is transparently mounted into the 122 local file system. 124 The term "local file URI" is used to describe file URIs which have no 125 authority, or where the authority is the special string "localhost" 126 or a fully qualified domain name that resolves to the machine from 127 which the URI is being interpreted (Section 2). 129 2. Syntax 131 The file URI syntax is defined here in Augmented Backus-Naur Form 132 (ABNF) [RFC5234], importing the "host" and "path-absolute" rules from 133 [RFC3986] (as updated by [RFC6874].) 135 The generic syntax in [RFC3986] includes "path" and "authority" 136 components, for each of which only a subset is used in the definition 137 of the file URI scheme. The relevant subset of "path" is "path- 138 absolute", and the subset of "authority" is "file-auth", given below. 140 The syntax definition below is different from those given in 141 [RFC1630] and [RFC1738] as it is derived from the generic syntax of 142 [RFC3986], which post-dates the previous file URI specifications. 143 Appendix A enumerates significant differences. 145 file-URI = file-scheme ":" file-hier-part 147 file-scheme = "file" 149 file-hier-part = ( "//" auth-path ) 150 / local-path 152 auth-path = [ file-auth ] path-absolute 154 local-path = path-absolute 156 file-auth = "localhost" 157 / host 159 The "host" is the fully qualified domain name of the system on which 160 the file is accessible. This allows a client on another system to 161 know that it cannot access the file system, or perhaps to use some 162 other local mecahnism to access the file. 164 As a special case, the "file-auth" rule can match the string 165 "localhost" which is interpreted as "the machine from which the URI 166 is being interpreted," exactly as if no authority were present. Some 167 current usages of the scheme incorrectly interpret all values in the 168 authority of a file URI, including "localhost", as non-local. Yet 169 others interpret any value as local, even if the "host" does not 170 resolve to the local machine. To maximise compatibility with 171 previous specifications, users MAY choose to include an "auth-path" 172 with no "file-auth" when creating a URI. 174 Some file systems have case-sensitive file naming and some do not. 175 As such the file URI scheme supports case sensitivity, in order to 176 retain the case as given. Any transport-related handling of the file 177 URI scheme MUST retain the case as given. Any mapping to or from a 178 case-insensitive form is soley the responsibility of the 179 implementation processing the file URI on behalf of the referenced 180 file system. 182 Some file systems allow directory objects to be treated as files in 183 some cases. This can be reflected in a file URI by omitting the 184 trailing slash "/" from the path. Be aware that merging a relative 185 URI reference to such a base URI as per Section 5.2 of [RFC3986] 186 could remove the directory name from the resulting target URI. 188 Also see Appendix E that lists some nonstandard syntax variations 189 that can be encountered in practice. 191 3. Operations Involving file URIs 193 Implementations that provide dereferencing operations on file URIs 194 SHOULD, at a minimum, provide a read-like operation to return the 195 contents of a file located by a file URI. Additional operations MAY 196 be provided, such as writing to, creating, and deleting files. See 197 the POSIX file and directory operations [POSIX] for examples of 198 standardized operations that can be performed on files. 200 A file URI can be dependably dereferenced or translated to a local 201 file path only if it is local. A file URI is considered "local" if 202 it has no "file-auth", or the "file-auth" is the special string 203 "localhost" or a fully qualified domain name that resolves to the 204 machine from which the URI is being interpreted (Section 2). 206 This specification neither defines nor forbids any set of operations 207 that might be performed on a file identified by a non-local file URI. 209 4. File Name Encoding 211 File systems use various encoding schemes to store file and directory 212 names. Many modern file systems encode file and directory names as 213 arbitrary sequences of octets, in which case the representation as an 214 encoded string often depends on the user's localization settings, or 215 defaults to UTF-8 [STD63]. 217 Without other encoding information, percent-encoded octets in a file 218 URI ([RFC3986], Section 2.1) MAY be interpreted according to the 219 preferred or configured encoding of the system on which the URI is 220 being interpreted. 222 5. Security Considerations 224 There are many security considerations for URI schemes discussed in 225 [RFC3986]. 227 File access and the granting of privileges for specific operations 228 are complex topics, and the use of file URIs can complicate the 229 security model in effect for file privileges. 231 Historically, user agents have granted content from the file URI 232 scheme a tremendous amount of privilege. However, granting all local 233 files such wide privileges can lead to privilege escalation attacks. 234 Some user agents have had success granting local files directory- 235 based privileges, but this approach has not been widely adopted. 236 Other user agents use globally unique identifiers as the origin for 237 each file URI [RFC6454], which is the most secure option. 239 File systems typically assign an operational meaning to special 240 characters, such as the "/", "\", ":", "[", and "]" characters, and 241 to special device names like ".", "..", "...", "aux", "lpt", etc. In 242 some cases, merely testing for the existence of such a name will 243 cause the operating system to pause or invoke unrelated system calls, 244 leading to significant security concerns regarding denial of service 245 and unintended data transfer. It would be impossible for this 246 specification to list all such significant characters and device 247 names. Implementers MUST research the reserved names and characters 248 for the types of storage device that may be attached to their 249 application and restrict the use of data obtained from URI components 250 accordingly. 252 File systems vary in the way they handle case. Care must (?) be 253 taken to avoid issues resulting from possibly unexpected aliasing 254 from case-only differences between file paths or URIs. Similarly, 255 care must be taken to avoid issues resulting from aliasing from 256 mismatched encodings or Unicode equivalences [UTR15] (see Section 4). 258 6. IANA Considerations 260 This document defines the following URI scheme, so the "Permanent URI 261 Schemes" registry has been updated accordingly. This registration 262 complies with [BCP35]. 264 Scheme name: 265 file 267 Status: 268 permanent 270 Applications/protocols that use this scheme name: 271 Commonly used in hypertext documents to refer to files without 272 depending on network access. Supported by major browsers. 274 Windows API (PathCreateFromUrl, UrlCreateFromPath). 276 Perl LWP. 278 Contact: 279 Matthew Kerwin 281 Change Controller: 282 This scheme is registered under the IETF tree. As such, the IETF 283 maintains change control. 285 7. Acknowledgements 287 This specification is derived from [RFC1738], [RFC3986], and 288 [I-D.hoffman-file-uri] (expired); the acknowledgements in those 289 documents still apply. 291 Additional thanks to Dave Risney, author of the informative IE Blog 292 article , and Dave Thaler for their early comments and 294 suggestions. 296 8. References 298 8.1. Normative References 300 [BCP35] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 301 and Registration Procedures for URI Schemes", BCP 35, 302 RFC 7595, DOI 10.17487/RFC7595, June 2015, 303 . 305 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 306 Requirement Levels", BCP 14, RFC 2119, 307 DOI 10.17487/RFC2119, March 1997, 308 . 310 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 311 Resource Identifier (URI): Generic Syntax", STD 66, 312 RFC 3986, DOI 10.17487/RFC3986, January 2005, 313 . 315 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 316 Specifications: ABNF", STD 68, RFC 5234, 317 DOI 10.17487/RFC5234, January 2008, 318 . 320 [RFC6874] Carpenter, B., Cheshire, S., and R. Hinden, "Representing 321 IPv6 Zone Identifiers in Address Literals and Uniform 322 Resource Identifiers", RFC 6874, DOI 10.17487/RFC6874, 323 February 2013, . 325 [UTR15] Davis, M. and K. Whistler, "Unicode Normalization Forms", 326 August 2012, 327 . 329 8.2. Informative References 331 [Bug107540] 332 Bugzilla@Mozilla, "Bug 107540", October 2007, 333 . 335 [I-D.hoffman-file-uri] 336 Hoffman, P., "The file URI Scheme", draft-hoffman-file- 337 uri-03 (work in progress), January 2005. 339 [ISO10646] 340 International Organization for Standardization, 341 "Information Technology - Universal Multiple-Octet Coded 342 Character Set (UCS)", ISO/IEC 10646:2003, December 2003. 344 [MS-DTYP] Microsoft Open Specifications, "Windows Data Types, 2.2.56 345 UNC", January 2013, 346 . 348 [MS-NBTE] Microsoft Open Specifications, "NetBIOS over TCP (NBT) 349 Extensions", May 2014, 350 . 352 [MS-SMB] Microsoft Open Specifications, "Server Message Block (SMB) 353 Protocol", January 2013, 354 . 356 [NOVELL] Novell, "NetWare Core Protocols", 2013, 357 . 360 [POSIX] IEEE, "IEEE Std 1003.1, 2013 Edition", 2013. 362 [RFC1035] Mockapetris, P., "Domain names - implementation and 363 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 364 November 1987, . 366 [RFC1123] Braden, R., Ed., "Requirements for Internet Hosts - 367 Application and Support", STD 3, RFC 1123, 368 DOI 10.17487/RFC1123, October 1989, 369 . 371 [RFC1630] Berners-Lee, T., "Universal Resource Identifiers in WWW: A 372 Unifying Syntax for the Expression of Names and Addresses 373 of Objects on the Network as used in the World-Wide Web", 374 RFC 1630, DOI 10.17487/RFC1630, June 1994, 375 . 377 [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform 378 Resource Locators (URL)", RFC 1738, DOI 10.17487/RFC1738, 379 December 1994, . 381 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 382 Architecture", RFC 4291, DOI 10.17487/RFC4291, February 383 2006, . 385 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 386 DOI 10.17487/RFC6454, December 2011, 387 . 389 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 390 Specifications and Registration Procedures", BCP 13, 391 RFC 6838, DOI 10.17487/RFC6838, January 2013, 392 . 394 [RFC7530] Haynes, T., Ed. and D. Noveck, Ed., "Network File System 395 (NFS) Version 4 Protocol", RFC 7530, DOI 10.17487/RFC7530, 396 March 2015, . 398 [STD63] Yergeau, F., "UTF-8, a transformation format of ISO 399 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 400 2003, . 402 [WHATWG-URL] 403 WHATWG, "URL Living Standard", May 2013, 404 . 406 [Win32-Namespaces] 407 Microsoft Developer Network, "Naming Files, Paths, and 408 Namespaces", June 2013, . 411 Appendix A. Differences from Previous Specifications 413 According to the definition in [RFC1738] a file URL always started 414 with the token "file://", followed by an (optionally blank) host name 415 and a "/". The syntax given in Section 2 makes the entire authority 416 component, including the double slashes "//", optional. 418 Appendix B. Example URIs 420 The syntax in Section 2 is intended to support file URIs that take 421 the following forms: 423 Local files: 425 o A traditional file URI for a local file, with an empty authority. 426 This is the most common format in use today. E.g.: 428 * "file:///path/to/file" 430 o The minimal representation of a local file, with no authority 431 field and an absolute path that begins with a slash "/". E.g.: 433 * "file:/path/to/file" 435 Non-local files: 437 o A non-local file, with an explicit authority. E.g.: 439 * "file://host.example.com/path/to/file" 441 Appendix C. Similar Technologies 443 o The WHATWG defines a living URL standard [WHATWG-URL], which 444 includes algorithms for interpreting file URIs (as URLs). 446 o The Universal Naming Convention (UNC) [MS-DTYP] defines a string 447 format that can perform a similar role to the file URI scheme in 448 describing the location of files, except that files located by UNC 449 filespace selector strings are typically stored on a remote 450 machine and accessed using a network protocol. A UNC filespace 451 selector string has three parts: host, share, and path; described 452 for informational purposes in Appendix F. Appendix E.3 lists some 453 ways in which UNC filespace selector strings are currently made to 454 interoperate with the file URI scheme. 456 o The Microsoft Windows API defines Win32 Namespaces 457 [Win32-Namespaces] for interacting with files and devices using 458 Windows API functions. These namespaced paths are prefixed by 459 "\\?\" for Win32 File Namespaces and "\\.\" for Win32 Device 460 Namespaces. There is also a special case for UNC file paths in 461 Win32 File Namespaces, referred to as "Long UNC", using the prefix 462 "\\?\UNC\". This specification does not define a mechanism for 463 translating namespaced paths to or from file URIs. 465 Appendix D. System-specific Operations 467 This appendix is not normative; it highlights some observed 468 behaviours and provides system-specific guidance for interacting with 469 file URIs and paths. 471 D.1. POSIX Systems 473 There is little to say about POSIX file systems; the file URI 474 structure already closely resembles POSIX file paths. 476 D.2. DOS- and Windows-Like Systems 478 When mapping a DOS- or Windows-like file path to a file URI, the 479 drive letter (e.g. "c:") is typically mapped into the first path 480 segment. 482 Appendix E lists some non-standard techniques for interacting with 483 DOS- or Windows-like file paths and URIs. 485 D.3. Mac OS X Systems 487 The HFS+ file system uses a non-standard normalization form, similar 488 to Normalization Form D [UTR15]. Take care when transforming HFS+ 489 file paths to and from URIs (Section 4). 491 D.4. OpenVMS Files-11 Systems 493 When mapping a VMS file path to a file URI, the device name is mapped 494 into the first path segment. Note that the dollars sign "$" is a 495 reserved character per the definition in [RFC3986], Section 2.2, so 496 should be percent-encoded if present in the device name. 498 If the VMS file path includes a node reference, that is used as the 499 authority. Where the original node reference includes a username and 500 password in an access control string, they can be transcribed into 501 the authority using the non-standard syntax extension in 502 Appendix E.1. 504 Appendix E. Nonstandard Syntax Variations 506 These variations may be encountered by existing usages of the file 507 URI scheme, but are not supported by the normative syntax of 508 Section 2. 510 This appendix is not normative. 512 E.1. User Information 514 It might be necessary to include user information such as a username 515 in a file URI, for example when mapping a VMS file path with a node 516 reference that includes a username. 518 To allow user information to be included in a file URI, the "file- 519 auth" rule in Section 2 can be replaced with the following: 521 file-auth = "localhost" 522 / [ userinfo "@" ] host 524 This uses the "userinfo" rule from [RFC3986]. 526 As discussed in the HP OpenVMS Systems Documentation 527 528 "access control strings include sufficient information to allow 529 someone to break in to the remote account, [therefore] they create 530 serious security exposure." In a similar vein, the presence of a 531 password in a "user:password" userinfo field is deprecated by 532 [RFC3986]. As such, the userinfo field of a file URI, if present, 533 MUST NOT (?) contain a password. 535 E.2. DOS and Windows Drive Letters 537 On Windows- or DOS-based file systems an absolute file path can begin 538 with a drive letter. To facilitate this, the "local-path" rule in 539 Section 2 can be replaced with the following: 541 local-path = [ drive-letter ] path-absolute 543 drive-letter = ALPHA ":" 545 The "ALPHA" rule is defined in [RFC5234]. 547 This is intended to support the minimal representation of a local 548 file in a DOS- or Windows-based environment, with no authority field 549 and an absolute path that begins with a drive letter. E.g.: 551 o "file:c:/path/to/file" 553 URIs of the form "file:///c:/path/to/file" are already supported by 554 the "path-absolute" rule. 556 Note that comparison of drive letters in DOS or Windows file paths is 557 case-insensitive, some usages of file URIs therefore canonicalize 558 drive letters by converting them to uppercase. 560 E.2.1. Relative Paths 562 To mimic the behaviour of DOS- or Windows-based file systems, 563 relative paths beginning with a slash "/" can be resolved relative to 564 the drive letter, when present, and resolution of ".." dot segments 565 (per Section 5.2.4 of [RFC3986]) can be modified to not ever 566 overwrite the drive letter. 568 For example: 570 base: file:///c:/path/to/file.txt 571 rel. URI: /some/other/thing.bmp 572 resolved: file:///c:/some/other/thing.bmp 574 base: file:///c:/foo.txt 575 rel. URI: ../../bar.txt 576 resolved: file:///c:/bar.txt 578 Relative paths with a drive letter followed by a character other than 579 a slash (e.g. "c:bar/baz.txt" or "c:../foo.txt") might not be 580 accepted as dereferenceable URIs in DOS or Windows systems. 582 E.2.2. Vertical Bar Character 584 Historically some usages of file URIs have included a vertical line 585 character "|" instead of a colon ":" in the drive letter construct. 586 [RFC3986] forbids the use of the vertical line, however it may be 587 necessary to interpret or update old URIs. 589 For interpreting such URIs, the "auth-path" and "local-path" rules in 590 Section 2 and the "drive-letter" rule above can be replaced with the 591 following: 593 auth-path = [ file-auth ] path-absolute 594 / [ file-auth ] file-absolute 596 local-path = [ drive-letter ] path-absolute 597 / file-absolute 599 file-absolute = "/" drive-letter path-absolute 601 drive-letter = ALPHA ":" 602 / ALPHA "|" 604 This is intended to support regular DOS or Windows file URIs with 605 vertical line characters in the drive letter construct. E.g.: 607 o "file:///c|/path/to/file" 609 o "file:/c|/path/to/file" 611 o "file:c|/path/to/file" 612 To update such an old URI, replace the vertical line "|" with a colon 613 ":". 615 E.3. UNC Strings 617 Some usages of the file URI scheme allow UNC filespace selector 618 strings [MS-DTYP] to be translated to and from file URIs, either by 619 mapping the equivalent segments of the two schemes (hostname to 620 authority, sharename+objectnames to path), or by mapping the entire 621 UNC string to the path segment of a URI. 623 E.3.1. file URI with Authority 625 The following is an algorithmic description of the process of 626 translating a UNC filespace selector string to a file URI by mapping 627 the equivalent segments of the two schemes: 629 1. Initialise the URI with the "file:" scheme identifier. 631 2. Append the authority: 633 1. Append the "//" authority sigil to the URI. 635 2. Append the hostname field of the UNC string to the URI. 637 3. Append the sharename: 639 1. Transform the sharename to a path segment ([RFC3986], 640 Section 3.3) to conform to the encoding rules of Section 2 of 641 [RFC3986]. 643 2. Append a delimiting slash character "/" and the transformed 644 segment to the URI. 646 4. For each objectname: 648 1. Transform the objectname to a path segment as above. 650 2. Append a delimiting slash character "/" and the transformed 651 segment to the URI. 653 For example: 655 UNC String: \\host.example.com\Share\path\to\file.txt 656 URI: file://host.example.com/Share/path/to/file.txt 658 E.3.2. file URI with UNC Path 660 It is common to encounter file URIs that encode entire UNC strings in 661 the path, usually with all backslash "\" characters replaced with 662 slashes "/". 664 To interpret such URIs, the "auth-path" rule in Section 2 can be 665 replaced with the following: 667 auth-path = [ file-auth ] path-absolute 668 / unc-authority path-absolute 670 unc-authority = 2*3"/" file-host 672 file-host = inline-IP / IPv4address / reg-name 674 inline-IP = "%5B" ( IPv6address / IPvFuture ) "%5D" 676 This syntax uses the "IPv4address", "IPv6address", "IPvFuture", and 677 "reg-name" rules from [RFC3986]. 679 Note that the "file-host" rule is the same as "host" but with 680 percent-encoding applied to "[" and "]" characters. 682 This extended syntax is intended to support URIs that take the 683 following forms, in addition to those in Appendix B: 685 Non-local files: 687 o The representation of a non-local file, with an empty authority 688 and a complete (transformed) UNC string in the path. E.g.: 690 * "file:////host.example.com/path/to/file" 692 o As above, with an extra slash between the empty authority and the 693 transformed UNC string, as per the syntax defined in [RFC1738]. 694 E.g.: 696 * "file://///host.example.com/path/to/file" 698 This representation is notably used by the Firefox web browser. 699 See Bugzilla#107540 [Bug107540]. 701 It also further limits the definition of a "local file URI" by 702 excluding any with a path that encodes a UNC string. 704 E.4. Backslash as Separator 706 Historically some usages have copied entire file paths into the path 707 components of file URIs. Where DOS or Windows file paths were thus 708 copied the resulting URI strings contained unencoded backslash "\" 709 characters, which are forbidden by both [RFC1738] and [RFC3986]. 711 It may be possible to translate or update such an invalid file URI by 712 replacing all backslashes "\" with slashes "/", if it can be 713 determined with reasonable certainty that the backslashes are 714 intended as path separators. 716 Appendix F. UNC Syntax 718 The UNC filespace selector string is a null-terminated sequence of 719 characters from the Universal Character Set [ISO10646]. 721 The syntax of a UNC filespace selector string, as defined by 722 [MS-DTYP], is given here in Augmented Backus-Naur Form (ABNF) 723 [RFC5234] for convenience. Note that this definition is informative 724 only; the normative description is in [MS-DTYP]. 726 UNC = "\\" hostname "\" sharename *( "\" objectname ) 727 hostname = netbios-name / fqdn / ip-address 728 sharename = 729 objectname = 731 o "netbios-name" from [MS-NBTE], Section 2.2.1. 733 o "fqdn" from [RFC1035] or [RFC1123] 735 o "ip-address" from Section 2.1 of [RFC1123], or Section 2.2 of 736 [RFC4291]. 738 The precise format of "sharename" depends on the protocol; see: SMB 739 [MS-SMB], NFS [RFC7530], NCP [NOVELL]. 741 Appendix G. Collected Rules 743 Here are the collected syntax rules for all optional appendices, 744 presented for convenience. This collected syntax is not normative. 746 file-URI = file-scheme ":" file-hier-part 748 file-scheme = "file" 750 file-hier-part = ( "//" auth-path ) 751 / local-path 753 auth-path = [ file-auth ] path-absolute 754 / [ file-auth ] file-absolute 755 / unc-authority path-absolute 757 local-path = [ drive-letter ] path-absolute 758 / file-absolute 760 file-auth = "localhost" 761 / [ userinfo "@" ] host 763 unc-authority = 2*3"/" file-host 765 file-host = inline-IP / IPv4address / reg-name 767 inline-IP = "%5B" ( IPv6address / IPvFuture ) "%5D" 769 file-absolute = "/" drive-letter path-absolute 771 drive-letter = ALPHA ":" 772 / ALPHA "|" 774 This collected syntax is intended to support file URIs that take the 775 following forms: 777 Local files: 779 o A traditional file URI for a local file, with an empty authority. 780 E.g.: 782 * "file:///path/to/file" 784 o The minimal representation of a local file, with no authority 785 field and an absolute path that begins with a slash "/". E.g.: 787 * "file:/path/to/file" 789 o The minimal representation of a local file in a DOS- or Windows- 790 based environment, with no authority field and an absolute path 791 that begins with a drive letter. E.g.: 793 * "file:c:/path/to/file" 795 o Regular DOS or Windows file URIs, with vertical line characters in 796 the drive letter construct. E.g.: 798 * "file:///c|/path/to/file" 800 * "file:/c|/path/to/file" 802 * "file:c|/path/to/file" 804 Non-local files: 806 o The representation of a non-local file, with an explicit 807 authority. E.g.: 809 * "file://host.example.com/path/to/file" 811 o The "traditional" representation of a non-local file, with an 812 empty authority and a complete (transformed) UNC string in the 813 path. E.g.: 815 * "file:////host.example.com/path/to/file" 817 o As above, with an extra slash between the empty authority and the 818 transformed UNC string. E.g.: 820 * "file://///host.example.com/path/to/file" 822 Author's Address 824 Matthew Kerwin 825 Queensland University of Technology 826 Victoria Park Road 827 Kelvin Grove, QLD 4059 828 Australia 830 Email: matthew.kerwin@qut.edu.au