UCAN Canonicalization Spec v0.1.0

Editors

• Brooklyn Zelenka, Fission

Authors

• Hugo Dias, DAG House
• Irakli Gozalishvili, DAG House
• Daniel Holmgren, Bluesky
• Brooklyn Zelenka, Fission

Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

0 Abstract

Per the core UCAN spec, all implementations MUST support JWT encoding. This provides a common representation that all implementations can understand. JWT canonicalization allows for alternate encodings to convert to and from the standard JWT format, retain the JWT signature scheme, and so on. This enables broad compatibility.

1 Motivation

The base UCAN spec is given as a JWT, which is a very open format aimed at broad adoption, and with mature tooling. JWT does not specify aspects like whitespace, key ordering, and capitalization. There is no technical reason that the information contained in a UCAN could not be expressed in a different format, such as CWT or IPLD. By forcing a rigid format, JWT canonicalization provides a deterministic way to convert to and from JWT and other formats, while staying fully compatible with JWT validators.

2 Canonicalization

To canonicalize a UCAN, the JSON segments MUST fulfill the following requirements:

1. All can fields MUST be lowercase
2. All unused optional fields (such as fct) that are empty MUST be omitted
3. dag-json encoding MUST be used
4. The resulting JWT MUST be base64url encoded per [RFC 7519]
5. All segments MUST be joined with .s, per RFC 7519

UCAN canonicalization is signalled by CID. If no canonicalization is used, the CID MUST use the raw multicodec. Canonicalized UCANs that wish to signal this encoding MUST use any other CID codec, including but not limited to dag-json and dag-cbor.

2.1 Non-Canonical Validator CID Handling

Validators that have not implemented this specification MUST be provided JWT-encoded UCANs. These validators will be unable to validate the CID in the proofs field. This is not strictly a problem in a semi-trusted scenario, as UCAN only depends on the existence (not the specific CID) of a valid proof for the capabilities being claimed. The security risk is for a malicious peer to provide very long but ultimately invalid proof chains as a denial-of-service vector. This is the case for any validator that does not check the CID hash upon receipt.

3 Acknowledgments

Thanks to Philipp Krüger for his feedback on canonicalization signalling.