ucan-wg/spec
User Controlled Authorization Network (UCAN) Specification - ucan-wg/spec
285 stars · 21 forks
README
User Controlled Authorization Network (UCAN) Specification Version 1.0.0 Editors
Brooklyn Zelenka, Witchcraft Software
Authors
Irakli Gozalishvili, Protocol Labs Daniel Holmgren, Bluesky Philipp Krüger, number zero Brooklyn Zelenka, Witchcraft Software
Sub-Specifications
UCAN Delegation UCAN Invocation UCAN Promise UCAN Revocation
Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. Abstract User-Controlled Authorization Network (UCAN) is a trustless, secure, local-first, user-originated, distributed authorization scheme. This document provides a high level overview of the components of the system, concepts, and motivation. Exact formats are given in sub-specifications. Introduction User-Controlled Authorization Network (UCAN) is a trustless, secure, local-first, user-originated, distributed authorization scheme. It provides public-key verifiable, delegable, expressive, openly extensible capabilities. UCANs achieve public verifiability with late-bound certificate chains and principals represented by decentralized identifiers (DIDs). UCAN improves the familiarity and adoptability of schemes like SPKI/SDSI for web and native application contexts. UCAN allows for the creation, delegation, and invocation of authority by any agent with a DID, including traditional systems and peer-to-peer architectures beyond traditional cloud computing. Motivation
If we practice our principles, we could have both security and functionality. Treating security as a separate concern has not succeeded in bridging the gap between principle and practice, because it operates without knowledge of what constitutes least authority. — Miller et al, The Structure of Authority
Since at least Multics, access control lists (ACLs) have been the most popular form of digital authorization, where a list of what each user is allowed to do is maintained on the resource. ACLs (and later RBAC) have been a successful model suited to architectures where persistent access to a single list is viable. ACLs require that rules are sufficiently well specified, such as in a centralized database with rules covering all possible permutations of scenario. This both imposes a very high maintenance burden on programmers as a systems grows in complexity, and is a key vector for confused deputies. With increasing interconnectivity between machines becoming commonplace, authorization needs to scale to meet the load demands of distributed systems while providing partition tolerance. However, it is not always practical to maintain a single central authorization source. Even when copies of the authorization list are distributed to the relevant servers, latency and partitions introduce troublesome challenges with conflicting updates, to say nothing of storage requirements. A large portion of personal information now also moves through connected systems. As a result, data privacy is a prominent theme when considering the design of modern applications, to the point of being legislated in parts of the world. Ahead-of-time coordination is often a barrier to development in many projects. Flexibility to define specialized authorization semantics for resources and the ability to integrate with external systems trustlessly are essential as the number of autonomous, specialized, and coordinated applications increases. Many high-value applications run in hostile environments. In recognition of this, many vendors now include public key functionality, such as non-extractable keys in browsers, certificate systems for external keys, platform keys, and [secure hardware enclaves] in widespread consumer devices. Two related models that work exceptionally well in the above context are Simple Public Key Infrastructure (SPKI) and object capabilities (OCAP). Since offline operation and self-verifiability are two requirements, UCAN adopts a certificate capability model related to SPKI. Intuition for Auth System Differences The following analogies illustrate several significant trade-offs between these systems but are only accurate enough to build intuition. A good resource for a more thorough presentation of these trade-offs is Capability Myths Demolished. In this framework, UCAN approximates SPKI with some dynamic features. Access Control Lists By analogy, ACLs are like a bouncer at an exclusive event. This bouncer has a list attendees allowed in and which of those are VIPs that get extra access. People trying to get in show their government-issued ID and are accepted or rejected. In addition, they may get a lanyard to identify that they have previously been allowed in. If someone is disruptive, they can simply be crossed off the list and denied further entry. If there are many such events at many venues, the organizers need to coordinate ahead of time, denials need to be synchronized, and attendees need to show their ID cards to many bouncers. The likelihood of the bouncer letting in the wrong person due to synchronization lag or confusion by someone sharing a name is nonzero. Certificate Capabilities UCANs work more like movie tickets or a festival pass. No one needs to check your ID; who you are is irrelevant. For example, if you have a ticket issued by the theater to see Citizen Kane, you are admitted to Theater 3. If you cannot attend an event, you can hand this ticket to a friend who wants to see the film instead, and there is no coordination required with the theater ahead of time. However, if the theater needs to cancel tickets for some reason, they need a way of uniquely identifying them and sharing this information between them. Object Capabilities Object capability ("ocap") systems use a combination of references, encapsulated state, and proxy forwarding. As the name implies, this is fairly close to object-oriented or actor-based systems. Object capabilities are robust, flexible, and expressive. To achieve these properties, object capabilities have two requirements: fail-safe, and locality preservation. The emphasis on consistency rules out partition tolerance1. Security Considerations Each UCAN includes an assertions of what it is allowed to do. "Proofs" are positive evidence (elsewhere called "witnesses") of the possession of rights. They are cryptographically verifiable chains showing that the UCAN issuer either claims to directly own a resource, or that it was delegated to them by some claimed owner. In the most common case, the root owner's ID is the only globally unique identity for the resource. Root capability issuers function as verifiable, distributed roots of trust. The delegation chain is by definition a provenance log. Private keys themselves SHOULD NOT move from one context to another. Keeping keys unique to each physical device and unique per use case is RECOMMENDED to reduce opportunity for keys to leak, and limit blast radius in the case of compromises. "Sharing authority without sharing keys" is provided by capabilities, so there is no reason to share keys directly. Note that a structurally and cryptographically valid UCAN chain can be semantically invalid. The executor MUST verify the ownership of any external resources at execution time. While not possible for all use cases (e.g. replicated state machines and eventually consistent data), having the Executor be the resource itself is RECOMMENDED. While certificate chains go a long way toward improving security, they do not provide confinement on their own. The principle of least authority SHOULD be used when delegating a UCAN: minimizing the amount of time that a UCAN is valid for and reducing authority to the bare minimum required for the delegate to complete their task. This delegate should be trusted as little as is practical since they can further sub-delegate their authority to others without alerting their delegator. UCANs do not offer confinement (as that would require all processes to be online), so it is impossible to guarantee knowledge of all of the sub-delegations that exist. The ability to revoke some or all downstream UCANs exists as a last resort. Inversion of Control Inversion of control is achieved due to two properties: self-certifying delegation and reference passing. There is no Authorization Server (AS) that sits between requestors and resources. In traditional terms, the owner of a UCAN resource is the resource server (RS) directly. This inverts the usual relationship between resources and users: the resource grants some (or all) authority over itself to agents, as opposed to an Authorization Server managing the relationship between them. This has several major advantages:
Fully distributed and scalable Self-contained request without intermediary Partition tolerance, support for replicated data and machines Flexible granularity Compositionality: no distinction between resources residing together or apart
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ │ │ │ │ ┌─────────┐ │ │ │ │ │ │ │ Bob's │ │ │ │ │ │ │ │ Photo │ │ │ │ │ │ │ │ Gallery │ │ │ │ │ │ │ └─────────┘ │ │ │ │ │ │ │ │ │ │ Alice's │ │ Bob's │ │ Carol's │ │ Stuff │ │ Stuff │ │ Stuff │ │ │ │ │ │ │ │ ┌───────┼───┼─────────────┼───┼──┐ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌───┼───┼──┼────────┐ │ │ │ │ │ Alice's │ │ │ │ │ │ │ │ │ │ Music │ │ │ │Carol's │ │ │ │ │ │ Player │ │ │ │ Game │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └───┼───┼──┼────────┘ │ │ │ │ │ │ │ │ │ │ └───────┼───┼─────────────┼───┼──┘ │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘
This additionally allows UCAN to model auth for eventually consistent and replicated state. Roles There are several roles that an agent MAY assume:
Name Description
Agent The general class of entities and principals that interact with a UCAN
Audience The Principal delegated to in the current UCAN. Listed in the aud field
Executor The Agent that actually performs the action described in an invocation
Invoker A Principal that requests an Executor perform some action that uses the Invoker's authority
Issuer The Principal of the current UCAN. Listed in the iss field
Owner A Subject that controls some external resource
Principal An agent identified by DID (listed in a UCAN's iss or aud field)
Revoker The Issuer listed in a proof chain that revokes a UCAN
Subject The Principal who's authority is delegated or invoked
Validator Any Agent that interprets a UCAN to determine that it is valid, and which capabilities it grants
flowchart TD subgraph Agent subgraph Principal direction TB
subgraph Issuer direction TB subgraph Subject direction TB Executor Owner end
Revoker end
subgraph Audience Invoker end end
Validator end
Loading
Subject
At the very least every object should have a URL — Alan Kay, The computer revolution hasn't happened yet
Every Erlang process in the universe should be addressable and introspective — Joe Armstrong, Code Mesh 2016
A [Subject] represents the Agent that a capability is for. A Subject MUST be referenced by DID. This behaves much like a GUID, with the addition of public key verifiability. This unforgeability prevents malicious namespace collisions which can lead to confused deputies. Resource A resource is some data or process that can be uniquely identified by a URI. It can be anything from a row in a database, a user account, storage quota, email address, etc. Resource MAY be as coarse or fine grained as desired. Finer-grained is RECOMMENDED where possible, as it is easier to model the principle of least authority (PoLA). A resource describes the noun of a capability. The resource pointer MUST be provided in URI format. Arbitrary and custom URIs MAY be used, provided that the intended recipient can decode the URI. The URI is merely a unique identifier to describe the pointer to — and within — a resource. Having a unique agent represent a resource (and act as its manager) is RECOMMENDED. However, to help traditional ACL-based systems transition to certificate capabilities, an agent MAY manage multiple resources, and act as the registrant in the ACL system. Unless explicitly stated, the Resource of a UCAN MUST be the Subject. Issuer & Audience The Issuer (iss) and Audience (aud) can be conceptualized as the sender and receiver (respectively) of a postal letter. Every UCAN MUST be signed with the private key associated with the DID in the iss field. For example: "aud": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp", "iss": "did:key:zDnaerDaTF5BXEavCrfRZEk316dpbLsfPDZ3WJ5hRTPFU2169", Please see the Cryptosuite section for more detail on DIDs. Lifecycle The UCAN lifecycle has four components:
Spec Description Requirement Level
Delegation Pass, attenuate, and secure authority in a partition-tolerant way REQUIRED
Invocation Exercise authority that has been delegated through one or more delegates REQUIRED
Promise Await the result of an Invocation inside another Invocation RECOMMENDED
Revocation Undo a delegation, breaking a delegation chain for malicious users RECOMMENDED
flowchart TD prm(Promise) inv(Invocation) del(Delegation) rev(Revocation)
prm -->|awaits| inv del -->|proves| inv rev -.->|kind of| inv rev -->|invalidates| del
click del href "https://github.com/ucan-wg/delegation" "UCAN Delegation Spec" click inv href "https://github.com/ucan-wg/invocation" "UCAN Invocation Spec" click rev href "https://github.com/ucan-wg/revocation" "UCAN Revocation Spec"
Loading
Time It is often useful to talk about a UCAN in the context of some action. For example, a UCAN delegation may be valid when it was created, but expired when invoked.
sequenceDiagram Alice -->> Bob: Delegate Bob ->> Bob: Validate Bob -->> Carol: Delegate Carol ->> Carol: Validate Carol ->> Alice: Invoke Alice ->> Alice: Validate Alice ->> Alice: Execute
Loading
Validity Interval The period of time that a capability is valid from and until. This is the range from the latest "not before" to the earliest expiry in the UCAN delegation chain. Delegation-Time The moment at which a delegation is asserted. This MAY be captured by an iat field, but is generally superfluous to capture in the token. Invocation-Time The moment a UCAN Invocation is created. It must be within the Validity Interval. Validation-Time Validation MAY occur at multiple points during a UCAN's lifecycle. The main two are:
On receipt of a delegation When executing an invocation
Execution-Time To avoid the overloaded word "runtime", UCAN adopts the term "execution-time" to express the moment that the executor attempts to use the authority captured in an invocation and associated delegation chain. Validation MUST occur at this time. Time Bounds nbf and exp stand for "not before" and "expires at," respectively. These MUST be expressed as seconds since the Unix epoch in UTC, without time zone or other offset. Taken together, they represent the time bounds for a token. These timestamps MUST be represented as the number of integer seconds since the Unix epoch. Due to limitations2 in numerics for certain common languages, timestamps outside of the range from $-2^{53} – 1$ to $2^{53} – 1$ MUST be rejected as invalid. The nbf field is OPTIONAL. When omitted, the token MUST be treated as valid beginning from the Unix epoch. Setting the nbf field to a time in the future MUST delay invoking a UCAN. For example, pre-provisioning access to conference materials ahead of time but not allowing access until the day it starts is achievable with judicious use of nbf. The exp field is RECOMMENDED. Following the principle of least authority, it is RECOMMENDED to give a timestamp expiry for UCANs. If the token explicitly never expires, the exp field MUST be set to null. If the time is in the past at validation time, the token MUST be treated as expired and invalid. Keeping the window of validity as short as possible is RECOMMENDED. Limiting the time range can mitigate the risk of a malicious user abusing a UCAN. However, this is situationally dependent. It may be desirable to limit the frequency of forced reauthorizations for trusted devices. Due to clock drift, time bounds SHOULD NOT be considered exact. A buffer of ±60 seconds is RECOMMENDED. Several named points of time in the UCAN lifecycle can be found in the [high level spec][UCAN]. Below are a couple examples: { // ... "nbf": 1529496683, "exp": 1575606941 } { // ... "exp": 1575606941 } { // ... "nbf": 1529496683, "exp": null } Lifecycle Example Here is a concrete example of all stages of the UCAN lifecycle for database write access.
sequenceDiagram participant Database
actor DBAgent actor Alice actor Bob
Note over Database, DBAgent: Set Up Agent-Owned Resource DBAgent ->> Database: createDB()
autonumber 1
Note over DBAgent, Bob: Delegation DBAgent -->> Alice: delegate(DBAgent, write) Alice -->> Bob: delegate(DBAgent, write)
Note over Database, Bob: Invocation Bob ->> DBAgent: invoke(DBAgent, [write, [key, value]], proof: [➊,➋]) DBAgent ->> Database: write(key, value) DBAgent ->> Bob: ACK
Note over DBAgent, Bob: Revocation Alice ->> DBAgent: revoke(➋, proof: [➊,➋]) Bob ->> DBAgent: invoke(DBAgent, [write, [key, newValue]], proof: [➊,➋]) DBAgent -X Bob: NAK(➏) [rejected]
Loading
Capability A capability is the association of an ability to a subject: subject x command x policy. The Subject and Command fields are REQUIRED. Any non-normative extensions are OPTIONAL. For example, a capability may used to represent the ability to send email from a certain address to others at @example.com.
Field Example
Subject did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
Command /msg/send
Policy ["or", ["==", ".from", "mailto:me@example.com"], ["match", ".cc", "mailto:*@example.com"]]
For a more complete treatment, please see the UCAN Delegation spec. Authority
Whether to enable cooperation or to limit vulnerability, we care about authority rather than permissions. Permissions determine what actions an individual program may perform on objects it can directly access. Authority describes the effects that a program may cause on objects it can access, either directly by permission, or indirectly by permitted interactions with other programs. —Mark Miller, Robust Composition
The set of capabilities delegated by a UCAN is called its "authority." To frame it another way, it's the set of effects that a principal can cause, and acts as a declarative description of delegated abilities. Merging capability authorities MUST follow set semantics, where the result includes all capabilities from the input authorities. Since broader capabilities automatically include narrower ones, this process is always additive. Capab