idnits 2.17.1 draft-ietf-appsawg-file-scheme-16.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 updates 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 (Using the creation date from RFC1738, updated by this document, for RFC5378 checks: 1994-12-01) -- 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 (December 16, 2016) is 2680 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 informational reference (is this intentional?): RFC 1738 (Obsoleted by RFC 4248, RFC 4266) -- Obsolete informational reference (is this intentional?): RFC 2396 (Obsoleted by RFC 3986) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 5 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 Updates: 1738 (if approved) December 16, 2016 5 Intended status: Standards Track 6 Expires: June 19, 2017 8 The file URI Scheme 9 draft-ietf-appsawg-file-scheme-16 11 Abstract 13 This document provides a more complete specification of the "file" 14 Uniform Resource Identifier (URI) scheme, replacing the very brief 15 definition in Section 3.10 of RFC 1738. 17 It defines a common syntax which is intended to interoperate across 18 the broad spectrum of existing usages. At the same time it notes 19 some other current practices around the use of file URIs. 21 Note to Readers (To be removed by the RFC Editor) 23 This draft should be discussed on the IETF Applications Area Working 24 Group discussion list . 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on June 19, 2017. 43 Copyright Notice 45 Copyright (c) 2016 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 62 2. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 3. Operations Involving file URIs . . . . . . . . . . . . . . . 5 64 4. File System Name Encoding . . . . . . . . . . . . . . . . . . 5 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . 5 66 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 67 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 68 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 69 8.1. Normative References . . . . . . . . . . . . . . . . . . 7 70 8.2. Informative References . . . . . . . . . . . . . . . . . 8 71 Appendix A. Differences from Previous Specifications . . . . . . 9 72 Appendix B. Example URIs . . . . . . . . . . . . . . . . . . . . 9 73 Appendix C. Similar Technologies . . . . . . . . . . . . . . . . 10 74 Appendix D. System-Specific Operations . . . . . . . . . . . . . 10 75 D.1. POSIX Systems . . . . . . . . . . . . . . . . . . . . . . 11 76 D.2. DOS- and Windows-Like Systems . . . . . . . . . . . . . . 11 77 D.3. Mac OS X Systems . . . . . . . . . . . . . . . . . . . . 11 78 D.4. OpenVMS Files-11 Systems . . . . . . . . . . . . . . . . 11 79 Appendix E. Nonstandard Syntax Variations . . . . . . . . . . . 11 80 E.1. User Information . . . . . . . . . . . . . . . . . . . . 12 81 E.2. DOS and Windows Drive Letters . . . . . . . . . . . . . . 12 82 E.2.1. Relative Resolution . . . . . . . . . . . . . . . . . 13 83 E.2.2. Vertical Line Character . . . . . . . . . . . . . . . 13 84 E.3. UNC Strings . . . . . . . . . . . . . . . . . . . . . . . 14 85 E.3.1. file URI with Authority . . . . . . . . . . . . . . . 14 86 E.3.2. file URI with UNC Path . . . . . . . . . . . . . . . 15 87 E.4. Backslash as Separator . . . . . . . . . . . . . . . . . 16 88 Appendix F. Collected Nonstandard 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. Where 101 incompatibilities arise they are usually in parts of the scheme that 102 were underspecified in earlier definitions and have been tightened up 103 by more recent specifications. Appendix A lists significant changes 104 to syntax. 106 Extensions to the syntax which might be encountered in practice are 107 listed in Appendix E; these extensions are listed for informational 108 purposes and are not a requirement of implementation. 110 The file URI scheme is not coupled with a specific protocol, nor with 111 a specific media type [RFC6838]. See Section 3 for a discussion of 112 operations that can be performed on the object identified by a file 113 URI. 115 1.1. Notational Conventions 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 119 document are to be interpreted as described in [RFC2119] when they 120 appear in all upper case. They may also appear in lower or mixed 121 case as English words, without normative meaning. 123 Throughout this document the term "local file" is used to describe 124 files that can be accessed through the local file system API using 125 only the information included in the file path, not relying on other 126 information (such as network addresses.) It is important to note 127 that a local file may not be physically located on the local machine, 128 for example if a networked file system is transparently mounted into 129 the local file system. 131 The term "local file URI" is used to describe file URIs which have no 132 "authority" component, or where the authority is the special string 133 "localhost" or a fully qualified domain name that resolves to the 134 machine from which the URI is being interpreted (Section 2). 136 2. Syntax 138 The file URI syntax is defined here in Augmented Backus-Naur Form 139 (ABNF) [RFC5234], importing the "host" and "path-absolute" rules from 140 [RFC3986] (as updated by [RFC6874].) 142 The generic syntax in [RFC3986] includes "path" and "authority" 143 components, for each of which only a subset is used in the definition 144 of the file URI scheme. The relevant subset of "path" is "path- 145 absolute", and the subset of "authority" is "file-auth", given below. 147 The syntax definition below is different from those given in 148 [RFC1630] and [RFC1738] as it is derived from the generic syntax of 149 [RFC3986], which post-dates the previous file URI specifications. 150 Appendix A enumerates significant differences. 152 file-URI = file-scheme ":" file-hier-part 154 file-scheme = "file" 156 file-hier-part = ( "//" auth-path ) 157 / local-path 159 auth-path = [ file-auth ] path-absolute 161 local-path = path-absolute 163 file-auth = "localhost" 164 / host 166 The "host" is the fully qualified domain name of the system on which 167 the file is accessible. This allows a client on another system to 168 know that it cannot access the file system, or perhaps that it needs 169 to use some other local mechanism to access the file. 171 As a special case, the "file-auth" rule can match the string 172 "localhost" which is interpreted as "the machine from which the URI 173 is being interpreted," exactly as if no authority were present. Some 174 current usages of the scheme incorrectly interpret all values in the 175 authority of a file URI, including "localhost", as non-local. Yet 176 others interpret any value as local, even if the "host" does not 177 resolve to the local machine. To maximize compatibility with 178 previous specifications, users MAY choose to include an "auth-path" 179 with no "file-auth" when creating a URI. 181 The path component represents the absolute path to the file in the 182 file system. See Appendix D for some discussion of system-specific 183 concerns including absolute file paths and file system roots. 185 Some file systems have case-sensitive file naming and some do not. 186 As such the file URI scheme supports case sensitivity, in order to 187 retain the case as given. Any transport-related handling of the file 188 URI scheme MUST retain the case as given. Any mapping to or from a 189 case-insensitive form is solely the responsibility of the 190 implementation processing the file URI on behalf of the referenced 191 file system. 193 Also see Appendix E that lists some nonstandard syntax variations 194 that can be encountered in practice. 196 3. Operations Involving file URIs 198 See the POSIX file and directory operations [POSIX] for examples of 199 standardized operations that can be performed on files. 201 A file URI can be dependably dereferenced or translated to a local 202 file path only if it is local. A file URI is considered "local" if 203 it has no "file-auth", or the "file-auth" is the special string 204 "localhost" or a fully qualified domain name that resolves to the 205 machine from which the URI is being interpreted (Section 2). 207 This specification neither defines nor forbids any set of operations 208 that might be performed on a file identified by a non-local file URI. 210 4. File System Name Encoding 212 File systems use various encoding schemes to store file and directory 213 names. Many modern file systems store file and directory names as 214 arbitrary sequences of octets, in which case the representation as an 215 encoded string often depends on the user's localization settings, or 216 defaults to UTF-8 [STD63]. 218 When a file URI is produced that represents textual data consisting 219 of characters from the Unicode Standard coded character set 220 [UNICODE], the data SHOULD be encoded as octets according to the 221 UTF-8 character encoding scheme [STD63] before percent-encoding is 222 applied; as per [RFC3986], Section 2.5. 224 A decision not to use percent-encoded UTF-8 is outside the scope of 225 this specification. It will typically require the use of heuristics 226 or explicit knowledge about the way the string will be processed. 228 5. Security Considerations 230 There are many security considerations for URI schemes discussed in 231 [RFC3986]. 233 File access and the granting of privileges for specific operations 234 are complex topics, and the use of file URIs can complicate the 235 security model in effect for file privileges. 237 Historically, user agents have granted content from the file URI 238 scheme a tremendous amount of privilege. However, granting all local 239 files such wide privileges can lead to privilege escalation attacks. 240 Some user agents have had success granting local files directory- 241 based privileges, but this approach has not been widely adopted. 242 Other user agents use globally unique identifiers as the origin for 243 each file URI [RFC6454], which is the most secure option. 245 Treating a non-local file URI as local or otherwise attempting to 246 perform local operations on a non-local URI can result in security 247 problems. 249 File systems typically assign an operational meaning to special 250 characters, such as the "/", "\", ":", "[", and "]" characters, and 251 to special device names like ".", "..", "...", "aux", "lpt", etc. In 252 some cases, merely testing for the existence of such a name will 253 cause the operating system to pause or invoke unrelated system calls, 254 leading to significant security concerns regarding denial of service 255 and unintended data transfer. It would not be possible for this 256 specification to list all such significant characters and device 257 names. Implementers should research the reserved names and 258 characters for the types of storage device that may be attached to 259 their application and restrict the use of data obtained from URI 260 components accordingly. 262 File systems vary in the way they handle case. Care must be taken to 263 avoid issues resulting from possibly unexpected aliasing from case- 264 only differences between file paths or URIs, or from mismatched 265 encodings or Unicode equivalences [UAX15] (see Section 4). 267 6. IANA Considerations 269 This document defines the following URI scheme, so the "Permanent URI 270 Schemes" registry has been updated accordingly. This registration 271 complies with [BCP35]. 273 Scheme name: 274 file 276 Status: 277 permanent 279 Applications/protocols that use this scheme name: 280 Commonly used in hypertext documents to refer to files without 281 depending on network access. Supported by major browsers. 283 Used in development libraries, such as: 285 * Windows Shell (PathCreateFromUrl, UrlCreateFromPath). 287 * libwww-perl - The World-Wide Web library for Perl. 289 Contact: 290 Applications and Real-Time Area 292 Change Controller: 293 This scheme is registered under the IETF tree. As such, the IETF 294 maintains change control. 296 References: 297 This RFC. 299 7. Acknowledgements 301 Contributions from many members of the IETF and W3C communities - 302 notably Dave Crocker, Graham Klyne, Tom Petch, and John Klensin - are 303 greatly appreciated. 305 Additional thanks to Dave Risney, author of the informative IE Blog 306 article , and Dave Thaler for their early comments and 308 suggestions; and to Paul Hoffman, whose earlier work served as an 309 inspiration for this undertaking. 311 8. References 313 8.1. Normative References 315 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 316 Requirement Levels", BCP 14, RFC 2119, 317 DOI 10.17487/RFC2119, March 1997, 318 . 320 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 321 Resource Identifier (URI): Generic Syntax", STD 66, 322 RFC 3986, DOI 10.17487/RFC3986, January 2005, 323 . 325 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 326 Specifications: ABNF", STD 68, RFC 5234, 327 DOI 10.17487/RFC5234, January 2008, 328 . 330 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 331 DOI 10.17487/RFC6454, December 2011, 332 . 334 [RFC6874] Carpenter, B., Cheshire, S., and R. Hinden, "Representing 335 IPv6 Zone Identifiers in Address Literals and Uniform 336 Resource Identifiers", RFC 6874, DOI 10.17487/RFC6874, 337 February 2013, . 339 [STD63] Yergeau, F., "UTF-8, a transformation format of ISO 340 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 341 2003, . 343 8.2. Informative References 345 [Bash-Tilde] 346 Free Software Foundation, Inc, "Bash Reference Manual: 347 Tilde Expansion", February 2014, 348 . 351 [BCP35] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 352 and Registration Procedures for URI Schemes", BCP 35, 353 RFC 7595, DOI 10.17487/RFC7595, June 2015, 354 . 356 [Bug107540] 357 Bugzilla@Mozilla, "Bug 107540", October 2007, 358 . 360 [MS-DTYP] Microsoft Open Specifications, "Windows Data Types, 2.2.57 361 UNC", October 2015, 362 . 364 [POSIX] IEEE, "IEEE Std 1003.1, 2013 Edition", 2013. 366 [RFC1630] Berners-Lee, T., "Universal Resource Identifiers in WWW: A 367 Unifying Syntax for the Expression of Names and Addresses 368 of Objects on the Network as used in the World-Wide Web", 369 RFC 1630, DOI 10.17487/RFC1630, June 1994, 370 . 372 [RFC1738] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform 373 Resource Locators (URL)", RFC 1738, DOI 10.17487/RFC1738, 374 December 1994, . 376 [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 377 Resource Identifiers (URI): Generic Syntax", RFC 2396, 378 DOI 10.17487/RFC2396, August 1998, 379 . 381 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 382 Specifications and Registration Procedures", BCP 13, 383 RFC 6838, DOI 10.17487/RFC6838, January 2013, 384 . 386 [UAX15] Davis, M., Ed. and K. Whistler, Ed., "Unicode Standard 387 Annex #15: Unicode Normalization Forms", February 2016, 388 . 390 [UNICODE] The Unicode Consortium, "The Unicode Standard, Version 391 9.0.0", ISBN 978-1-936213-13-9, June 2016, 392 . 394 [WHATWG-URL] 395 WHATWG, "URL Standard", December 2016, 396 . 398 [Win32-Namespaces] 399 Microsoft Developer Network, "Naming Files, Paths, and 400 Namespaces", June 2013, . 403 [Zsh-Tilde] 404 "zsh: 14.7 Filename Expansion", December 2015, 405 . 408 Appendix A. Differences from Previous Specifications 410 The syntax definition in Section 2 inherits incremental differences 411 from the general syntax of [RFC1738] made by [RFC2396] ([RFC2396], 412 Appendix G) and [RFC3986] ([RFC3986], Appendix D). 414 According to the definition in [RFC1738] a file URL always started 415 with the token "file://", followed by an (optionally blank) host name 416 and a "/". The syntax given in Section 2 makes the entire authority 417 component, including the double slashes "//", optional. 419 Appendix B. Example URIs 421 The syntax in Section 2 is intended to support file URIs that take 422 the following forms: 424 Local files: 426 o A traditional file URI for a local file, with an empty authority. 427 This is the most common format in use today. E.g.: 429 * "file:///path/to/file" 431 o The minimal representation of a local file, with no authority 432 field and an absolute path that begins with a slash "/". E.g.: 434 * "file:/path/to/file" 436 Non-local files: 438 o A non-local file, with an explicit authority. E.g.: 440 * "file://host.example.com/path/to/file" 442 Appendix C. Similar Technologies 444 o The WHATWG URL specification [WHATWG-URL] defines browser behavior 445 for a variety of inputs, including file URIs. As a living 446 document, it changes to reflect updates in browser behavior. As a 447 result, its algorithms and syntax definitions may or may not be 448 consistent with this specification. Implementors should be aware 449 of this possible discrepancy if they expect to share file URIs 450 with browsers that follow the WHATWG specification. 452 o The Universal Naming Convention (UNC) [MS-DTYP] defines a string 453 format that can perform a similar role to the file URI scheme in 454 describing the location of files, except that files located by UNC 455 filespace selector strings are typically stored on a remote 456 machine and accessed using a network protocol. Appendix E.3 lists 457 some ways in which UNC filespace selector strings are currently 458 made to interoperate with the file URI scheme. 460 o The Microsoft Windows API defines Win32 Namespaces 461 [Win32-Namespaces] for interacting with files and devices using 462 Windows API functions. These namespaced paths are prefixed by 463 "\\?\" for Win32 File Namespaces and "\\.\" for Win32 Device 464 Namespaces. There is also a special case for UNC file paths in 465 Win32 File Namespaces, referred to as "Long UNC", using the prefix 466 "\\?\UNC\". This specification does not define a mechanism for 467 translating namespaced paths to or from file URIs. 469 Appendix D. System-Specific Operations 471 This appendix is not normative. It highlights some observed 472 behaviours and provides system-specific guidance for interacting with 473 file URIs and paths. This is not an exhaustive list of operating or 474 file systems; rather it is intended to illustrate certain types of 475 interactions that might be encountered. 477 D.1. POSIX Systems 479 In a POSIX file system the root of the file system is represented as 480 a directory with a zero-length name, usually written as "/"; the 481 presence of this root in a file URI can be taken as given by the 482 initial slash in the "path-absolute" rule. 484 Common UNIX shells such as the Bourne-Again SHell (bash) and Z Shell 485 (zsh) provide a function known as "tilde expansion" [Bash-Tilde] or 486 "filename expansion" [Zsh-Tilde], where a path that begins with a 487 tilde character "~" can be expanded out to a special directory name. 488 No such facility exists using the file URI scheme; a tilde in a file 489 URI is always just a tilde. 491 D.2. DOS- and Windows-Like Systems 493 When mapping a DOS- or Windows-like file path to a file URI, the 494 drive letter (e.g. "c:") is typically mapped into the first path 495 segment. 497 Appendix E lists some nonstandard techniques for interacting with 498 DOS- or Windows-like file paths and URIs. 500 D.3. Mac OS X Systems 502 The HFS+ file system uses a nonstandard normalization form, similar 503 to Normalization Form D [UAX15]. Take care when transforming HFS+ 504 file paths to and from URIs (Section 4). 506 D.4. OpenVMS Files-11 Systems 508 When mapping a VMS file path to a file URI, the device name is mapped 509 into the first path segment. Note that the dollars sign "$" is a 510 reserved character per the definition in [RFC3986], Section 2.2, so 511 should be percent-encoded if present in the device name. 513 If the VMS file path includes a node reference, that reference is 514 used as the authority. Where the original node reference includes a 515 user name and password in an access control string, they can be 516 transcribed into the authority using the nonstandard syntax extension 517 in Appendix E.1. 519 Appendix E. Nonstandard Syntax Variations 521 These variations may be encountered by existing usages of the file 522 URI scheme, but are not supported by the normative syntax of 523 Section 2. 525 This appendix is not normative. 527 E.1. User Information 529 It might be necessary to include user information such as a user name 530 in a file URI, for example when mapping a VMS file path with a node 531 reference that includes an access control string. 533 To allow user information to be included in a file URI, the "file- 534 auth" rule in Section 2 can be replaced with the following: 536 file-auth = "localhost" 537 / [ userinfo "@" ] host 539 This uses the "userinfo" rule from [RFC3986]. 541 As discussed in the HP OpenVMS Systems Documentation 542 543 "access control strings include sufficient information to allow 544 someone to break in to the remote account, [therefore] they create 545 serious security exposure." In a similar vein, the presence of a 546 password in a "user:password" userinfo field is deprecated by 547 [RFC3986]. Take care when dealing with information that can be used 548 to identify a user or grant access to a system. 550 E.2. DOS and Windows Drive Letters 552 On Windows- or DOS-like file systems an absolute file path can begin 553 with a drive letter. To facilitate this, the "local-path" rule in 554 Section 2 can be replaced with the following: 556 local-path = [ drive-letter ] path-absolute 558 drive-letter = ALPHA ":" 560 The "ALPHA" rule is defined in [RFC5234]. 562 This is intended to support the minimal representation of a local 563 file in a DOS- or Windows-like environment, with no authority field 564 and an absolute path that begins with a drive letter. E.g.: 566 o "file:c:/path/to/file" 568 URIs of the form "file:///c:/path/to/file" are already supported by 569 the "path-absolute" rule. 571 Note that comparison of drive letters in DOS or Windows file paths is 572 case-insensitive. In some usages of file URIs drive letters are 573 canonicalized by converting them to uppercase, and other usages treat 574 URIs that differ only in the case of the drive letter as identical. 576 E.2.1. Relative Resolution 578 To mimic the behaviour of DOS- or Windows-like file systems, relative 579 references beginning with a slash "/" can be resolved relative to the 580 drive letter, when present; and resolution of ".." dot segments (per 581 Section 5.2.4 of [RFC3986]) can be modified to not ever overwrite the 582 drive letter. 584 For example: 586 base URI: file:///c:/path/to/file.txt 587 rel. ref.: /some/other/thing.bmp 588 resolved: file:///c:/some/other/thing.bmp 590 base URI: file:///c:/foo.txt 591 rel. ref.: ../bar.txt 592 resolved: file:///c:/bar.txt 594 A relative reference starting with a drive letter would be 595 interpreted by a generic URI parser as a URI with the drive letter as 596 its scheme. Instead such a reference ought to be constructed with a 597 leading slash "/" character (e.g. "/c:/foo.txt"). 599 Relative references with a drive letter followed by a character other 600 than a slash (e.g. "/c:bar/baz.txt" or "/c:../foo.txt") might not be 601 accepted as dereferenceable URIs in DOS- or Windows-like systems. 603 E.2.2. Vertical Line Character 605 Historically some usages of file URIs have included a vertical line 606 character "|" instead of a colon ":" in the drive letter construct. 607 [RFC3986] forbids the use of the vertical line, however it may be 608 necessary to interpret or update old URIs. 610 For interpreting such URIs, the "auth-path" and "local-path" rules in 611 Section 2 and the "drive-letter" rule above can be replaced with the 612 following: 614 auth-path = [ file-auth ] path-absolute 615 / [ file-auth ] file-absolute 617 local-path = [ drive-letter ] path-absolute 618 / file-absolute 620 file-absolute = "/" drive-letter path-absolute 622 drive-letter = ALPHA ":" 623 / ALPHA "|" 625 This is intended to support regular DOS or Windows file URIs with 626 vertical line characters in the drive letter construct. E.g.: 628 o "file:///c|/path/to/file" 630 o "file:/c|/path/to/file" 632 o "file:c|/path/to/file" 634 To update such an old URI, replace the vertical line "|" with a colon 635 ":". 637 E.3. UNC Strings 639 Some usages of the file URI scheme allow UNC filespace selector 640 strings [MS-DTYP] to be translated to and from file URIs, either by 641 mapping the equivalent segments of the two schemes (hostname to 642 authority, sharename+objectnames to path), or by mapping the entire 643 UNC string to the path segment of a URI. 645 E.3.1. file URI with Authority 647 The following is an algorithmic description of the process of 648 translating a UNC filespace selector string to a file URI by mapping 649 the equivalent segments of the two schemes: 651 1. Initialize the URI with the "file:" scheme identifier. 653 2. Append the authority: 655 1. Append the "//" authority sigil to the URI. 657 2. Append the host-name field of the UNC string to the URI. 659 3. Append the share-name: 661 1. Transform the share-name to a path segment ([RFC3986], 662 Section 3.3) to conform to the encoding rules of Section 2 of 663 [RFC3986]. 665 2. Append a delimiting slash character "/" and the transformed 666 segment to the URI. 668 4. For each object-name: 670 1. Transform the objectname to a path segment as above. 672 The colon character ":" is allowed as a delimiter before 673 stream-name and stream-type in the file-name, if present. 675 2. Append a delimiting slash character "/" and the transformed 676 segment to the URI. 678 For example: 680 UNC String: \\host.example.com\Share\path\to\file.txt 681 URI: file://host.example.com/Share/path/to/file.txt 683 The inverse algorithm, for translating a file URI to a UNC filespace 684 selector string, is left as an exercise for the reader. 686 E.3.2. file URI with UNC Path 688 It is common to encounter file URIs that encode entire UNC strings in 689 the path, usually with all backslash "\" characters replaced with 690 slashes "/". 692 To interpret such URIs, the "auth-path" rule in Section 2 can be 693 replaced with the following: 695 auth-path = [ file-auth ] path-absolute 696 / unc-authority path-absolute 698 unc-authority = 2*3"/" file-host 700 file-host = inline-IP / IPv4address / reg-name 702 inline-IP = "%5B" ( IPv6address / IPvFuture ) "%5D" 704 This syntax uses the "IPv4address", "IPv6address", "IPvFuture", and 705 "reg-name" rules from [RFC3986]. 707 Note that the "file-host" rule is the same as "host" but with 708 percent-encoding applied to "[" and "]" characters. 710 This extended syntax is intended to support URIs that take the 711 following forms, in addition to those in Appendix B: 713 Non-local files: 715 o The representation of a non-local file, with an empty authority 716 and a complete (transformed) UNC string in the path. E.g.: 718 * "file:////host.example.com/path/to/file" 720 o As above, with an extra slash between the empty authority and the 721 transformed UNC string, as per the syntax defined in [RFC1738]. 722 E.g.: 724 * "file://///host.example.com/path/to/file" 726 This representation is notably used by the Firefox web browser. 727 See Bugzilla#107540 [Bug107540]. 729 It also further limits the definition of a "local file URI" by 730 excluding any file URI with a path that encodes a UNC string. 732 E.4. Backslash as Separator 734 Historically some usages have copied entire file paths into the path 735 components of file URIs. Where DOS or Windows file paths were thus 736 copied the resulting URI strings contained unencoded backslash "\" 737 characters, which are forbidden by both [RFC1738] and [RFC3986]. 739 It may be possible to translate or update such an invalid file URI by 740 replacing all backslashes "\" with slashes "/", if it can be 741 determined with reasonable certainty that the backslashes are 742 intended as path separators. 744 Appendix F. Collected Nonstandard Rules 746 Here are the collected syntax rules for all optional appendices, 747 presented for convenience. This collected syntax is not normative. 749 file-URI = file-scheme ":" file-hier-part 751 file-scheme = "file" 753 file-hier-part = ( "//" auth-path ) 754 / local-path 756 auth-path = [ file-auth ] path-absolute 757 / [ file-auth ] file-absolute 758 / unc-authority path-absolute 760 local-path = [ drive-letter ] path-absolute 761 / file-absolute 763 file-auth = "localhost" 764 / [ userinfo "@" ] host 766 unc-authority = 2*3"/" file-host 768 file-host = inline-IP / IPv4address / reg-name 770 inline-IP = "%5B" ( IPv6address / IPvFuture ) "%5D" 772 file-absolute = "/" drive-letter path-absolute 774 drive-letter = ALPHA ":" 775 / ALPHA "|" 777 This collected syntax is intended to support file URIs that take the 778 following forms: 780 Local files: 782 o A traditional file URI for a local file, with an empty authority. 783 E.g.: 785 * "file:///path/to/file" 787 o The minimal representation of a local file, with no authority 788 field and an absolute path that begins with a slash "/". E.g.: 790 * "file:/path/to/file" 792 o The minimal representation of a local file in a DOS- or Windows- 793 based environment, with no authority field and an absolute path 794 that begins with a drive letter. E.g.: 796 * "file:c:/path/to/file" 798 o Regular DOS or Windows file URIs, with vertical line characters in 799 the drive letter construct. E.g.: 801 * "file:///c|/path/to/file" 803 * "file:/c|/path/to/file" 805 * "file:c|/path/to/file" 807 Non-local files: 809 o The representation of a non-local file, with an explicit 810 authority. E.g.: 812 * "file://host.example.com/path/to/file" 814 o The "traditional" representation of a non-local file, with an 815 empty authority and a complete (transformed) UNC string in the 816 path. E.g.: 818 * "file:////host.example.com/path/to/file" 820 o As above, with an extra slash between the empty authority and the 821 transformed UNC string. E.g.: 823 * "file://///host.example.com/path/to/file" 825 Author's Address 827 Matthew Kerwin 828 Queensland University of Technology 829 Victoria Park Road 830 Kelvin Grove, QLD 4059 831 Australia 833 Email: matthew.kerwin@qut.edu.au