CAIP-74: CACAO - Chain Agnostic CApability Object

Metadata

Status: ReviewStandardCreated: 2021-11-01

Authors

Sergey Ukustov (@ukstv), Haardik (@haardikk21)

Links

GitHub page Discussion on Ethereum Magicians

Simple Summary

Represent a chain-agnostic Object Capability (OCAP), created using CAIP-122, as an IPLD object.

Abstract

In this document we define a way to record the result of CAIP-122 signing operation as an IPLD-based object capability (OCAP). This creates not just an event receipt of an authentication, but also a composable and replay-able authorization receipt for verifiable authorizations, when the message signed contains the appropriate fields. The first CACAO profile was tailored to the ethereum dapps supporting [EIP-4361][] but roughly equivalent profiles for other wallet/dapp ecosystems are being added over time.

Motivation

"Sign-in with X" is a way for a user to authenticate into a service, and provide authorization. In essense, it is a signature of a well-formed payload.

We could see this as a stepping point for a rich capability-based authorization system.

In order to do this, we would like to have a standardized IPLD-based representation of the payload and the signature, that together comprise a capability.

Specification

Container format

We start construction with declaring a container format, that represents a signed payload. It should contain meta-information, payload and signatures. For reference let's call such container CACAO (for Chain Agnostic CApability Object). We use IPLD schema language to describe the format. Reminder, unless a field is marked optional, it is mandatory.

Header uniquely identifies the payload format:

The header type will be caip122 in reference to the CAIP-122 specification for the SIWx data model. In an older version of the specification, the header type was restricted to eip4361 as it was designed to work only with Sign-in with Ethereum. As such, newer implementations MUST be able to deal with both header types appropriately.

The payload structure must be presented as follows:

It is important to note, that issuer here is did:pkh, which includes both blockchain address and blockchain network information. Also, as per CAIP-122 specificaction,iat, nbf, and exp are encoded as RFC 3339 date-time, which could include milliseconds precision.

The signature in essence is just bytes, but we have to give a hint on how the signature verification should work. The signature verification type is referenced from methods that are listed as possible within the CAIP-122 namespace.

This construction allows a dApp to uniformly request a SIWx signature regardless of the user's account nature.

Signature Verification

Signature signing and verification should follow the workflow as specified in the CAIP-122 namespaces. For example, for eip155 chains, we reconstruct the SIWx payload as follows, resulting in a message conformant with EIP-4361:

Signature verification goes according to t in SignatureMeta: For example,

eip191: use EIP-191,
eip1271: use EIP-1271.

Serialization

As a proper IPLD object, it can be deterministically serialized using CBOR into bytes. Performance is almost as fast as vanilla JSON serialization. For transport purposes we propose that a CACAO is 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

As a chain-agnostic standard, a capability should identify chain-specific signature methods.
While "Sign-in with X" standardizes payload format, the payload could be extended in future.
The standard should be usable for DID-based signing methods as well as blockchain based ones.
The format we are creating here should be uniquely serialized as an IPLD object; we expect it to be identified by CID.
A capability format described here should allow chaining capabilities together.
We should standardize on a url-safe serialization format of a capability chain suitable for well-established non-binary transport protocols.

Backwards Compatibility

In the previous version of this specification, the header type was restricted to eip4361 as it was designed to work only with Sign-in with Ethereum. Newer implementations should support both header types - eip4361 and caip122.

Example

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

CACAO:

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

Versioning

Present version of CAIP-74 updates and clarifies the previous versions:

Version 1 - CACAO for Sign-in with Ethereum