Authorization Capabilities for Linked Data v0.3

Authorization Capabilities for Linked Data (ZCAP-LD for short) provides a secure way for linked data systems to grant and express authority utilizing the object capability model. Capabilities are represented as linked data objects which are signed with Linked Data Proofs. ZCAP-LD supports delegating authority to other entities on the network by chaining together capability documents. "Caveats" may be attached to capability documents which may be used to restrict the scope of their use, for example to restrict the actions which may be used or providing a mechanism by which the capability may be later revoked.

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 ZCAP-LD invocations 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 ZCAP-LD that is specific to HTTP; for example, both capabilities and invocations could be stored on a blockchain or a distributed hash table.

Capabilities vs. Access Control Lists

One of the first questions that is usually asked about using Object Capabilities for authorization is: "How are Capabilities different from Access Control Lists?". Fundamentally, Access Control Lists are about authority by identity whereas Object Capabilities are about authority by possession.

Authority by identity is the process of giving access to a resource to a specific entity based on their identity. These processes typically ask the question: "Who are you?"

Authority by possession is the process of giving access to a resource to any entity that possesses something, like a key. These processes typically ask the question: "Do you have a key that fits this lock?"

This document doesn't explain why Access Control Lists lead to a variety of security issues or why Object Capabilities provide stronger security guarantees. For those that would like to learn more about these topics, Capability Myths Demolished and ACLs Don't provide a deeper exploration into the benefits of Object Capabilities.

ZCAP-LD 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 performing 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 ZCAP-LD. The following document delegates authority from the car (who always has authority over itself) to Alyssa so that she may drive:

{
  "@context": ["https://w3id.org/security/v2",
               "https://autopower.example/"],

  "id": "https://whatacar.example/a-fancy-car/proc/7a397d7b",

  // Since this is the first delegated capability, the parentCapability
  // points to the target this capability will operate against
  // (in this case, Alyssa's Car)
  "parentCapability": "https://whatacar.example/a-fancy-car",

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

  // Finally we sign this object with cryptographic material from
  // Alyssa's Car's capabilityDelegation field, and using the
  // capabilityDelegation proofPurpose.
  "proof": {
    "type": "Ed25519Signature2018",
    "created": "2018-02-13T21:26:08Z",
    "capabilityChain": [
      "https://whatacar.example/a-fancy-car"
    ],
    "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..lfAFjrWE-4RxhL0gtzSMRX72NR9SRDgaMmkjPA4if0ERbw4R2bnts5sAs8OyhAlbFzBAKOqrFk57AYqwSR2vCw",
    "proofPurpose": "capabilityDelegation",
    "verificationMethod": "https://example.com/i/alice/keys/1"
  }
}

Turning on this car and driving into the sunset is as easy as invoking the capability to do so:

    {"@context": ["https://example.org/zcap/v1",
                  "https://autopower.example/"],
     "id": "urn:uuid:ad86cb2c-e9db-434a-beae-71b82120a8a4",
     "action": "Drive",
     "proof": {
        "type": "RsaSignature2016",
        // A linked data document can be an invocation if it has a
        // proofPurpose of capabilityInvocation and links to the capability
        // chain it is invoking
        "proofPurpose": "capabilityInvocation",
        "capability": "https://whatacar.example/a-fancy-car/proc/7a397d7b",
        "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 capability document that points at the capability she has, adding the caveat:

    {"@context": ["https://example.org/zcap/v1",
                  "https://autopower.example/"],
     "id": "https://social.example/alyssa/caps#79795d78",

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

     // Alyssa grants authority specifically to one of Ben's
     // cryptographic keys
     "invoker": "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
     "proof": {
        "type": "RsaSignature2016",
        "proofPurpose": "capabilityDelegation",
        "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 proof/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 create 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/zcap/v1",
                  "https://autopower.example/"],
     "id": "https://chatty.example/ben/caps#2cdea8c1",
     "parentCapability": "https://social.example/alyssa/caps#79795d78",
     "invoker": "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 gauge 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
     "proof": {
        "type": "RsaSignature2016",
        "proofPurpose": "capabilityDelegation",
        "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 using an object capability system such as ZCAP-LD 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:

Ambient authority problems: For example, in an access control list environment, if an attacker gets you to open a message in your email client which contains an image which triggers an arbitrary code execution vulnerability in the image library it is using, an attacker can use this to do everything that you can: they can read or destroy your documents, they can run programs as you, and they can in general do anything that you can... all from a pin-prick sized vulnerability. Properly using an object capability environment, the worst an attacker could do is mess with your email (or if the program is itself capability aware, they may not be able to do even that... they could just display some nasty imagery on your screen, which they could do already anyway).
Confused deputy attacks: For example, browsers and both backend and frontend software for the web have frequently struggled with Cross-Site Request Forgery attack issues. Your browser may both allow websites to access resources on other websites and also allow you to log into various websites, say a social networking site or a bank. A malicious website could use this to its advantage to trick your browser into performing actions as you on those other sites... say to read from or spam to your social timeline, or to withdraw money from your bank account. While various techniques to can be used to restrict the scope of these attacks, they are notoriously hard to prevent.

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. ZCAP-LD helps bring the power of capabilities to the web, providing specific and directed grants of authority.

Root Capability

A root zcap looks like this:

{
  "@context": [
    "https://w3id.org/zcap/v1"
  ],
  "id": "urn:zcap:root:https%3A%2F%2Fexample.com%2Ffoo",
  "controller": "did:key:example",
  "invocationTarget": "https://example.com/foo"
}

A root zcap MUST have an `@context` field that is a string with the value `https://w3id.org/zcap/v1`. This field makes zcaps JSON-LD compatible, but does not mean that any other JSON-LDisms are permitted. In other words, zcaps are JSON-based, and the JSON has been chosen carefully such that it can be interpreted properly as JSON-LD as well. Other JSON-LD representations that deviate from the JSON expression of a zcap are not permitted.

By enabling JSON-LD compatibility, DI proofs (Data Integrity Proofs, formerly known as Linked Data proofs) are used instead of JOSE-based signatures. This helps keep zcap sizes small by eliminating the need to encapsulate zcaps via base64 encoding. This is particularly important for expressing capability chains [TODO: link to capability chains], where ancestor zcaps would be base64-encoded N+1 times where N is the length or position in the chain. If neither of these approaches were used, a novel signature encapsulation mechanism would have to be invented to get the same benefits; instead, reuse of existing work is preferred.

Additionally, JSON-LD compatibility enables CBOR-LD to be used to express zcaps — further reducing size via semantic compression. [Note: [See invoking a root zcap section]. When invoking a root zcap, a capability invocation proof is added, not to the root zcap itself, but rather to another document that is acceptable to an API. This means that no additional contexts (especially cryptosuite contexts) ever need to be added to a root zcap. Further work on the Data Integrity 1.0 spec could alleviate the need for additional cryptosuite contexts entirely.]

A root zcap MUST have an `id` that is a string that expresses a URN. This ID can always be dereferenced by the verifier system if it is a valid root zcap for a particular endpoint. The ID of a root zcap SHOULD [Note: this should become a MUST if it covers all use cases, to keep things simple] have the following format:

urn:zcap:root:${encodeURIComponent(invocationTarget)}

This format makes it clear that the identifier is for the root zcap for the root invocation target, `invocationTarget`.

A root zcap MUST have an `invocationTarget` that is a string that expresses a URI. The invocation target identifies where the zcap may be invoked, and identifies the target object for which the root zcap expresses authority.

A root zcap MUST have a `controller` that is a string or an array of strings that each express a URI that identifies a controller for the root zcap. The controller (or controllers) may take any actions with the invocation target (that are supported by the verifier) by invoking the root zcap. The controller (or controllers) may create delegated zcaps from the root zcap [TODO: link to delegated zcap section].

Note: A root zcap MUST NOT have any other fields.

A root zcap can be invoked by referencing only its ID because the verifier can (and MUST) always dereference the zcap locally using a trusted dereferencing mechanism. This is because a root zcap does not have a capability delegation proof; it is the root of trust for a capability chain [TODO: link to capability chains].

Invoking a Root ZCAP

There can be multiple ways to invoke a root zcap; these include 1) by using an HTTP signature in an HTTP request, and 2) by attaching an LD capability invocation proof to a document. The verifier will decide which of these methods is acceptable and what other information must be signed (in the case of an HTTP signature) or what documents may be submitted with attached capability invocation proof(s).

When invoking a root zcap using an HTTP signature, a capability-invocation header must be included that identifies the root zcap by ID (via an `id` parameter) and the capability action that is being invoked (via an `action` parameter). The request URL identifies the intended invocation target, which must either match the invocation target in the root zcap, or, if the verifier allows it, have the root zcap's invocation target as a prefix. The capability action must be an action that is expected (supported) by the verifier at the request URL. The capability action SHOULD be read or write. The key used to create the HTTP signature must be either 1) the private key paired with a verification method that matches the controller of the root zcap or 2) a verification method that is controlled by the controller of the root zcap — and authorized for the purpose of `capabilityInvocation`.

When invoking using a DI proof, a capability invocation proof must be attached to a document that is acceptable by the API, as defined by the specific API being accessed. The capability invocation proof MUST include the intended `invocationTarget`, the root zcap ID in the `capability` property, and the action to be taken in the `capabilityAction` property. The same controller rules apply as in the HTTP signature case.

Dereferencing a Root Capability on a Verifier System

It is expected that only verification systems will dereference root zcaps from their IDs. One model for new HTTP APIs is to store a controller value with every resource at the base of a hierarchy, for instance, store controller `X` for the collection `https://foo.example/collections/123`. When the root zcap for this collection is invoked or referenced via a delegated zcap invocation, the verifier can look up the `controller` property (or receive it from another system in some kind of decentralized setup) for that resource and include it in a "dynamically dereferenced" root zcap. In other words, the verifier sees the root zcap ID `urn:zcap:root:`, and dynamically converts that (after looking up its controller) into:

            {
  "@context": [
    "https://w3id.org/zcap/v1"
  ],
  "id": "urn:zcap:root:https%3A%2F%2Ffoo.example%2Fcollections%2F123",
  // populated via a database or external system call
  "controller": "did:key:example",
  "invocationTarget": "https://foo.example/collections/123"
}

Delegated Capability

A delegated zcap looks like this:

{
  "@context": [
    "https://w3id.org/zcap/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "id": "urn:uuid:cdc77118-6bfa-11ec-aceb-10bf48838a41",
  "parentCapability": "urn:zcap:root:https%3A%2F%2Fexample.com%2Ffoo",
  "controller": "did:key:example",
  "invocationTarget": "https://example.com/foo",
  "expires": "2021-11-03T18:33:51Z",
  "allowedAction": [
    "write",
    "read"
  ],
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2021-10-27T18:33:51Z",
    "verificationMethod": "did:key:z6MkfWKcvBiKCfNgz5UUGseNt37t4dguEvFgJ9XvX2UV6zB9#z6MkfWKcvBiKCfNgz5UUGseNt37t4dguEvFgJ9XvX2UV6zB9",
    "proofPurpose": "capabilityDelegation",
    "capabilityChain": [
      "urn:zcap:root:https%3A%2F%2Fexample.com%2Ffoo"
    ],
    "proofValue": "z3t9BCQyF21MDVYmLKc9zbLreqx4wBtQnUsd5aqyoWS5FfhapRz7QjPNLcgKAornUVmJR4ZjbGpuxRFnffxX1ZjtF"
  }
}

A delegated zcap is different from a root zcap primarily in that it has a `parentCapability`, an expiration date-time, and a capability delegation proof (found in proof). It is also different from a root zcap in that all delegated zcaps in a chain [link to capability chains] must be fully provided to the verifier when invoking a delegated zcap, so that the verifier is not required to dereference them other than via the provided chain. Note: A verifier may still need to query a database for delegated zcaps to perform revocation checks by ID. However, a verifier MUST NOT be required to perform network requests or database queries to dereference delegated zcaps by ID when verifying the capability chain [link to capability chains], prior to inspecting it for potential revocations.

A delegated zcap MUST have an `@context` field with an array where the first value is the zcapld context and any subsequent values identify context(s) used to define vocabulary terms used in the capability delegation proof. [Note: Maximum array size should be defined in the spec along with rationale].

A delegated zcap MUST have an `id` that is a string that expresses a URI. The id SHOULD have the format:

urn:uuid:

Using this format enables CBOR-LD to perform compression on the ID value, and reduces correlation risk by making the ID semantically opaque.

A delegated zcap MUST have a `parentCapability` that is a string that expresses the ID of the parent zcap. The parent zcap may be another delegated zcap or the root zcap. A verifier MUST ensure that a delegated zcap was created by a controller of its parent capability by checking its capability delegation proof.

A delegated zcap can only be invoked by submitting the entire zcap. A delegated zcap MUST have a capability delegation proof which MUST contain the delegation chain.

[target for link to capability chains]

A capability delegation chain MUST be an array that includes the root zcap using its ID (i.e., by reference only, not embedded) and every other delegated zcap in its ancestry must be referenced by ID except for the parent delegated zcap, which MUST be fully embedded. This ensures that delegated zcaps are of minimal size (other delegated zcaps in the chain are never repeated) and that every delegated zcap can be dereferenced directly from the chain without ever having to hit a network resource or similar. The capability delegation chain is ordered; the first entry MUST be the root zcap's ID and any other entries must be in the order of delegation from least recent to most recent.

A verifier MUST limit the length of the capability chain to prevent long chain attacks. A verifier SHOULD limit the length of the capability chain to 10. [exposition on why 10 / link to security section].

A root zcap MUST have an `invocationTarget` that is a string that expresses a URI. The invocation target identifies where the zcap may be invoked. A verifier MUST ensure that the `invocationTarget` either matches the `invocationTarget` in the parent capability or, if invocation target attenuation [link] is permitted, that it has the `invocationTarget` from the parent capability as a prefix. A prefix is defined as a base URI and parent path (and optional query) (i.e., `/`-delimited and `?`/`&`-delimited) [more rigorous definition].

A delegated zcap MUST have a `controller` that is a string or an array of strings that each express a URI that identifies a controller for the delegated zcap. The controller (or controllers) may take any allowed actions [link] with the invocation target (that are supported by the verifier) by invoking the delegated zcap. The controller (or controllers) may create delegated zcaps from the delegated zcap. Note: As with other data model sections in W3C specs, every property of a zcap should be called out in its own subsection along with the rules for the property.

A delegated zcap MUST have an `expires` field that expresses an XSD date-time Note: The JavaScript `new Date().toISOString()` code can produce such a date representation, though it is preferred to remove millisecond precision via `new Date().toISOString().slice(0, -5) + 'Z'`.

A verifier MUST ensure that an invoked delegated zcap has not expired. A verifier MUST ensure that a delegated zcap's expiration date-time is not less restrictive than its parent capability's expiration date-time, if present. Note: a root zcap does not have an expiration date-time.

A verifier SHOULD ensure that an invoked delegated zcap does not have an expiration date-time that is more than three months in the future. [TODO: exposition on why 3 months?] This is because a verifier MUST store revoked zcaps [link to revocation] until they expire, to prevent their use. A delegated zcap with an expiration date that is unreasonably far into the future will have to be stored for an unreasonable period of time to prevent its invocation. There are other mitigation strategies here, such as considering all zcaps delegated from a particular controller as revoked, or full key revocation.

Delegated zcaps MUST have expiration date-times to support good security hygiene practices and because zcaps support decentralized delegation. In order to revoke a zcap, it must be submitted to the verifier's revocation endpoint for the associated invocation target. If a delegated zcap has been lost or misplaced, it MUST eventually expire to avoid undesirable access.

A delegated zcap MAY have an `allowedAction` field that is a string or an array of strings that each express an action that the controller of the zcap may take when invoking the capability. A verifier MUST ensure that the `allowedAction` field in a delegated zcap is not less restrictive than the parent's capability, if present.

A delegated zcap MUST have a `proof` field that is an object or an array of objects that each express a DI proof. At least one of these proofs MUST be a zcap capability delegation proof. [TODO: more details on this proof]

A capability delegator (one who creates a delegated zcap) may attenuate authority by setting a more restrictive expiration date-time, a more restrictive invocation target (via URL path- or query-based attenuation), or a greater limit on the allowed actions. Taken together, the API that a verifier manages access is expected to have the flexibility required to model all desired authorization models.

URL Path- or Query-based Attenuation

Note: The `@context` / vocab-based caveats have been removed and replaced with:

A verifier will accept delegations (and invocations) where a suffix has been added to the parent zcap's invocation target (invoked zcap's invocation target). The suffix MUST start with `/` or `?` if the invocation target prefix has no `?`, and with `&` otherwise. This allows for fully customizable attenuations via HTTP API path and query parameters. For example, a ZCAP that can be invoked at `https://foo.example/bars/123` can be delegated with an attenuation such that the delegated ZCAP has an invocation target of `https://foo.example/bars/123/bazzes/456`. This could be further delegated and attenuated with a ZCAP with an invocation target of `https://foo.example/bars/123/bazzes/456?day=tuesday` and then again with `https://foo.example/bars/123/bazzes/456?day=tuesday&hour=12`.

Invoking a Delegated ZCAP

Just like with root zcaps, there can be multiple ways to invoke a delegated zcap; two are the same as with root zcaps and are defined with the differences described below:

When invoking a delegated zcap using an HTTP signature, a capability-invocation header must be included that includes the full delegated zcap in a `capability` parameter by serializing it to JSON, gzipping the result, and then base64url-encoding the gzipped JSON.

When invoking using a DI proof, the `capability` property must express the full delegated zcap.

TODO: Add section on revocation, detailing what verifiers MUST/SHOULD do to provide revocation endpoints for zcaps. A root invocation target SHOULD have a `/zcaps/revocations` subpath, where a root zcap of `urn:zcap:root:` can be invoked. The verifier SHOULD set the controllers for that root zcap to all controllers in the (to be revoked) zcap's chain so that any controller in the chain can revoke the zcap. Link to example server-side revocation implementation: https://github.com/digitalbazaar/ezcap-express/blob/main/lib/revoke.js

TODO: Detail algorithm for validation process: https://github.com/digitalbazaar/zcapld/blob/4386185f784f552d6eaeb2c3c82959cb2e09762e/lib/CapabilityProofPurpose.js#L85

TODO: Detail how revocation works: Any controller in the chain of a delegated zcap may post that zcap to: `/zcaps/revocations/` using the root zcap: `urn:zcap:root:encodeURIComponent(/zcaps/revocations/)` to revoke. Example: https://github.com/digitalbazaar/ezcap-express/blob/main/lib/revoke.js

Introduction

Capabilities vs. Access Control Lists

ZCAP-LD by Example

Capabilities Are Safer

Root Capability

Invoking a Root ZCAP

Dereferencing a Root Capability on a Verifier System

Delegated Capability

URL Path- or Query-based Attenuation

Invoking a Delegated ZCAP

Terminology

Capabilities

Delegation through Capability Chains

Caveats

Invocation

Actions

Relationship to Verifiable Credentials

Handling abuse