CAIP-196: CACAO - Chain Agnostic CApability Object

Metadata
Status: DraftStandardCreated: 2021-11-01
Authors
Sergey Ukustov (@ukstv), Haardik (@haardikk21), Irakli Gozalishvili (@Gozala), Joel Thorstensson (@oed)
Links
GitHub pageDiscussion on Ethereum Magicians

Simple Summary

A Chain Agnostic CApability Object, or CACAO, is an IPLD representation of an object-capability.

Abstract

CACAO proposes a way to leverage varsig and multidid as well as IPLD to create a common representation for various different object-capability formats, such as SIWE, SIWx, and UCAN. The IPLD representation contains common fields shared between these format. In addition this CAIP also registers varsig codes for both SIWE + ReCap and UCAN.

Motivation

There has been a proliferation of ways to create object-capabilities in the web3 space. Most notably Sign-in with Ethereum, UCAN, Sign-in with X, and ReCap. All of these approaches share similar characteristics such as an issuer, audience, signature, etc. However, they are structured quite differently and have different constraints when it comes to how they are serialized and signed. Having a common representation strategy in IPLD can make it easier to interface with these various formats.

Specification

The specification consists of two main things, an IPLD schema that describes the data structure of a CACAO, and algorithms to convert SIWE(x), ReCap, and UCAN messages into and out of this data structure.

Container IPLD schema

The container schema described SHOULD be encoded using the dag-cbor IPLD codec.



Important to note is that in the Abilitiy array, every NB are treated as separate. For example,




is treated as "You can post drafts to the blog, or post any status on Fridays". If you want to represent "You can post drafts to the blog on Fridays" it would need to be expressed as,




Decode to IPLD


This section describes how to convert different object-capability formats into the IPLD schema described above.


SIWx + ReCap


The following values can be easily translated from the SIWx (CAIP-122) specification:


    

  • iss - a multidid encoded DID PKH constructued using address and chain-id
    • 

  • aud - a multidid encoded DID based on uri
    • 

  • v - set to version
    • 

  • nnc - set to nonce
    • 



Timestamps


    

  • iat - is based on issued-at
    • 

  • nbf - is based on not-before
    • 

  • exp - is based on expiration-time
    • 

  • fct.z-iat - timezone info from issued-at
    • 

  • fct.z-nbf - timezone info from not-before
    • 

  • fct.z-exp - timezone info from expiration-time
    • 



See Appendix A for the algorithm used for the conversion.


ReCap


CACAO only allows there to be one ReCap message per SIWx message.


    

  • prf - set to recap.prf, make sure that the CIDs get encoded as IPLD links
    • 

  • att - set to recap.att, these should map 1-to-1
    • 



Additional fields


    

  • fct.domain should be set to domain
    • 

  • fct.statement should be set to statement (if the SIWx message contain a ReCap, the redundant data MUST be removed, e.g. recap-preamble 1*(" " recap-statement-entry "."), according to ReCap eip)
    • 

  • fct.request-id should be set to request-id
    • 

  • fct.resources should be set to an array containing all strings in resources except the ReCap resource
    • 



Signature


The s field is a signature encoded as a varsig and depends on which SIWx type is used. A few examples are outlined below,


SIWx, eip191:


    

  • content_multicodec - set to caip122-eip191, 0xd51e
    • 

  • multihash - set to keccak-256, 0x1b
    • 

  • key_multicodec - set to secp256k1, 0xe7
    • 

  • raw_signature - the signature bytes
    • 



SIWx, solana:


According to the solana namespace,


    

  • content_multicodec - set to caip122, 0xd510
    • 

  • multihash - set to sha2-256, 0x12
    • 

  • key_multicodec - set to ed25519, 0xed
    • 

  • raw_signature - the signature bytes
    • 



SIWx, tezos:


According to the tezos namespace,


    

  • content_multicodec - set to caip122, 0xd510
    • 

  • multihash - set to sha2-256, 0x12
    • 

  • key_multicodec - set to ed25519, 0xed (or other curves based on the tezos namespace)
    • 

  • raw_signature - the signature bytes
    • 



UCAN


Most fields in a UCAN should map 1-to-1 with the CACAO IPLD schema.


Additional fields


    

  • 

    v - set to ucv from the JWT header
    

    • 

  • 

    iss - convert the iss string of the UCAN to a multidid
    

    • 

  • 

    aud - convert the aud string of the UCAN to a multidid
    

    • 



Signature


The s field is a signature encoded as a varsig and depends on which signature algorithm was used for the UCAN JWT,


    

  • content_multicodec - set to ucan-jwt, 0xd001
    • 

  • raw_signature - the signature bytes
    • 



Examples based on alg in the JWT header:


EdDSA:


    

  • multihash - set to sha2-256, 0x12
    • 

  • key_multicodec - set to ed25519, 0xed
    • 



ES256K:


    

  • multihash - set to sha2-256, 0x12
    • 

  • key_multicodec - set to secp256k1, 0xe7
    • 



Other formats


Other formats can be added similarly to the examples above by registering a content_multicodec for the particular object-capability.


Signature Verification


To verify a signature of a CACAO the varsig specification is followed. Before verifying the signature the content_multicodec must be used to compute the digest used by the hash function and signature verification algorithm. Below the content_multicodec is described for 0xd510, 0xd51e, and 0xd001.


Content encoding: SIWx + ReCap


In order to verify the signature we first need to reconstruct the message that was signed. For caip122-eip191 (0xd51e) and caip122 (0xd510) we can start with the shared steps.


Reconstruct ReCap data


If present the ReCap URI and statement segment need to be reconstructed. Using the values from the CACAO reconstruct the ReCap json object (should be valid dag-json).




The recap statement segment is computed according to the ReCap eip, e.g. recap-preamble 1*(" " recap-statement-entry ".").


Reconstruct SIWx message


Start by computing values for:


    

  • address - extract address from DID PKH in cacao.iss
    • 

  • chain-id - extract chain id reference from DID PKH in cacao.iss
    • 



Timestamps:


    

  • issued-at - based on cacao.iat and cacao.fct.z-iat
    • 

  • not-before - based on cacao.nbf and cacao.fct.z-nbf
    • 

  • expiration-time - based on cacao.exp and cacao.fct.z-exp
    • 



See Appendix A for the algorithm used for the conversion.


Finally, construct the SIWx string:




Construct signature digest, caip122 0xd510:


digest = SIWx-string


Construct signature digest, caip122-eip191 0xd51e:


Simply prepend the message according to eip191:


digest = "\x19Ethereum Signed Message:\n" + SIWx-string


Content encoding: UCAN (0xd001)


Converting a CACAO to a UCAN string that can be verified is relatively simple. Remove the s and v fields from the CACAO object and encode it as dag-json. Stringify the json object and encode using base64url. The protected header is constructed as follows,


    

  • typ - MUST equal "JWT"
    • 

  • ucv - is set to cacao.v
    • 

  • alg - is based on key_multicodec and multihash in  cacao.v:

      

    • "EdDSA" if ed25519 and sha2-256
      • 

    • "ES256K" if secp256k1 and sha2-256
      • 

    

    • 



Stringify the protected header json object and encode it using base64url.


digest = protected-base64url + "." + payload-base64url


Serialization


For transport purposes a CACAO can be passed inside a base64url-serialized CAR file,
with root of the CAR file set to a tip of capability chain. Here and now we use CARv1 format, as CARv2 is still being worked on.


We propose, that all the necessary parent CACAOs are passed there as well. This way, even if a referenced CACAO is not yet available over IPFS, both consumer and presenter of CACAO still can access it.


Rationale


A common way to represent multiple different types of capabilities can enable more interoperability between object-capability systems and establishes a common ground for further innovation. CACAO relies on existing standards, such as DIDs and multicodec as a base layer for this interoperability.


Using IPLD as a represetation layer allows CACAO to easily be transfered over the internet, using IPFS or other protocols that can leverage its integrity checks.


We choose SIWx + ReCap and UCAN as examples since they represent a majority of the existing object-capabilities in use in the blockchain community today.


Backwards Compatibility


Present version of CACAO is a substantial change from the previous draft defined in CAIP-74.


Example


TODO - update these examples


Below you could find a CACAO, along with its serialized presentation in CAR file.


CACAO:




CACAO Serialized: base64url-encoded CARv1 file with the IPLD block of the CACAO above:




Appendix A: Timestamp converstion algorithm


The values in SIWx are encoded as RFC3339 strings, while CACAO requires unix timestamps (in seconds). The algorithm used to convert between the two is outlined below.


RFC3339 to UNIX + tz-info


    

  1. TODO
    2. 



UNIX + tz-info to RFC3339


    

  1. TODO
    2. 



Links



Copyright


Copyright and related rights waived via CC0.