22
33# Catalyst signed document
44
5- Catalyst signed document is [ COSE] based document structure,
6- particularly ` COSE Signed Data Object ` [ COSE] type.
7-
8- ## Structure
9-
10- This document structure is fully inherits an original [ COSE] design and specifies the details
11- of different [ COSE] header's fields.
12-
13- ### Protected header
14-
15- The [ COSE] standard defines two types of headers: ` protected ` and ` unprotected ` .
16- Catalyst signed document specifies the following ` protected ` header fields,
17- which ** must** be present (most of the fields originally defined by this
18- [ spec] ( https://input-output-hk.github.io/catalyst-voices/architecture/08_concepts/signed_document_metadata/metadata/ ) ):
19-
20- * ` alg ` : ` EdDSA `
21- (this parameter is used to indicate the algorithm used for the security processing,
22- in this particular case ` ed25119 ` signature algorithm is used).
23- * ` content type ` : ` application/json `
24- (this parameter is used to indicate the content type of the payload data,
25- in this particular case ` JSON ` format is used).
26- * ` content encoding ` (CBOR type ` text ` ): ` br ` CBOR type ` text `
27- (this parameter is used to indicate the content encodings algorithm of the payload data,
28- in this particular case [ brotli] compression data format is used).
29- * ` type ` : CBOR encoded UUID.
30- * ` id ` : CBOR encoded UUID.
31- * ` ver ` : CBOR encoded UUID.
32- * ` ref ` : CBOR encoded UUID or two elements array of UUID (optional).
33- * ` template ` : CBOR encoded UUID or two elements array of UUID (optional).
34- * ` reply ` : CBOR encoded UUID or two elements array of UUID (optional).
35- * ` section ` : CBOR encoded string (optional).
36- * ` collabs ` : CBOR encoded array of any CBOR types (optional).
37-
38- Precise CDDL definition
39-
40- ``` cddl
41- ; All encoders/decoders of this specification must follow deterministic cbor encoding rules
42- ; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06
43-
44- protected_header = {
45- 1 => -8, ; "alg": EdDSA
46- 3 => 30, ; "content type": Json
47- "content encoding" => "br", ; payload content encoding, brotli compression
48- "type" => UUID,
49- "id" => UUID,
50- "ver" => UUID,
51- ? "ref" => reference_type,
52- ? "template" => reference_type,
53- ? "reply" => reference_type,
54- ? "section" => text,
55- ? "collabs" => [+any],
56- }
57-
58- UUID = #6.37(bytes)
59- reference_type = UUID / [UUID, UUID] ; either UUID or [UUID, UUID]
60- ```
61-
62- ### COSE payload
63-
64- The [ COSE] signature payload, as mentioned earlier,
65- the content type of the [ COSE] signature payload is JSON, [ brotli] compressed.
66- Which stores an actual document data which should follow to some schema.
67-
68- ### Signature protected header
69-
70- As it mentioned earlier, Catalyst signed document utilizes ` COSE Signed Data Object ` format,
71- which allows to provide multi-signature functionality.
72- In that regard,
73- each Catalyst signed document [ COSE] signature ** must** include the following protected header field:
74-
75- ` protected ` :
76-
77- * ` kid ` : CBOR encoded ` bytes ` type.
78-
79- Precise CDDL definition
80-
81- ``` cddl
82- ; All encoders/decoders of this specification must follow deterministic cbor encoding rules
83- ; https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cde-06
84-
85- signature_protected_header = {
86- 4 => bytes ; "kid"
87- }
88- ```
5+ Catalyst signed document crate implementation based on this
6+ [ spec] ( https://input-output-hk.github.io/catalyst-libs/architecture/08_concepts/signed_doc/spec/ )
897
908## Example
919
@@ -99,33 +17,14 @@ Prepare non-signed document,
9917` meta.json ` file should follow the [ ` meta.schema.json ` ] ( ./meta.schema.json ) .
10018
10119``` shell
102- cargo run -p signed_doc --example mk_signed_doc build
20+ cargo run -p catalyst-signed-doc --example mk_signed_doc build
10321signed_doc/doc.json signed_doc/schema.json signed_doc/doc.cose signed_doc/meta.json
10422```
10523
106- Sign document
24+ Inspect document
10725
10826``` shell
109- cargo run -p signed_doc --example mk_signed_doc sign private.pem signed_doc/doc.cose kid_1
110- ```
111-
112- Verify document
113-
114- ``` shell
115- cargo run -p signed_doc --example mk_signed_doc verify
116- public.pem signed_doc/doc.cose signed_doc/schema.json
117- ```
118-
119- Catalyst signed document CBOR bytes example
120-
121- ``` cbor
122- 845861A6012703183270636F6E74656E7420656E636F64696E676262726474797065D825500CE8AB3892584FBCA62E7F
123- AA6E58318F626964D9800C500193929C1D227F1977FED19443841F0B63766572D9800C500193929C1D227F1977FED194
124- 43841F0BA0584E1B6D00209C05762C9B4E1EAC3DCA9286B50888CBDE8E99A2EB532C3A0D83D6F6462707ECDFF7F9B74B
125- 8904098479CA4221337F7DB97FDA25AFCC10ECB75722C91A485AAC1158BA6F90619221066C828347A104446B696431A0
126- 584090DF51433D97728ACF3851C5D3CA2908F76589EA925AF434C5619234E4B1BA7B12A124EA79503562B33214EBC730
127- C9837E1CA909BB8163D7904B09C3FD6A5B0B8347A104446B696432A05840AB318FEF3FF46E69E760540B0B44E9E8A51A
128- 84F23EC8A870ECDEBF9AD98EBB8212EBE5EA5FDBA87C98DF8DF259BE7873FE8B9EB54CC6558337B5C95D90CC3504
27+ cargo run -p catalyst-signed-doc --example mk_signed_doc inspect signed_doc/doc.cose
12928```
13029
13130[ COSE ] : https://datatracker.ietf.org/doc/html/rfc9052
0 commit comments