RFC 8615

Well-Known Uniform Resource Identifiers (URIs)

📅 published May 2019, from ietf

🎀 Well-Known Uniform Resource Identifiers (URIs) 🎀

okay bestie, this is RFC 8615 🦋 It's from the Internet Engineering Task Force (IETF), and it was written by M. Nottingham in May 2019. It's a Standards Track document, so it's a real protocol spec that people actually build against. It obsoletes RFC 5785 (so that older doc is retired now 💀) and it updates RFC 7230 and RFC 7595 (ISSN 2070-1721, if you're keeping receipts ✨). The whole thing is about one reserved path prefix, so let's get into it 💅

Abstract ✨

okay so the big idea is a path prefix, /.well-known/, that gets reserved for "well-known locations" in certain URI schemes 🌸 This memo also obsoletes RFC 5785. It updates the URI schemes defined in RFC 7230 so they reserve that space, and it updates RFC 7595 so the registry can track which schemes support well-known URIs 🫶

Status of This Memo

this is an Internet Standards Track document 💜

it's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). if you want more on Internet Standards, check Section 2 of RFC 7841 📚

for the current status, errata, and how to send feedback, go to https://www.rfc-editor.org/info/rfc8615 🔗

Copyright (c) 2019 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) as they were in effect on the date of publication. please read those carefully because they describe your rights and restrictions for this document 🧚

also, any Code Components pulled out of this document have to include the Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions. they're provided without warranty, as the Simplified BSD License describes 🫶

Table of Contents

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
2.  Notational Conventions  . . . . . . . . . . . . . . . . . . .   3
3.  Well-Known URIs . . . . . . . . . . . . . . . . . . . . . . .   3
  3.1.  Registering Well-Known URIs . . . . . . . . . . . . . . .   4
4.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
  4.1.  Protecting Well-Known Resources . . . . . . . . . . . . .   6
  4.2.  Interaction with Web Browsing . . . . . . . . . . . . . .   6
  4.3.  Scoping Applications  . . . . . . . . . . . . . . . . . .   7
  4.4.  Hidden Capabilities . . . . . . . . . . . . . . . . . . .   8
5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
  5.1.  The Well-Known URI Registry . . . . . . . . . . . . . . .   8
  5.2.  The Uniform Resource Identifier (URI) Schemes Registry  .   9
6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   9
  6.1.  Normative References  . . . . . . . . . . . . . . . . . .   9
  6.2.  Informative References  . . . . . . . . . . . . . . . . .  10
Appendix A.  Frequently Asked Questions . . . . . . . . . . . . .  12
Appendix B.  Changes from RFC 5785  . . . . . . . . . . . . . . .  12
Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  12

1. Introduction 🌸

some Web applications need to find out information about an origin [RFC6454] (people call this "site-wide metadata") before they make a request 👀 for example, the Robots Exclusion Protocol (http://www.robotstxt.org) is how automated processes get permission to access resources. and the Platform for Privacy Preferences [P3P] tells user agents where to find a site's privacy policy before they interact with the origin server 🔐

there are other ways to get per-resource metadata, like HTTP header fields or PROPFIND in Web Distributed Authoring and Versioning (WebDAV) [RFC4918]. but the overhead (whether that's client-perceived latency, deployment headaches, or both) often rules them out for these site-wide cases 💀

meanwhile, HTTP has become a popular substrate for non-Web protocols 🦋 those protocols sometimes need to find one or more resources on a given host, and that's where it gets messy.

one fix is to pick a "well-known location" for data or services tied to the origin as a whole, so anyone can find it easily. the catch is that it risks collisions, both with other "well-known locations" and with resources the origin already made (or wants to make later) 😭 on top of that, defining well-known locations takes away the origin's control over its own URI space [RFC7320] 🙈

so, to handle all of this, this memo reserves a path prefix, /.well-known/, for these "well-known locations" in HTTP, HTTPS, WebSocket (WS), and Secure WebSocket (WSS) URIs ✨ future specs that need a resource for this kind of metadata can register their use, which avoids collisions and keeps the impact on origins' URI space small 🫶

well-known URIs can also be used with other URI schemes, but only when those schemes' own definitions explicitly allow it 🧚

2. Notational Conventions 💜

okay this one's the BCP 14 part, so pay attention 🤓 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 💅 so if you see them in lowercase, they're just regular words, not requirements ✨

3. Well-Known URIs 🎀

a well-known URI is a URI [RFC3986] whose path component starts with the characters /.well-known/, as long as the scheme has been explicitly defined to support well-known URIs 🦋

for example, if an application registers the name example, then the matching well-known URI on http://www.example.com/ would be http://www.example.com/.well-known/example 🌈

this specification updates the "http" [RFC7230] and "https" [RFC7230] schemes so they support well-known URIs. other existing schemes can use the right process to update their own definitions. for instance, [RFC8307] does that for the "ws" and "wss" schemes ⭐ the "Uniform Resource Identifier (URI) Schemes" registry keeps track of which schemes support well-known URIs, so check Section 5.2 for that 📚

applications that want to mint new well-known URIs MUST register them. they follow the procedures in Section 5.1 and meet the requirements below 💖

registered names MUST conform to the "segment-nz" production in [RFC3986]. that means they can't contain the / character 🙅‍♀️

registered names for a specific application SHOULD be pretty precise. "squatting" on generic terms is not encouraged 👑 for example, if the Example application wants a well-known location for metadata, a good registered name could be example-metadata or even example.com-metadata, but not metadata 🍓

at a minimum, a registration has to reference a specification that defines the format and associated media type(s) you get back when you dereference the well-known URI, plus the URI scheme(s) it can be used with. if no URI schemes are explicitly specified, then "http" and "https" are assumed 🫶

applications will typically use the default port for the given scheme. if they use an alternative port, the application in question MUST explicitly specify it 🔥

registrations MAY also include extra info, like the syntax of additional path components, query strings, and/or fragment identifiers to append to the well-known URI, or protocol-specific details (for example, HTTP [RFC7231] method handling) 🌸

this specification doesn't define how to figure out the hostname you use to find the well-known URI for a particular application, and it doesn't define the scope of the metadata you discover by dereferencing it. both of those should be defined by the application itself 🧚

also, this specification doesn't define a format or media type for the resource at /.well-known/, and clients should not expect a resource to exist at that location 🙈

well-known URIs are rooted at the top of the path hierarchy. they aren't well-known by definition anywhere else in the path. for example, /.well-known/example is a well-known URI, but /foo/.well-known/example is not 💀

see also Section 4 for the Security Considerations around well-known locations 🔐

ngl, Section 3.1 is where the registry drama lives, so stay tuned 👀

4.1. Protecting Well-Known Resources 🛡️

okay bestie, well-known locations effectively represent the entire origin 🌸, so server operators should appropriately control who can write to them. This is especially true when more than one entity is co-located on the same origin 👀. Even when an origin is controlled by and represents a single entity, due care should be taken to make sure write access to well-known locations is not granted unwittingly 💅. That can happen externally through server configuration, or locally through implementation permissions (e.g., on a filesystem) 😭.

4.2. Interaction with Web Browsing 🌐

applications using well-known URIs for "http" or "https" URLs need to be aware that well-known resources are accessible to Web browsers 👀. That means content from other parts of that origin can manipulate them 🫣. If an attacker can inject content (e.g., through a Cross-Site Scripting vulnerability), they can make potentially arbitrary requests to the well-known resource 💀.

HTTP and HTTPS also use origins as a security boundary for lots of other mechanisms, including (but not limited to) cookies [RFC6265], Web Storage [WEBSTORAGE], and various capabilities 🍓.

an application that defines well-known locations should not assume it has sole access to these mechanisms, or that it's the only application using the origin 🙈. Depending on the nature of the application, mitigations can include:

  • Encrypting sensitive information 🔐
  • Allowing flexibility in the use of identifiers (e.g., cookie names) to avoid collisions with other applications
  • Using the HttpOnly flag on cookies to assure that cookies are not exposed to browser scripting languages [RFC6265]
  • Using the Path parameter on cookies to assure that they are not available to other parts of the origin [RFC6265]
  • Using X-Content-Type-Options: nosniff [FETCH] to assure that content under attacker control can't be coaxed into a form that is interpreted as active content by a Web browser

other good practices include:

  • Using an application-specific media type in the Content-Type header field, and requiring clients to fail if it is not used
  • Using Content-Security-Policy [CSP] to constrain the capabilities of active content (such as HTML [HTML5]), thereby mitigating Cross-Site Scripting attacks 🛑
  • Using Referrer-Policy [REFERRER-POLICY] to prevent sensitive data in URLs from being leaked in the Referer request header field 🤫
  • Avoiding use of compression on any sensitive information (e.g., authentication tokens, passwords), as the scripting environment offered by Web browsers allows an attacker to repeatedly probe the compression space. If the attacker has access to the path of the communication, they can use this capability to recover that information 😱

4.3. Scoping Applications 🎯

this memo does not specify the scope of applicability for the information obtained from a well-known URI, and it does not specify how to discover a well-known URI for a particular application 🤷‍♀️.

individual applications using this mechanism must define both aspects. If this is not specified, security issues can arise from implementation deviations and confusion about boundaries between applications 🌀.

applying metadata discovered in a well-known URI to resources other than those co-located on the same origin risks administrative as well as security issues 🚩. For example, allowing https://example.com/.well-known/example to apply policy to https://department.example.com, https://www.example.com, or even https://www.example.com:8000 assumes a relationship between hosts where there might be none, thereby giving control to a potential attacker 😈.

likewise, specifying that a well-known URI on a particular hostname is to be used to bootstrap a protocol can cause a large number of undesired requests 📬. For example, if a well-known HTTPS URI is used to find policy about a separate service such as email, it can result in a flood of requests to Web servers, even if they don't implement the well-known URI 🌊. Such undesired requests can resemble a denial-of-service attack 🚨.

4.4. Hidden Capabilities 🫥

applications using well-known locations should consider that some server administrators might be unaware of their existence 👻. This is especially true on operating systems that hide directories whose names begin with .. That means if an attacker has write access to the .well-known directory, they would be able to control its contents, possibly without the administrator realising it 😭.

5. IANA Considerations 📋

5.1. The Well-Known URI Registry 🗂️

this specification updates the registration procedures for the "Well-Known URI" registry, first defined in [RFC5785]; see Section 3.1 ✨.

Well-known URIs are registered on the advice of one or more experts, with a Specification Required (using terminology from [RFC8126]) 🧐.

the experts' primary considerations in evaluating registration requests are:

  • Conformance to the requirements in Section 3
  • The availability and stability of the specifying document
  • The considerations outlined in Section 4

IANA will direct the senders of any incoming registry requests to this document and, if defined, the processes established by the expert(s). Typically, this will mean referring them to the registry Web page 💌.

per this document, IANA has:

  • Updated the registration procedure to Specification Required.
  • Added a "Status" column to the registry and marked all of the existing registrations as "permanent" 🔖.

5.2. The Uniform Resource Identifier (URI) Schemes Registry 🌈

this specification adds a field to the registration template of the "Uniform Resource Identifier (URI) Schemes" registry, with the name "Well-Known URI Support" and a default value of "-" 🎀.

if a URI scheme explicitly has been specified to use well-known URIs as per Section 3, the value changes to a reference to that specification. Initial values not equal to "-" are given in Table 1 💖.

+------------+------------------------+
| URI Scheme | Well-Known URI Support |
+------------+------------------------+
| coap       | [RFC7252]              |
| coap+tcp   | [RFC8323]              |
| coap+ws    | [RFC8323]              |
| coaps      | [RFC7252]              |
| coaps+tcp  | [RFC8323]              |
| coaps+ws   | [RFC8323]              |
| http       | [RFC8615]              |
| https      | [RFC8615]              |
| ws         | [RFC8307]              |
| wss        | [RFC8307]              |
+------------+------------------------+

Table 1: Rows in URI Scheme Registry with Nonempty New Column

6. References 📚

6.1. Normative References 🧾

6.2. Informative References 📚✨

okay bestie, these are the extra reading refs, the ones that give helpful background but aren't required to implement this spec 🤓 here they are, all exact:

Appendix A. Frequently Asked Questions 🙋‍♀️💖

okay, the FAQ! these are the questions everyone secretly wonders about 🫶

Aren't well-known locations bad for the Web?

They kinda are 😬 but for technical and social reasons they're sometimes necessary anyway. This memo defines a "sandbox" for them, so there's less risk of collisions and less mess for preexisting URIs on sites. ✨

Why "/.well-known?"

It's short 💅, it's descriptive 📝, and according to search indices it isn't widely used already 🧚. Honestly, very on brand.

What impact does this have on existing mechanisms, such as P3P and robots.txt?

None! 🌸 Not unless they decide to adopt this mechanism.

Why aren't per-directory well-known locations defined?

Because if every path segment got its own well-known location, like /images/.well-known/, you'd have way more chances of colliding with a URI that already exists on a site 💀. Those kinds of solutions also don't scale well, since they're too "chatty" 🙈.

Appendix B. Changes from RFC 5785 🦋

here's what's new compared to RFC 5785, the glow-up list 💜

  • Allowed non-Web well-known locations
  • Adjusted IANA instructions
  • Updated references
  • Made various other clarifications
  • Tracked supporting schemes in the "Uniform Resource Identifier (URI) Schemes" registry

Author's Address 🎀

Mark Nottingham

and that's a wrap, bestie!! 🌈💖

📦 where this page comes from