Skip to content

Specification

Abstract

Project Catalyst both produces and consumes a lot of different data objects, in different places of the system. To ensure the data object is authoritative, it must be signed. In addition to the data object content and the signature, metadata is also included to describe different kind of Catalyst Signed Document properties.

Motivation: why is this CIP necessary?

As we decentralize project catalyst, it will be required to unambiguously identify who produced some data object, and the purpose of it.

Specification

Catalyst Signed Document is COSE based structure, particularly COSE Signed Data Object COSE type. It fully inherits an original COSE design and specifies the details of different COSE header's fields.

Catalyst Signed Document metadata fields

To uniquely specify a Catalyst Signed Document id, type, version etc., a list of different metadata fields is specified.

Also as you can see from the specification, it is allowed to add any number of additional metadata fields, which could be specified for each type of document.

A full list of considered additional metadata fields.

All these fields will be encoded as the COSE protected header

Catalyst Signed Document metadata fields: signed_doc_meta.cddl 
; All encoders/decoders of this specification must follow deterministic cbor encoding rules
; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06

signed_doc_meta = { 
  "type" => UUID, ; UUID v4
  "id" => UUID, ; UUID v7
  "ver" => UUID, ; UUID v7

  1 => -8, ; "alg": EdDSA
  3 => text / int, ; "content type"
  ? content-encoding-key => "br", ; payload content encoding

  ~meta.additional_fields,

  * metadata-key => metadata-value
}

content-encoding-key = "Content-Encoding" / "content-encoding"

metadata-key = int / text
metadata-value = any

UUID = #6.37(bytes)

;# include additional_meta as meta

type

Each Catalyst Signed Document will have a type identifier called type.

The type is a UUID v4.

A full list of Catalyst supported document types

id

Every Catalyst Signed Document will have a unique ID. All Catalyst Signed Document with the same id are considered different versions of the same Catalyst Signed Document (read about ver). However, id uniqueness is only guaranteed on first use.

If the same id is used, by unauthorized publishers, the Catalyst Signed Document is invalid.

The id is a UUID v7.

The first time a Catalyst Signed Document is created, it will be assigned by the creator a new id which must be well constructed.

  • The time must be the time the Catalyst Signed Document was first created.
  • The random value must be truly random.

Creating id this way ensures there are no collisions, and they can be independently created without central co-ordination.

Note: All Catalyst Signed Documents are signed, the first creation of an id assigns that id to the creator and any assigned collaborators. A Catalyst Signed Document that is not signed by the creator, or an assigned collaborator, is invalid. There is no reasonable way an id can collide accidentally. Therefore, detection of invalid ids published by unauthorized publishers, could result in anti-spam or system integrity mitigations being triggered. This could result in all actions in the system being blocked by the offending publisher, including all otherwise legitimate publications by the same author being marked as fraudulent.

ver

Every Catalyst Signed Document in the system will be versioned. There can, and probably will, exist multiple versions of the same document.

The ver is a UUID v7.

The initial ver assigned the first time a Catalyst Signed Document is published MUST be identical to the id. Subsequent versions will retain the same id and will create a new ver, following best practice for creating a new UUID v7.

alg

This is an original COSE header field, which indicates the cryptography algorithm used for the security processing.

It must be equal to EdDSA value

Only ed25119 considered at this moment as the only option to be supported for signed objects.

content type

This is an original COSE header field, which indicates the content type of the content (COSE payload) data.

content encoding (optional)

This field is used to indicate the content encoding algorithm of the content data.

Supported encodings:

  • br - Brotli compressed data.

Catalyst Signed Document content

The Catalyst Signed Document content data is encoded (and could be additionally compressed, read content encoding) as COSE payload.

COSE signature protected header

As it mentioned earlier, Catalyst Signed Document utilizes COSE Signed Data Object format, which allows to provide multi-signature functionality. In that regard, each Catalyst Signed Document COSE signature must include the following protected header field:

; All encoders/decoders of this specification must follow deterministic cbor encoding rules
; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06

signature_protected_header = {
    4 => bytes ; "kid", UTF-8 encoded URI string
}
  • kid: A unique identifier of the signer. A UTF-8 encoded URI string.

This document is licensed under CC-BY-4.0.