Unofficial Draft
Copyright © 2022 the document editors/authors. Text is available under the Creative Commons Attribution 4.0 International Public License; additional terms may apply.
This document is a draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organization.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key word MUST in this document is to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
This specification defines the following JSON-LD Context file: https://demo.didkit.dev/2022/cacao-zcap/contexts/v1.json
JSON-LD documents using CacaoZcap2022 and CacaoZcapProof2022 are expected to use this context file in @context following the
[SECURITY-VOCABULARY] context
(https://w3id.org/security/v2), i.e.:
{
"@context": [
"https://w3id.org/security/v2",
"https://demo.didkit.dev/2022/cacao-zcap/contexts/v1.json"
],
...
}| CACAO property | Relationship/Value | ZCAP property | Required? |
|---|---|---|---|
| h.t | = | cacaoPayloadType | yes |
| p.domain | = | proof.domain | yes |
| p.iss | DID ↔ DID URL | proof.verificationMethod | yes |
| p.aud | = | invoker | yes |
| p.version | "1" | – | yes |
| – | [...] | @context | yes |
| – | "CacaoZcap2022" | type | yes |
| – | "CacaoZcapProof2022" | proof.type | yes |
| p.nonce | = | proof.nonce | yes |
| p.iat | = | proof.created | yes |
| p.nbf | = | proof.validFrom | no |
| p.exp | = | expires | no |
| p.statement | statement-actions mapping | cacaoZcapSubstatement, allowedAction | no |
| p.requestId | = | requestId | no |
| . | CID → | id | no |
| p.resources[0] | = | invocationTarget | yes |
| p.resources[0] | URL ↔ ZCAP Root URN | proof.capabilityChain[0] | no |
| p.resources[1..n-2] | = | proof.capabilityChain[1..n-2] | no |
| p.resources[n-1] | Object ↔ Data URI | proof.capabilityChain[n-1] | no |
| s.t | = | proof.cacaoSignatureType | yes |
| s.s | bytes ↔ multibase | proof.proofValue | no |
The CACAO is serialized using [DAG-CBOR]. A SHA-256 hash is computed over this serialization. The last 16 bytes of the hash (dropping the initial 16) is used as "pseudo-random" input to a [RFC4122] v4 UUID. This UUID is represented as a URN by prefixing it with "urn:uuid:". This URN is used as the id of the delegation object.
The CACAO payload issuer property (p.iss) is defined by [CACAO]
to be a [DID-PKH] DID. The proof
verificationMethod
property is expected to be a
DID URL resolving to
a verification method map.
CACAO-ZCAP converts between these two fields (CACAO issuer and verification
method URL) by assuming that the issuer DID
has a default verification method, that the CACAO signature is created
using the
verification material
of that default verification method, and that the
default verification method allows creating a proof of type
CacaoZcapProof2022.
The first value of the CACAO payload resources array is used as the invocation
target URI, that is the value of the zcap delegation's
invocationTarget property. The invocation target URI is encoded
into a root zcap URN to become the root capability id. The root zcap URN is
constructed as the concatenation of "urn:zcap:root:" with
encodeURIComponent(invocationTarget). To transform the root zcap
URN to the invocation target URI, the prefix "urn:zcap:root:" is
removed and the remaining value is URL-decoded to return the invocation target
id.
If the proof capabilityChain array / CACAO resources array
(p.resources) contain more than two elements, the intermediate
elements are passed through as URIs.
The last value of the proof capabilityChain array / CACAO
resources array (p.resources) represents the previous delegation.
If the previous delegation is the root delegation, the
capabilityChain array contains only the root delegation id, as a
single value. If the previous delegation is a non-root delegation, the last
value of the proof capabilityChain array is the previous
delegation embedded as an object. The embedded previous delegation is
represented in the last value of the CACAO resources array
(p.resources) as a [RFC2397] Data URI containing the
Base64-encoded JSON object serialized with [RFC8785] JSON Canonicalization
Scheme (JCS).
In CACAO, the signature is represented with an IPLD bytes type. In ZCAP and data integrity proofs, the signature is typically represented in a string in the proofValue property of the proof object. CACAO-ZCAP encodes the signature in the proofValue property using [MULTIBASE].
The CACAO statement string MUST match the following ABNF (extending RFC 3986):
statement = stmt-noaction / stmt-action
stmt-noaction = "Authorize action" substmt-opt
stmt-action = "Authorize action (" actions ")" substmt-opt
substmt-opt = [ ": " substatement ]
actions = action *( ", " action )
action = *( reserved / unreserved / " " )
substatement = *( reserved / unreserved / " " )The substatement is the value of the cacaoZcapSubstatement proof property if present.
The action values are represented in the proof's allowedAction property as follows:
allowedAction is omitted when the stmt-noaction production is matched.allowedAction is an array of action strings when the stmt-actions production is matched.
This document defines the following terms, in the namespace
https://demo.didkit.dev/2022/cacao-zcap/#.
In JSON-LD, these terms may be imported using 2. Context.
A CACAO interpreted as an authorization capability delegation.
The proof property should be an object of type
CacaoZcapProof2022.
The invocationTarget property should be the URL to which an entity
is being authorized access.
A data integrity proof over an authorization capability delegation document (CacaoZcap2022), together representing a CACAO.
CACAO payload format type (CACAO header "t" value). e.g. "eip4361".
CACAO signature type (CACAO signature "t" value). e.g. "eip191" or "eip1271".
CACAO substatement, parsed from the CACAO payload "statement" value according to the statement-actions mapping.
CACAO request ID (CACAO payload "requestId" value).
This section is non-normative.
This section is non-normative.
Certain properties of the zCap delegation and proof object do not appear in the
CACAO object but are synthesized as part of the 3. CACAO-ZCAP Mapping. In
particular, the delegation type property with value CacaoZcap2022,
proof type property with value CacaoZcapProof2022, and proof
proofPurpose property with value
capabilityDelegation. Other properties are passed through from the
CACAO into the delegation/proof but with different property names, which may
have different meanings, e.g. iss as
verificationMethod, and iat as created.
It is possible therefore that an entity may sign/create a CACAO without
intending it to be used as
CacaoZcap2022/CacaoZcapProof2022 or realizing that it
may be used as such. Applications may want to pay close attention to the
CACAO-ZCAP statement substring (cacaoZcapSubstatement) - which is
expected to be seen by the user during signing - for determining how much to
rely on a CacaoZcap2022/CacaoZcapProof2022 for
authorization/delegation purposes.