Independent Submission A. Conill
Internet-Draft Pleroma
Intended status: Informational 17 October 2019
Expires: 19 April 2020
The Bearer Capability URI Scheme
draft-conill-bearcaps-uri-scheme-01
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.
Status of This Memo
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 19 April 2020.
Copyright Notice
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) 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.
Conill Expires 19 April 2020 [Page 1]
Internet-Draft Bearer Capabilities October 2019
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Requirements Language . . . . . . . . . . . . . . . . . . . . 2
3. Construction of Bearer Capability URIs . . . . . . . . . . . 2
3.1. Valid Query Parameters For Bearer Capability URIs . . . . 3
3.2. Use Of Bearer Tokens In HTTP Requests . . . . . . . . . . 3
3.3. Use Of Bearer Tokens In Non-HTTP Requests . . . . . . . . 3
4. Security Considerations . . . . . . . . . . . . . . . . . . . 3
4.1. Risk of Exposure . . . . . . . . . . . . . . . . . . . . 3
4.2. Authority Leakage via HTTP Referer Header . . . . . . . . 4
4.3. Handling Compromises . . . . . . . . . . . . . . . . . . 4
4.4. General Considerations With Access Tokens . . . . . . . . 4
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4
5.1. Bearcap URI Scheme Registration . . . . . . . . . . . . . 4
5.1.1. bearcap URI Scheme Registration Request . . . . . . . 4
6. Normative References . . . . . . . . . . . . . . . . . . . . 5
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5
1. Introduction
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.
2. 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].
3. Construction of Bearer Capability URIs
Bearer Capability URIs combine a stable URI with an access token. An
example URI would be:
bearcap:?u=https://example.com&t=123456
This example URI would define that the URL "https://example.com/"
Conill Expires 19 April 2020 [Page 2]
Internet-Draft Bearer Capabilities October 2019
could be accessed with the token "123456" using the appropriate
mechanism for "https" URLs.
3.1. 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.
3.2. 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
3.3. 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.
4. 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.
4.1. 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.
Conill Expires 19 April 2020 [Page 3]
Internet-Draft Bearer Capabilities October 2019
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.
4.2. 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.
4.3. 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.
4.4. 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].
5. IANA Considerations
5.1. Bearcap URI Scheme Registration
This specification registers the following URI Scheme in the URI
Schemes Registry [RFC7595].
5.1.1. "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
Conill Expires 19 April 2020 [Page 4]
Internet-Draft Bearer Capabilities October 2019
Change controller: TODO
6. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750,
DOI 10.17487/RFC6750, October 2012,
<https://www.rfc-editor.org/info/rfc6750>.
[RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines
and Registration Procedures for URI Schemes", BCP 35,
RFC 7595, DOI 10.17487/RFC7595, June 2015,
<https://www.rfc-editor.org/info/rfc7595>.
[W3C.WD-capability-urls-20140218]
Tennison, J., "Good Practices for Capability URLs", World
Wide Web Consortium WD WD-capability-urls-20140218, 18
February 2014,
<http://www.w3.org/TR/2014/WD-capability-urls-20140218>.
Author's Address
Ariadne Conill
Pleroma
Email: ariadne@dereferenced.org
Conill Expires 19 April 2020 [Page 5]