| Applications Area Working Group | M. Kerwin |
| Internet-Draft | QUT |
| Obsoletes: 8089 (if approved) | December 19, 2018 |
| Intended status: Standards Track | |
| Expires: June 22, 2019 |
The file URI Scheme
draft-kerwin-rfc8089-bis-core-latest
This document provides a specification of the “file” Uniform Resource Identifier (URI) scheme. It defines a common syntax which is intended to interoperate across the broad spectrum of existing usages. It obsoletes RFC 8089.
This draft should be discussed on the GitHub repository <https://github.com/phluid61/internet-drafts/labels/rfc8089-bis-core>.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on June 22, 2019.
Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
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 [RFC3986] 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. Appendix A lists significant changes from historical syntax definitions.
Extensions to the syntax which might be encountered in practice are listed in [draft-kerwin-rfc8089-bis-info]; those extensions are given 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 [RFC6838]. See Section 3 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”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
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 (Section 2).
The file URI syntax is defined here in Augmented Backus-Naur Form (ABNF) [RFC5234], importing the host and path-absolute rules from [RFC3986] (as updated by [RFC6874]), and ALPHA from [RFC5234].
The generic syntax in [RFC3986] 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 previous definitions. Appendix A enumerates significant differences.
file-URI = file-scheme ":" file-hier-part
file-scheme = "file" ; case-insensitive
file-hier-part = ( "//" auth-path )
/ local-path
auth-path = [ file-auth ] path-absolute
local-path = path-absolute
/ ( drive-letter path-absolute )
drive-letter = ALPHA ":" ; case-insensitive
file-auth = "localhost" ; RFC 3986 "authority", as
/ host ; applicable to a file URI
Past specifications mandated an authority component preceded by two slash characters (“//”) in all file URIs; however in practice implementations have relaxed this requirement so the file-hier-part rule includes a local-path option without an authority component.
The file-auth rule can match either:
Various implementations have mixed these definitions, for example interpreting “localhost” as a remote host name, or treating any host name as “localhost”. So while users and systems MAY include an auth-path when creating a file URI, to maximize compatibility with previous specifications, they SHOULD NOT include a file-auth in the auth-path of any file URI they create.
The path component represents the absolute path to the file in the file system. Note that both auth-path and local-path use the path-absolute rule which begins with a slash character (“/”). In the case of auth-path the slash serves both to separate the path from the authority, and to represent the [POSIX] convention that a path beginning with a slash character is relative to the root of the file system. In local-path it solely represents the [POSIX] convention, and MAY be omitted before the drive letter when representing an absolute path in a MS-DOS or Windows file system.
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.
Fragment components ([RFC3986], Section 3.5) are supported according to [RFC3986], however the specific syntax and semantics of a fragment depend on the media type of the representation of the retrieved resource. As the file URI scheme does not have a mechanism for detecting or communicating the content type of resources, any fragment on a file URI is inherently meaningless. However in practice there are mechanisms to detect or guess the media type of a file, which can provide meaning for fragment components. [[TODO: are there any security concerns here?]]
See the POSIX file and directory operations [POSIX] 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 (Section 2).
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 [STD63].
When a file URI is produced that represents textual data consisting of characters from the Unicode Standard coded character set [UNICODE], the data SHOULD be encoded as octets according to the UTF-8 character encoding scheme [STD63] before percent-encoding is applied; as per [RFC3986], 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 [RFC3986].
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 [RFC6454], 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 not be possible for this specification to list all such significant characters and device names. Implementers should 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 [UAX15] (see Section 4).
This document defines the following URI scheme, so the “Permanent URI Schemes” registry has been updated accordingly. This registration complies with [BCP35].
This document is derived directly from [RFC8089]. All thanks and acknowledgements in that document apply equally to this.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC3986] | Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005. |
| [RFC5234] | Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008. |
| [RFC6454] | Barth, A., "The Web Origin Concept", RFC 6454, DOI 10.17487/RFC6454, December 2011. |
| [RFC6874] | Carpenter, B., Cheshire, S. and R. Hinden, "Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers", RFC 6874, DOI 10.17487/RFC6874, February 2013. |
| [RFC8174] | Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017. |
| [STD63] | Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003. |
The syntax definition in Section 2 inherits incremental differences from the general syntax of [RFC1738] made by [RFC2396] ([RFC2396], Appendix G) and [RFC3986] ([RFC3986], Appendix D).
According to the definition in [RFC1738] a file URL always started with the token “file://”, followed by an (optionally blank) host name and a “/”. The syntax given in Section 2 makes the entire authority component, including the double slashes “//”, optional.
Further, according to [RFC1738] the initial slash character “/” after the authority was not defined as part of the path component, where [RFC3986] includes the slash in the path. As such, in more modern implementations the path component is often interpreted as a complete file path, including sequences of empty path segments (represented as subsequence slashes).
The definition specified in [RFC8089] did not allow for file URIs with no authority component that start with a MS-DOS or Windows drive letter (for example “file:c:/”). That syntax is allowed in this specification.
The syntax in Section 2 is intended to support file URIs that take the following forms:
Local files:
Non-local files:
This appendix is not normative, and does not include requirements for conformance or interoperability. It highlights some observed behaviours and provides system-specific guidance for interacting with file URIs and file system 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” [Bash-Tilde] or “filename expansion” [Zsh-Tilde], 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 MS-DOS or Windows file path to a file URI, the drive letter (e.g. “c:”) is typically mapped into the first path segment.
A relative reference starting with a drive letter (e.g. “c:/foo.txt”) would be interpreted by a generic URI parser as a URI with the drive letter as its scheme. Instead such a reference would be constructed with a leading slash “/” character (e.g. “/c:/foo.txt”).
Absolute file URIs without a drive letter are resolved relative to the current context (i.e. with the same drive letter as the base URL, or the current working environment if there is no base URL.)
URIs and relative references with a drive letter followed by a character other than a slash (e.g. “file:c:bar/baz.txt” or “/c:../foo.txt”) represent relative file paths and should not be accepted as dereferenceable URIs in MS-DOS or Windows systems and should not be created.
[draft-kerwin-rfc8089-bis-info] lists some nonstandard mechanisms for interacting with MS-DOS or Windows file paths and URIs.
The HFS+ file system uses a nonstandard normalization form, similar to Normalization Form D [UAX15]. Take care when transforming HFS+ file paths to and from URIs (Section 4).
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 [RFC3986], 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 a nonstandard extension described in [draft-kerwin-rfc8089-bis-info].