draft-conill-bearcaps-uri-scheme/draft-conill-bearcaps-uri-scheme.md -rw-r--r-- 5.1 KiB
22c458a9Ariadne Conill fix RFC7595 reference 2 years ago

%%% title = "The Bearer Capability URI Scheme" abbrev = "Bearer Capabilities"

ipr = "trust200902" area = "General" workgroup = "Independent Submission" keyword = ["Internet-Draft"]

submissionType = "independent" category = "info"

[pi] toc = "yes"

[seriesInfo] name = "Internet-Draft" value = "draft-conill-bearcaps-uri-scheme-01" stream = "independent" status = "info"

[[author]] initials = "A." surname = "Conill" fullname = "Ariadne Conill" organization = "Pleroma"

[author.address] email = "ariadne@dereferenced.org" %%%

.# Abstract

Bearer Capability URIs provide a mechanism for granting access to anyone who possess a copy of the bearer capability URI. It builds on previous work surrounding capability URLs to improve upon their security properties.



Capability URLs [@!W3C.WD-capability-urls-20140218] grant access to resources to whoever possesses the URL. An example of a case where this is useful would be the URLs included in various transactional e-mails, such as password reset or unsubscribe links. This technique of embedding authority inside the URLs themselves is not without it's problems, however.

Bearer Capability URIs define a new URI scheme and associated composition mechanism that is used to combine a stable URL with an access token. By separating the access token from the URL, it is hoped that several security problems can be solved.

#Requirements Language

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 RFC 2119 [@!RFC2119].

#Construction of Bearer Capability URIs

Bearer Capability URIs combine a stable URI with an access token. An example URI would be:


This example URI would define that the URL https://example.com/ could be accessed with the token 123456 using the appropriate mechanism for https URLs.

#Valid Query Parameters For Bearer Capability URIs

Bearer capability URIs MUST have two query parameters:

  • u: The stable URL that the bearer capability URI is associated with for requests.

  • t: The access token to use for requests.

Bearer capability URIs MUST NOT have any other query parameters.

#Use Of Bearer Tokens In HTTP Requests

For bearer capability URIs which reference http and https URLs, the access token MUST be treated as being equivalent to an OAuth 2.0 Bearer token [@!RFC6750].

For example, given the URI bearcap:?u=https://example.com&t=123456, the following HTTP GET request could be made:

  GET / HTTP/1.1
  Host: example.com
  Authorization: Bearer 123456

#Use Of Bearer Tokens In Non-HTTP Requests

For bearer capability URIs which reference URLs other than http or https URLs, the access token SHOULD be supplied using whatever mechanism is the most appropriate for supplying access tokens for the given protocol.

#Security Considerations

Bearer capability URIs by their design should resolve many security concerns that exist with capability URLs. However, they introduce a few new ones that should be considered when implementing clients that consume them.

#Risk of Exposure

Browsers and other applications which consume URIs are generally not designed to treat them as sensitive information. For example, URIs appear in application logs and the URI bar in browsers and can be copied from these sources easily.

Applications which consume bearcap URIs SHOULD display the underlying stable URL instead of the bearcap URI itself in application logs and other UI elements that would normally display URIs.

#Authority Leakage via HTTP Referer Header

The HTTP Referer header is sent by many HTTP clients to indicate the URL they are fetching the new resource from. In the case of capability URLs, this can result in authority being leaked in the form of server logs, if they log the Referer header value.

Accordingly, clients which are following a bearcap URI MUST NOT send a Referer header containing the bearcap URI when fetching the associated URL. Also, server implementations SHOULD NOT log any bearcap URIs encountered in the Referer header.

#Handling Compromises

In the event that a bearcap URI is disclosed to an undesired party, the person who originally granted access through the bearcap URI must revoke the associated token. This is not dissimilar to any other access token based authorization mechanism.

#General Considerations With Access Tokens

It is strongly suggested that implementors look at the security considerations section of the OAuth 2.0 Bearer Token Usage specification [@!RFC6750].

#IANA Considerations

#Bearcap URI Scheme Registration

This specification registers the following URI Scheme in the URI Schemes Registry [@!RFC7595].

#bearcap URI Scheme Registration Request

Scheme name: bearcap

Status: provisional

Applications/protocols that use this scheme name: The bearcap URI scheme is planned to be used for referring to private resources in the ActivityPub federated network.

Contact: TODO

Change controller: TODO