Capability URIs and IRIs

1.1. Rationale

The research on access control has shown that between the two major paradigms of access control, access control lists (ACLs) are less expressive and usually open the possibility of confused deputy attacks, which include some the most problematic attack surfaces of the Web, like XSS and CSRF (see ACLs Don't). The ambient authority inherent to ACLs is also often critical in enabling privilege escalation, making one security flaw vastly more damaging.¶

The other paradigm, capability-based security, combines designation and authority, making it possible to prevent confused deputy attacks and create new patterns of access control, including composable security policies and safe delegation mechanisms. (see Capability Myths Demolished)¶

HTTP URIs could be used as capabilities, but as HTTP URIs are not treated as sensitive data by most systems, except for their authorization part (but the classical format login:password has been deprecated since, see [RFC3986], section 3.2.1), it opens up the possibility that capabilities would get leaked in various problematic places, including being stored in server logs and shown in browser address bars.¶

This specification describes URI schemes that make it possible to safely encode capabilities as URIs and IRIs (see [RFC3987]) by combining an existing URI or IRI and some authorization data into a URI or IRI, called capability-URI (for readability, we don't distinguish capability-URIs and capability-IRIs, as they don't have different security properties).¶

1.2. Architectural benefits

These URIs and IRIs also deliver on the promises of several architectural decisions at the core of the World Wide Web. [webarch] notes that¶

It is a strength of Web Architecture that links can be made and shared; a user who has found an interesting part of the Web can share this experience just by republishing a URI.¶

When authority is separated from designation, sharing a link is often not enough. And several platforms only let their users share content among themselves. When the only tool of access control is user identity, it is logical that you can only share with another user. But fined grained capabilities make it possible again to share "an interesting part of the Web".¶

Capability-URIs are also a better fit than identity-based authorization in REST APIs (see Architectural Styles and the Design of Network-based Software Architectures, especially chapter 5). The hypermedia nature of REST means that a payload may contain state transitions going to a variety of different servers and in the context of identity-based authorization, it is unclear what credentials should be used where and it creates the risk of using some credentials with the wrong server, possibly leaking credentials to an untrusted system.¶

But if a REST server uses capability-URIs in the state transitions, the client knows with certainy which credentials to use for each request, and each capability-URI can hold the bare minimum of authority needed to trigger just that transition (see Attenuation (Section 4.6)).¶

Capability-URIS also give the server more control over the trade-off between safety and latency: when the client should be able to trigger a state transition often and/or over some period of time, the server can embed a long-lived authorization in that state transition with only the authority for that transition. It makes the capability easier to reuse by a malicious agent, but with a very limited attack surface. On the other hand, whenever some state transitions require that the client be very strictly verified to be the right one, capabilities could have a very short TTL and the client would need to renew them by requesting again the resource where they appeared.¶

1.3. Conventions and Terminology

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 [BCP14].¶

1.4. Syntax Notation

This specification uses the Augmented Backus-Naur Form (ABNF) notation of [RFC5234].¶

1.5. Prior work

The first use of URIs as capabilities was in the Waterken project, with web-keys, which placed an unguessable token in the fragment of an https URI, and YURLs, with the httpy URI scheme, which introduced the Y-property (Section 4.8).¶

Introducing a new URI scheme proved to be difficult with Web browsers at the time, so the Waterken project ended up using https URIs with the fingerprint for the Y-property embedded in the host.¶

Recently, several proposals were made about embedding capabilities as URIs with a new URI scheme (see acknoledgements (Section 6)).¶

While this specification describes new URI schemes, the principle of web-keys remain a useful alternative in use cases where using the new schemes is not possible, and it can interoperate with capability-URIs. Appendix C explains the basic mechanism of web-keys and Section 3 their evolution with capability-URIs.¶

2.1. Principle of operation

When a capability-URI-aware HTTP agent (like a browser or library) is asked to make an HTTP request to a resource identified by a capability-URI (with parameters like the method or the request body), it extracts from that capability-URI the authorization data and the request target, prepares the HTTP request with the user-given parameters but augments the connection establishment and the request headers based on the authorization data of the capability-URI.¶

In the following example, it puts the bearer token in the Authorization header with the Bearer authorization scheme [RFC6750]:¶

http.post("cap-https://bt=AViRTF9ppWiAtdnpVtVHDQ@example.com/foo", body="bar",
  headers={"Content-Type": "text/plain"})

would produce the following HTTP/1.1 [RFC9112] request:¶

POST /foo HTTP/1.1
Host: example.com
Content-Type: text/plain
Authorization: Bearer AViRTF9ppWiAtdnpVtVHDQ

bar

or the following HTTP/2 [RFC9113] or HTTP/3 [RFC9114] request:¶

HEADERS
  + END_HEADERS
    :method = POST
    :scheme = cap-https
    :authority = example.com
    :path = /foo
    content-type = text/plain
    authorization = Bearer AViRTF9ppWiAtdnpVtVHDQ

DATA
  + END_STREAM
bar

Each URI scheme corresponds to an existing HTTP URI scheme, extended with rich authorization data. In a target capability-URI, except for the userinfo component which maps to the capability-URI's authorization component, every component has the same syntax and semantics than the corresponding URI scheme (and maps to the same request components, headers and pseudo-headers).¶

As far as the capability-URI-aware agent is concerned, the URI of the designated resource MUST NOT be the embedded HTTP URI, but the capability-URI (the retrieval URI is one source for a base URI).¶

2.2. Relative URI references

The normal algorithm from [RFC3986] (section 5.2) applies to relative references, which means that except for network-path references with a userinfo component, relative references reuse the same authorization data used to retrieve the resource representation where they appear.¶

For that reason, the capability schemes include a dedicated syntax to use a relative path with a different token: cap-https:bt=NVW9YpUuEkZ367AyA-3MZw@./bar. Note that when such a relative capability-URI is parsed by a generic URI parser, the whole content after the scheme will match the path-rootless rule of [RFC3986] (and the token won't be parsed by the authority rule).¶

To make a relative reference with an absolute path, a network-path reference can be used: //D-nX3h-tDq_VtaYQKYYlDw@/baz. If there could be ambiguity whether the base URI is a capability-URI, it is valid for capability-URIs to have an empty host, which creates a URI that is equivalent to a network-path reference, but with the scheme specified: cap-https://bt=D-nX3h-tDq_VtaYQKYYlDw@/baz.¶

These relative capability-URI, like relative URI references, refer to a target capability-URI.¶

2.3. Definitions

The four URI schemes are specified by the rules¶

• cap-http-uri¶

• cap-https-uri¶

• cap-ws-uri¶

• cap-wss-uri¶

The corresponding IRIs are specified by the rules¶

• cap-http-iri¶

• cap-https-iri¶

• cap-ws-iri¶

• cap-wss-iri¶

cap-http-uri        = "cap-http" ":" cap-path [ "?" query ] [ "#" fragment ]
cap-https-uri       = "cap-https" ":" cap-path [ "?" query ] [ "#" fragment ]
cap-ws-uri          = "cap-ws" ":" cap-path [ "?" query ]
cap-wss-uri         = "cap-wss" ":" cap-path [ "?" query ]
cap-path            = absolute-cap-path / relative-cap-path
absolute-cap-path   = "//" authorization "@" host [ ":" port ] path-abempty
relative-cap-path   = authorization "@" path-rel
path-rel            = segment-rel "/" path-rootless
authorization       = [ param *( ";" param ) ]
param               = 1*param-char
param-char          = unreserved / pct-encoded / param-delims
param-delims        = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / "=" / ":"
bearer-token-param  = "bt=" token
token               = 1*param-char
token-format-param  = [ "*" ] "tf=" token-format
token-format        = 1*param-char
y-cert-param        = "yc=" y-cert-alg ":" y-cert-hash
y-cert-alg          = 1*unreserved
y-cert-hash         = base32
segment-rel         = "." / ".."
base32              =  "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" / "I" / "J" / "K"
base32              =/ "L" / "M" / "N" / "O" / "P" / "Q" / "R" / "S" / "T" / "U" / "V"
base32              =/ "W" / "X" / "Y" / "Z" / "2" / "3" / "4" / "5" / "6" / "7"

cap-http-iri        = "cap-http" ":" cap-ipath [ "?" iquery ] [ "#" ifragment ]
cap-https-iri       = "cap-https" ":" cap-ipath [ "?" iquery ] [ "#" ifragment ]
cap-ws-iri          = "cap-ws" ":" cap-ipath [ "?" iquery ]
cap-wss-iri         = "cap-wss" ":" cap-ipath [ "?" iquery ]
cap-ipath           = absolute-cap-ipath / relative-cap-ipath
absolute-cap-ipath  = "//" iauthorization "@" ihost [ ":" port ] ipath-abempty
relative-cap-ipath  = iauthorization "@" ipath-rel
ipath-rel           = isegment-rel "/" ipath-rootless
iauthorization      = [ iparam *( ";" iparam ) ]
iparam              = 1*param-ichar
param-ichar         = iunreserved / pct-encoded / param-delims
bearer-token-iparam = "bt=" itoken
itoken              = 1*param-ichar

Note that the rule param-delims corresponds to the rule sub-delims (see [RFC3986], section 2.2), minus the ";" alternative, plus the ":" alternative.¶

The definitions of the following rules are adopted from the generic syntax of URIs and IRIs:¶

host           = <host, see [RFC3986], Section 3.2.2>
port           = <port, see [RFC3986], Section 3.2.3>
path-abempty   = <path-abempty, see [RFC3986], Section 3.3>
path-rootless  = <path-rootless, see [RFC3986], Section 3.3>
unreserved     = <unreserved, see [RFC3986], Section 2.3>
pct-encoded    = <pct-encoded, see [RFC3986], Section 2.1>
query          = <query, see [RFC3986], Section 3.4>
fragment       = <fragment, see [RFC3986], Section 3.5>

ihost          = <ihost, see [RFC3987], Section 2.2>
iport          = <iport, see [RFC3987], Section 2.2>
ipath-abempty  = <ipath-abempty, see [RFC3987], Section 2.2>
ipath-rootless = <ipath-rootless, see [RFC3987], Section 2.2>
iunreserved    = <iunreserved, see [RFC3987], Section 2.2>
iquery         = <iquery, see [RFC3987], Section 2.2>
ifragment      = <ifragment, see [RFC3987], Section 2.2>

If the capability-URI has an absolute-cap-path where the host component is empty or an absolute-cap-ipath where the ihost component is empty, the URI is relative and is valid only if there is a known base URI (see [RFC3986], section 5.1). Resolving this relative capability-URI consists in creating a target capability-URI where every component is taken from the relative capability-URI, except the host, taken from the base URI.¶

If the capability-URI has a relative-cap-path or relative-cap-ipath, resolving it consists in creating a target capability-URI where every component is taken from the URI produced by resolving the relative reference present in the path-rel or path-irel component, except the authorization or iauthorization component, taken from the authorization or iauthorization component of the relative capability-URI.¶

2.4. Parameters

The authorization or iauthorization component of the capability-URI is made of a sequence of parameters. This specification defines three such parameters, but a future version can define more parameters, to support different authorization mechanisms, or deprecate exisiting ones.¶

An application that doesn't implement some parameter MUST NOT make a request for a capability-URI containing that parameter, except if that parameter's handling is optional. If a parameter's handling is optional, it MUST begin with the character *. If a parameter's handling is not optional, it MUST NOT begin with the character *.¶

4.7. Responsibility tracking

As much as capabilities make it easier and safer to design systems that better prevent unwanted accesses and are more robust in the face of negligent or malicious behavior, they also make it possible to track complex chains of responsibility in cases where unwanted accesses happen.¶

The difference with ACL security is important. In an ACL system, permissions are usually granted broadly and often in advance. For example, all members of a lab might get added to a group that has write access to the files of all active projects of the lab, or maybe to groups linked to projects they participate in if security is tighter. If Mallet want some file overwritten without logs pointing to them, they set things up so that Bob will instruct Alice to write data in the targeted file. When it is later discovered that it wasn't the right file for what she wrote and she overwrote and lost valuable information, in the system itself, we may have only limited evidence:¶

• when user X put Alice in the relevant group¶

• when user Y gave that group write permissions on the file¶

• when Alice modified the file¶

Users X and Y probably did their changes long before the unwanted access happened and none of them is Bob or Mallet. Depending on the system, on top of Alice being indirectly duped to write to some path, another person might have been indirectly duped so that this unassumng file path is actually a link to something else. The paths could have been communicated with all kinds of services, or even given by speech or written by hand, so they may not be anywhere in the security logs. Ultimately, Mallet might not have himself the authority in the system to write the file, nor Bob. In this scenario, even if permissions are given narrowly, they would not show any evidence against Mallet.¶

In a capability system, people cannot be duped to enter a path as the target of a link or write operation when those require a capability, not a path. This means that Mallet needs to have access to the targeted file himself. When Alice writes the file, the system can be designed to log that it's with a capability given by Bob, itself using a capability given by Mallet.¶

4.10. Protection against CSRF

The use of capability-URIS according to POLA (Section 4.4) is resistant to CSRF attacks because an attacker cannot forge a request that the targeted user is authorized to make but the attacker isn't. By definition, when you combine authority with designation, noone can request what they are not authorized to do.¶

Of course, like any security framework, the design of an application can go against its principles and be unsafe despite the framework. If a service A holds a capabiliy-URI to service B with a broad authority, where part of the embedded URI is a guessable resource name, and service A uses resource names from its client requests, then service A has succesfully circumvented POLA and made itself vulnerable to confused deputy attacks, despite the use of capabilities.¶

An example of such a bad design would be (using URI templates, see [RFC6570]):¶

• Service B is accessed by Service A through cap-https://K_qCxe8msbJGU4kkIIbSpA@quux.org/serviceB{?resource}¶

• Service A is accessed by its clients through https://quux.org/serviceA{?resource}¶

4.11. Protection against XSS

Most previous uses of bearer tokens that protect against CSRF are vulnerable to XSS because some tokens with broad authority are stored in a global mutable store where XSS-injected malicious code can trivially read them (like the localStorage of a Web browser).¶

But with the combined use of REST and capability-URIs, client-side code can use capability-URIs in such a way that they are never stored except in the local variables of the functions using them, where XSS-injected malicious code cannot read them without the support of attacks like Meltdown or Spectre.¶

When using capability-URIs in a browser's address bar, either with a browser capable of using capability-URI directly, or with web-caps, a Web application SHOULD redact the address bar as soon as possible, as XSS-injected malicious code can trivially read it.¶