Skip to content

Commit 886672d

Browse files
committed
update Readme.md
1 parent 00c3d81 commit 886672d

File tree

1 file changed

+5
-106
lines changed

1 file changed

+5
-106
lines changed

rust/signed_doc/README.md

Lines changed: 5 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -2,90 +2,8 @@
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
10321
signed_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

Comments
 (0)