Linked Data Capabilities (ld-ocap for short) provide a secure way for linked data systems to grant and express authority utilizing the object capability model. Capabilities are expressed through "proclamation chains" which are themselves linked data documents signed through Linked Data Signatures. Linked Data Capabilities support delegating authority to other entities on the network. "Caveats" may be attached to proclamations which may be used to restrict the scope of their use, for example to restrict the methods which may be used or providing a mechanism by which the capability may be later revoked.

This specification is currently being drafted to be considered as a work item for the Community Credentials Group.

Introduction

This document is being based off of a paper from Rebooting Web of Trust. In the early stages of this document some ideas may be better described in that paper than yet in this specification.

This document does not cover a specific method for delivering Linked Data Capabilities to an object, though something like the inbox property and associated delivery mechanisms from Linked Data Notifications and ActivityPub is one possible system. However there is nothing about Linked Data Capabilities that is specific to HTTP; for example, both proclamations and invocations could be stored on a blockchain or a distributed hash table.

Linked Data Capabilities by Example

Much of modern computing security infrastructure relies on "who is doing something" using access control lists. For example, our friend Alyssa P. Hacker has a car, and she would like to drive it In the access control list world, the car itself may scan Alyssa's face, determine that Alyssa is the driver, and say "Welcome Alyssa, you are now free to drive." Talking cars are appealing and fun, but Alyssa may run into challenges when she would like to allow others to drive her car.

Fortunately, there is another paradigm that is even more familiar to the car scenario, but less familiar in the context of computing, despite providing some superior properties and a greater degree of safety: object capabilities. Object capabilities focus not on "who" is peforming an action, but upon "what" source of authority permits an action to occur. As it turns out, Alyssa does not have a talking and face-scanning car, she has a car that accepts a car key. The car may have no memory of Alyssa whatsoever, but as long as Alyssa holds the kind of key that enables her to drive the car, she can drive the car. Capabilities are very similar to this car metaphor, and we can encode this same idea in Linked Data Capabilities as a "proclamation":

    {"@context": ["https://example.org/ocap/v1",
                  "https://autopower.example/"],
     "id": "https://whatacar.example/a-fancy-car/proc/7a397d7b",
     "type": "Proclamation",
     
     // The subject is who the capability operates on (in this case,
     // Alyssa's Car)
     "subject": "https://whatacar.example/a-fancy-car",

     // We are granting authority specifically to one of Alyssa's signing
     // keys (a cryptographic key, not to be confused with the car
     // key metaphor!)
     "grantedKey": "https://social.example/alyssa/#key-for-car",

     // Finally we sign this object with one of the Alyssa's Car's
     // signing keys
     "signature": {
        "type": "RsaSignature2016",
        "created": "2016-02-08T16:02:20Z",
        "creator": "https://whatacar.example/a-fancy-car#key-1",
        "signatureValue": "IOmA4R7TfhkYTYW8...CBMq2/gi25s="}}
        

This proclamation signs that one of Alyssa's keys (rather than Alyssa specifically) is able to drive the car. Turning on this car and driving into the sunset is as easy as invoking the capability to do so:

    {"@context": ["https://example.org/ocap/v1",
                  "https://autopower.example/"],
     "id": "urn:uuid:ad86cb2c-e9db-434a-beae-71b82120a8a4",
     "type": "Invocation",
     "proclamation": "https://whatacar.example/a-fancy-car/proc/7a397d7b",
     "method": "Drive",
     "signature": {
        "type": "RsaSignature2016",
        "created": "2016-02-08T17:13:48Z",
        "creator": "https://social.example/alyssa/#key-for-car",
        "signatureValue": "..."}}
        

Alyssa lives with her roommate and long-time friend Ben Bitdiddle. While they're living together, she'd like that he be able to drive her car too. Capabilities support delegation, so she could delegate a new capability to Ben giving him full authority, not unlike going to the hardware store and having them copy the car key. But Alyssa knows that she and Ben will probably not be roommates forever, and she feels no need for him to be able to drive her car once they are not, so she would like to have the option to revoke his authority. In the world of object capabilities, this is entirely possible by adding a "caveat" that permits future revocation. We can imagine this to be like a new car key that has a remote destruction mechanism: Alyssa can press a button that she has, a wire burns out inside the car key, and the car key will not be usable anymore. Alyssa generates a new proclamation that points at the proclamation she has, adding the caveat:

    {"@context": ["https://example.org/ocap/v1",
                  "https://autopower.example/"],
     "id": "https://social.example/alyssa/prcmtns#79795d78",
     "type": "Proclamation",

     // Pointing up the chain at the proclamation from which Alyssa
     // initially gained authority
     "parentProclamation": "https://whatacar.example/a-fancy-car/proc/7a397d7b",

     // Alyssa grants authority specifically to one of Ben's signing keys
     "grantedKey": "https://chatty.example/ben/#key-33",

     // Alyssa adds a caveat: Ben can drive her car, unless she flips
     // the bit at this url
     "caveat": [
       {"type": "ValidWhileTrue",
        "uri": "https://social.example/alyssa/ben-can-still-drive"}],

     // Finally Alyssa signs this object with the key she was granted
     // authority with
     "signature": {
        "type": "RsaSignature2016",
        "created": "2017-03-28T06:01:25Z",
        "creator": "https://social.example/alyssa/#key-for-car",
        "signatureValue": "..."}}
        

Alyssa hands the car key to Ben, and Ben marks the car key in such a way that reminds him that it's specifically to drive Alyssa's car. Several months pass and Ben receives a message from Alyssa asking if he might enjoy joining her at an award ceremony her university is holding. Alyssa is already at the university and is getting a ride to the venue, so she suggests Ben drive her car and meet her there. Ben invokes his capability, the car performs all relevant checks on the capability (including that the signature is valid and applicable, and that the caveat is still valid), and off Ben drives.

Ben arrives at the fancy award venue, where there is valet parking. The Valet approaches wearing the nametag "Lem E. Driveit" and asks for a key to park the car. Ben remembers he has heard some stories about valets going on joyrides and isn't sure if they're true, but decides there's no need to take the risk: he can use his capability to forge a new, further restricted capability which he can delegate to Lem. This new car key has the caveat that it can be used to drive up to 5 kilometers, but no more:

    {"@context": ["https://example.org/ocap/v1",
                  "https://autopower.example/"],
     "id": "https://chatty.example/ben/procs#2cdea8c1",
     "type": "Proclamation",
     "parentProclamation": "https://social.example/alyssa/prcmtns#79795d78",
     "grantedKey": "https://lem.example/#key-bf36",

     // Ben adds this caveat: this capability can be used to drive the
     // car, but not for more than 5 kilometers
     "caveat": [
       {"type": "DriveNoMoreThan",
        // Alyssa's guage currently says 123854 kilometers driven,
        // so this is only 5 km more than the current value
        "kilometers": 123859}],

     // Finally Ben signs this object with the key he was granted
     // authority with
     "signature": {
        "type": "RsaSignature2016",
        "created": "2017-06-13T19:15:03Z",
        "creator": "https://chatty.example/ben/#key-33",
        "signatureValue": "..."}}
        

(It probably doesn't matter to this scenario, but since it is derived from the car key that Ben holds, it also has the same caveat that it will also be remote destructed by Alyssa along with Ben's car key should she press the relevant button.)

Capabilities Are Safer

We can see from the above example that by using an object capability system such as Linked Data Capabilities can give us some additional power around delegating and restricting the scope of capabilities. But object capabilities provide improved safety characteristics over Access Control Lists which may make them frequently better choices (for more details, see the paper ACLs Don't). Object capability systems are in general more robust against:

Object capabilities are less vulnerable to these kinds of attacks because capabilities are an encoding of "the principle of least authority" in software development practice. Linked Data Capabilities helps bring the power of capabilities to the web, providing specific and directed grants of authority.

Terminology

capability
Authority which may be invoked to perform some operation upon a (linked data) object. Represented as a proclamation chain within the context of Linked Data Capabilities.
caveat
Also known as "attenuation" within object capability literature, a "caveat" may be attached to a proclamation as a restriction on how that capability may be used. Delegated capabilities will preserve caveats and may be themselves may be further restricted by adding more caveats.
invocation
The "activation" of a capability, represented as a linked data document which is signed in such a way that matches authority granted through a prior proclamation. An invocation may have arguments, similar to how a procedure call may have arguments.
object
Though the term object has many definitions in computer science, within the context of Linked Data Capabilities a "linked data object" is an entity which is associated with a URI and which is capable of having proclamation chain based capabilities being invoked against it.
method
An argument of an invocation which directs what particular functionality of the object is being used. For example, an invocation against a file storage service may specify either a write method or a read method.
proclamation / proclamation chain
A proclamation is a linked data document which represents a capability to an object. Proclamations may be delegated by issuing new proclamations which point at previous proclamations, possibly with further caveats attached.
subject
TODO

Proclamations

Linked Data Capabilities are encoded through "proclamation chains". Proclamations are linked data documents which express a grant of authority from some entity (or more commonly, an entitiy's specific key) to a specific subject, possibly restricted through "caveats". (This includes the possibility of revocation through a caveat that expresses such a mechanism.)

Every proclamation MUST have:

"Top-level" proclamations, which do not have a parentProclamation property, MUST have:

Why don't all child proclamations require a grantedKey property? The reason is that it is perfectly reasonable for an entity which has authority to a capability to give an attenuated capability to itself to be used in a specific context.

Capabilities are not structured around "who has access" to something but rather holding onto a capability for a particular use, and in order to avoid confused deputy and ambient authority problems, in general objects should not hold on to a "bucket" of capabilities which grant them authority, but hold on to them within specific contexts for specific purposes. In general, when an object is granted a capability, it is important that it know for what specific purpose it has been granted that capability so that it does not become confused and use it in the wrong scenario. This is not unlike how in computer programs a procedure called with specific arguments understands for what the meaning of those arguments are and for what they may be used.

Delegation through Proclamation Chains

A proclamation MAY also have a parentProclamation property. A series of proclamations chained together in this way is called a "proclamation chain" and is how delegation of capabilities are handled in Linked Data Capabilities. New keys MAY be granted authority to use this proclamation through the associated grantedKey property. Proclamations with parents MUST NOT have a new subject property, and MUST be signed by either the original subject or one of the later grantedKey keys.

Caveats

Every proclamation MAY add restrictions on the way the capability may be used by adding to the caveat property. Proclamations inherit the restrictions from all caveat properties of their parents, and MAY add new caveats in addition to those of their parents.

The meaning of caveats are determined by their type and whatever other properties they have. Due to the way they are interpreted at invocation type by the subject, some mutual understanding of terminology must be understood between the entity adding a caveat and the subject evaluating (or any other parties observing) the invocation.

Invocation

A capability may be enacted through the process of invocation. In the context of Linked Data Capabilities, an invocation consists of a linked data object which MUST have:

An invocation SHOULD have an id (which may also serve as a nonce). Any other properties are considered arguments to the invocation.

In order for an invocation to be considered valid:

At this point, the invocation is considered valid and any relevant action may be performed. (This does not guarantee that a specific result will occur, merely that the invocation itself is valid; a subject could in evaluating the invocation encounter invalid input and return or raise an error, for instance.)

Since invocations are themselves linked data documents, it is possible for an invocation to refer to an invocation as an argument. For this reason it is critical that mechanisms for accepting invocations be sure which invocation is being performed. For example, a mechanism that accepts linked data capabilities as JSON-LD documents will likely have no trouble telling which invocation is being performed since that will be the "top" of the framed document. However, a mechanism which accepted N-Quads would need additional information supplied perhaps in the headers in order to be able to determine the "root" of the invocation.

Methods

Methods are a common way to direct behavior of an invocation. Subjects are free to choose their own mechanisms for directing behavior, but MAY support the method property on invocations as one common bahavioral direction technique. The method property points to a URI as a form of vocabulary to determine which method is being performed. For example, a capability to a file storage system may allow for both reading and writing files, and a user could choose to set the method to https://datastore.example/WriteFile as an argument on their invocation.