Queensland University of Technology

Victoria Park Road Kelvin Grove QLD 4059 Australia matthew.kerwin@qut.edu.au

General Applications Area Working Group Internet-Draft This document provides a more complete specification of the “file” Uniform Resource Identifier (URI) scheme, replacing the very brief definition in Section 3.10 of RFC 1738. It defines a common syntax which is intended to interoperate across the broad spectrum of existing usages. At the same time it notes some other current practices around the use of file URIs. This draft should be discussed on the IETF Applications Area Working Group discussion list <apps-discuss@ietf.org>.

A file URI identifies an object (a “file”) stored in a structured object naming and accessing environment on a host (a “file system.”) The URI can be used in discussions about the file, and if other conditions are met it can be dereferenced to directly access the file. This document specifies a syntax based on the generic syntax of that is compatible with most existing usages. Where incompatibilities arise they are usually in parts of the scheme that were underspecified in earlier definitions and have been tightened up by more recent specifications. lists significant changes to syntax. Extensions to the syntax which might be encountered in practice are listed in ; these extensions are listed for informational purposes and are not a requirement of implementation. The file URI scheme is not coupled with a specific protocol, nor with a specific media type . See for a discussion of operations that can be performed on the object identified by a file URI.

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in when they appear in all upper case. They may also appear in lower or mixed case as English words, without normative meaning. Throughout this document the term “local file” is used to describe files that can be accessed through the local file system API using only the information included in the file path, not relying on other information (such as network addresses.) It is important to note that a local file may not be physically located on the local machine, for example if a networked file system is transparently mounted into the local file system. The term “local file URI” is used to describe file URIs which have no authority component, or where the authority is the special string “localhost” or a fully qualified domain name that resolves to the machine from which the URI is being interpreted ().

The file URI syntax is defined here in Augmented Backus-Naur Form (ABNF) , importing the host and path-absolute rules from (as updated by .) The generic syntax in includes path and authority components, for each of which only a subset is used in the definition of the file URI scheme. The relevant subset of path is path-absolute, and the subset of authority is file-auth, given below. The syntax definition below is different from those given in and as it is derived from the generic syntax of , which post-dates the previous file URI specifications. enumerates significant differences.

The host is the fully qualified domain name of the system on which the file is accessible. This allows a client on another system to know that it cannot access the file system, or perhaps that it needs to use some other local mechanism to access the file. As a special case, the file-auth rule can match the string “localhost” which is interpreted as “the machine from which the URI is being interpreted,” exactly as if no authority were present. Some current usages of the scheme incorrectly interpret all values in the authority of a file URI, including “localhost”, as non-local. Yet others interpret any value as local, even if the host does not resolve to the local machine. To maximize compatibility with previous specifications, users MAY choose to include an auth-path with no file-auth when creating a URI. The path component represents the absolute path to the file in the file system. See for some discussion of system-specific concerns including absolute file paths and file system roots. Some file systems have case-sensitive file naming and some do not. As such the file URI scheme supports case sensitivity, in order to retain the case as given. Any transport-related handling of the file URI scheme MUST retain the case as given. Any mapping to or from a case-insensitive form is solely the responsibility of the implementation processing the file URI on behalf of the referenced file system. Also see that lists some nonstandard syntax variations that can be encountered in practice.

See the POSIX file and directory operations for examples of standardized operations that can be performed on files. A file URI can be dependably dereferenced or translated to a local file path only if it is local. A file URI is considered “local” if it has no file-auth, or the file-auth is the special string “localhost” or a fully qualified domain name that resolves to the machine from which the URI is being interpreted (). This specification neither defines nor forbids any set of operations that might be performed on a file identified by a non-local file URI.

File systems use various encoding schemes to store file and directory names. Many modern file systems store file and directory names as arbitrary sequences of octets, in which case the representation as an encoded string often depends on the user’s localization settings, or defaults to UTF-8 . When a file URI is produced that represents textual data consisting of characters from the Unicode Standard coded character set , the data SHOULD be encoded as octets according to the UTF-8 character encoding scheme before percent-encoding is applied; as per , Section 2.5. A decision not to use percent-encoded UTF-8 is outside the scope of this specification. It will typically require the use of heuristics or explicit knowledge about the way the string will be processed.

There are many security considerations for URI schemes discussed in . File access and the granting of privileges for specific operations are complex topics, and the use of file URIs can complicate the security model in effect for file privileges. Historically, user agents have granted content from the file URI scheme a tremendous amount of privilege. However, granting all local files such wide privileges can lead to privilege escalation attacks. Some user agents have had success granting local files directory-based privileges, but this approach has not been widely adopted. Other user agents use globally unique identifiers as the origin for each file URI , which is the most secure option. Treating a non-local file URI as local or otherwise attempting to perform local operations on a non-local URI can result in security problems. File systems typically assign an operational meaning to special characters, such as the “/”, “\”, “:”, “[”, and “]” characters, and to special device names like “.”, “..”, “…”, “aux”, “lpt”, etc. In some cases, merely testing for the existence of such a name will cause the operating system to pause or invoke unrelated system calls, leading to significant security concerns regarding denial of service and unintended data transfer. It would be impossible for this specification to list all such significant characters and device names. Implementers MUST research the reserved names and characters for the types of storage device that may be attached to their application and restrict the use of data obtained from URI components accordingly. File systems vary in the way they handle case. Care MUST be taken to avoid issues resulting from possibly unexpected aliasing from case-only differences between file paths or URIs, or from mismatched encodings or Unicode equivalences (see ).

This document defines the following URI scheme, so the “Permanent URI Schemes” registry has been updated accordingly. This registration complies with . file permanent Commonly used in hypertext documents to refer to files without depending on network access. Supported by major browsers. Used in development libraries, such as: Windows Shell (PathCreateFromUrl, UrlCreateFromPath). libwww-perl - The World-Wide Web library for Perl. Applications and Real-Time Area <art@ietf.org> This scheme is registered under the IETF tree. As such, the IETF maintains change control. This RFC.

Contributions from many members of the IETF and W3C communities – notably Dave Crocker, Graham Klyne, Tom Petch, and John Klensin – are greatly appreciated. Additional thanks to Dave Risney, author of the informative IE Blog article <http://blogs.msdn.com/b/ie/archive/2006/12/06/file-uris-in-windows.aspx>, and Dave Thaler for their early comments and suggestions; and to Paul Hoffman, whose earlier work served as an inspiration for this undertaking.

In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] Internet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK] This document defines the concept of an "origin", which is often used as the scope of authority or privilege by user agents. Typically, user agents isolate content retrieved from different origins to prevent malicious web site operators from interfering with the operation of benign web sites. In addition to outlining the principles that underlie the concept of origin, this document details how to determine the origin of a URI and how to serialize an origin into a string. It also defines an HTTP header field, named "Origin", that indicates which origins are associated with an HTTP request. [STANDARDS-TRACK] This document describes how the zone identifier of an IPv6 scoped address, defined as <zone_id> in the IPv6 Scoped Address Architecture (RFC 4007), can be represented in a literal IPv6 address and in a Uniform Resource Identifier that includes such a literal address. It updates the URI Generic Syntax specification (RFC 3986) accordingly. This document defines the syntax used by the World-Wide Web initiative to encode the names and addresses of objects on the Internet. This memo provides information for the Internet community. This memo does not specify an Internet standard of any kind. This document specifies a Uniform Resource Locator (URL), the syntax and semantics of formalized information for location and access of resources via the Internet. [STANDARDS-TRACK] This document defines a grammar that is a superset of all valid URI, such that an implementation can parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier type. [STANDARDS-TRACK] This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. Free Software Foundation, Inc WHATWG Microsoft Open Specifications IEEE The Unicode Consortium Microsoft Developer Network Bugzilla@Mozilla

The syntax definition in inherits incremental differences from the general syntax of made by (, Appendix G) and (, Appendix D). According to the definition in a file URL always started with the token “file://”, followed by an (optionally blank) host name and a “/”. The syntax given in makes the entire authority component, including the double slashes “//”, optional.

The syntax in is intended to support file URIs that take the following forms: Local files: A traditional file URI for a local file, with an empty authority. This is the most common format in use today. E.g.: file:///path/to/file The minimal representation of a local file, with no authority field and an absolute path that begins with a slash “/”. E.g.: file:/path/to/file Non-local files: A non-local file, with an explicit authority. E.g.: file://host.example.com/path/to/file

The WHATWG defines a living URL standard , which includes algorithms for interpreting file URIs (as URLs). The Universal Naming Convention (UNC) defines a string format that can perform a similar role to the file URI scheme in describing the location of files, except that files located by UNC filespace selector strings are typically stored on a remote machine and accessed using a network protocol. lists some ways in which UNC filespace selector strings are currently made to interoperate with the file URI scheme. The Microsoft Windows API defines Win32 Namespaces for interacting with files and devices using Windows API functions. These namespaced paths are prefixed by “\\?\” for Win32 File Namespaces and “\\.\” for Win32 Device Namespaces. There is also a special case for UNC file paths in Win32 File Namespaces, referred to as “Long UNC”, using the prefix “\\?\UNC\”. This specification does not define a mechanism for translating namespaced paths to or from file URIs.

This appendix is not normative. It highlights some observed behaviours and provides system-specific guidance for interacting with file URIs and paths. This is not an exhaustive list of operating or file systems; rather it is intended to illustrate certain types of interactions that might be encountered.

In a POSIX file system the root of the file system is represented as a directory with a zero-length name, usually written as “/”; the presence of this root in a file URI can be taken as given by the initial slash in the path-absolute rule. Common UNIX shells such as the Bourne-Again SHell (bash) and Z Shell (zsh) provide a function known as “tilde expansion” or “filename expansion” , where a path that begins with a tilde character “~” can be expanded out to a special directory name. No such facility exists using the file URI scheme; a tilde in a file URI is always just a tilde.

When mapping a DOS- or Windows-like file path to a file URI, the drive letter (e.g. “c:”) is typically mapped into the first path segment. lists some nonstandard techniques for interacting with DOS- or Windows-like file paths and URIs.

The HFS+ file system uses a nonstandard normalization form, similar to Normalization Form D . Take care when transforming HFS+ file paths to and from URIs ().

When mapping a VMS file path to a file URI, the device name is mapped into the first path segment. Note that the dollars sign “$” is a reserved character per the definition in , Section 2.2, so should be percent-encoded if present in the device name. If the VMS file path includes a node reference, that reference is used as the authority. Where the original node reference includes a user name and password in an access control string, they can be transcribed into the authority using the nonstandard syntax extension in .

These variations may be encountered by existing usages of the file URI scheme, but are not supported by the normative syntax of . This appendix is not normative.

It might be necessary to include user information such as a user name in a file URI, for example when mapping a VMS file path with a node reference that includes an access control string. To allow user information to be included in a file URI, the file-auth rule in can be replaced with the following:

This uses the userinfo rule from . As discussed in the HP OpenVMS Systems Documentation <http://h71000.www7.hp.com/doc/84final/ba554_90015/ch03s09.html> “access control strings include sufficient information to allow someone to break in to the remote account, [therefore] they create serious security exposure.” In a similar vein, the presence of a password in a “user:password” userinfo field is deprecated by . Take care when dealing with information that can be used to identify a user or grant access to a system.

On Windows- or DOS-like file systems an absolute file path can begin with a drive letter. To facilitate this, the local-path rule in can be replaced with the following:

The ALPHA rule is defined in . This is intended to support the minimal representation of a local file in a DOS- or Windows-like environment, with no authority field and an absolute path that begins with a drive letter. E.g.: file:c:/path/to/file URIs of the form file:///c:/path/to/file are already supported by the path-absolute rule. Note that comparison of drive letters in DOS or Windows file paths is case-insensitive. In some usages of file URIs drive letters are canonicalized by converting them to uppercase, and other usages treat URIs that differ only in the case of the drive letter as identical.

To mimic the behaviour of DOS- or Windows-like file systems, relative references beginning with a slash “/” can be resolved relative to the drive letter, when present; and resolution of “..” dot segments (per Section 5.2.4 of ) can be modified to not ever overwrite the drive letter. For example:

A relative reference starting with a drive letter would be interpreted by a generic URI parser as a URI with the drive letter as its scheme. Instead such a reference ought to be constructed with a leading slash “/” character (e.g. “/c:/foo.txt”). Relative references with a drive letter followed by a character other than a slash (e.g. “/c:bar/baz.txt” or “/c:../foo.txt”) might not be accepted as dereferenceable URIs in DOS- or Windows-like systems.

Historically some usages of file URIs have included a vertical line character “|” instead of a colon “:” in the drive letter construct. forbids the use of the vertical line, however it may be necessary to interpret or update old URIs. For interpreting such URIs, the auth-path and local-path rules in and the drive-letter rule above can be replaced with the following:

This is intended to support regular DOS or Windows file URIs with vertical line characters in the drive letter construct. E.g.: file:///c|/path/to/file file:/c|/path/to/file file:c|/path/to/file To update such an old URI, replace the vertical line “|” with a colon “:”.

Some usages of the file URI scheme allow UNC filespace selector strings to be translated to and from file URIs, either by mapping the equivalent segments of the two schemes (hostname to authority, sharename+objectnames to path), or by mapping the entire UNC string to the path segment of a URI.

The following is an algorithmic description of the process of translating a UNC filespace selector string to a file URI by mapping the equivalent segments of the two schemes: Initialize the URI with the “file:” scheme identifier. Append the authority: Append the “//” authority sigil to the URI. Append the host-name field of the UNC string to the URI. Append the share-name: Transform the share-name to a path segment (, Section 3.3) to conform to the encoding rules of Section 2 of . Append a delimiting slash character “/” and the transformed segment to the URI. For each object-name: Transform the objectname to a path segment as above. The colon character “:” is allowed as a delimiter before stream-name and stream-type in the file-name, if present. Append a delimiting slash character “/” and the transformed segment to the URI. For example:

The inverse algorithm, for translating a file URI to a UNC filespace selector string, is left as an exercise for the reader.

It is common to encounter file URIs that encode entire UNC strings in the path, usually with all backslash “\” characters replaced with slashes “/”. To interpret such URIs, the auth-path rule in can be replaced with the following:

This syntax uses the IPv4address, IPv6address, IPvFuture, and reg-name rules from . Note that the file-host rule is the same as host but with percent-encoding applied to “[” and “]” characters. This extended syntax is intended to support URIs that take the following forms, in addition to those in : Non-local files: The representation of a non-local file, with an empty authority and a complete (transformed) UNC string in the path. E.g.: file:////host.example.com/path/to/file As above, with an extra slash between the empty authority and the transformed UNC string, as per the syntax defined in . E.g.: file://///host.example.com/path/to/file This representation is notably used by the Firefox web browser. See Bugzilla#107540 . It also further limits the definition of a “local file URI” by excluding any file URI with a path that encodes a UNC string.

Historically some usages have copied entire file paths into the path components of file URIs. Where DOS or Windows file paths were thus copied the resulting URI strings contained unencoded backslash “\” characters, which are forbidden by both and . It may be possible to translate or update such an invalid file URI by replacing all backslashes “\” with slashes “/”, if it can be determined with reasonable certainty that the backslashes are intended as path separators.

Here are the collected syntax rules for all optional appendices, presented for convenience. This collected syntax is not normative.

This collected syntax is intended to support file URIs that take the following forms: Local files: A traditional file URI for a local file, with an empty authority. E.g.: file:///path/to/file The minimal representation of a local file, with no authority field and an absolute path that begins with a slash “/”. E.g.: file:/path/to/file The minimal representation of a local file in a DOS- or Windows-based environment, with no authority field and an absolute path that begins with a drive letter. E.g.: file:c:/path/to/file Regular DOS or Windows file URIs, with vertical line characters in the drive letter construct. E.g.: file:///c|/path/to/file file:/c|/path/to/file file:c|/path/to/file Non-local files: The representation of a non-local file, with an explicit authority. E.g.: file://host.example.com/path/to/file The “traditional” representation of a non-local file, with an empty authority and a complete (transformed) UNC string in the path. E.g.: file:////host.example.com/path/to/file As above, with an extra slash between the empty authority and the transformed UNC string. E.g.: file://///host.example.com/path/to/file