[WIP] Add real examples in the description

Signed-off-by: Yogesh Deshpande <[email protected]>

cocli/COMID.md

@@ -11,19 +11,19 @@ JSON representation via the `--template` switch (or equivalently its `-t` shorth
 * Please inspect `comid` JSON templates as examples under `data/comid/templates` `comid-*.json`
 
 ```
-$ cocli comid create --template t1.json
+$ cocli comid create --template data/comid/templates/comid-dice-refval.json
 ```
 On success, you should see something like the following printed to stdout:
 ```
->> created "t1.cbor" from "t1.json"
+>> created "comid-dice-refval.cbor" from "comid-dice-refval.json"
 ```
 
 The CBOR-encoded CoMID file is stored in the current working directory with a
 name derived from its template.  If you want, you can specify a different
 target directory using the `--output-dir` command line switch (abbrev. `-o`)
 ```
-$ cocli comid create --template t1.json --output-dir /tmp
->> created "/tmp/t1.cbor" from "t1.json"
+$ cocli comid create --template data/comid/templates/comid-dice-refval.json --output-dir /tmp
+>> created "/tmp/comid-dice-refval.cbor" from "comid-dice-refval.json"
 ```
 Note that the output directory, as well as all its parent directories, MUST
 pre-exist.
@@ -33,19 +33,19 @@ stored in the `templates/` folder:
 ```
 $ tree templates/
 templates/
-├── t1.json
-├── t2.json
+├── comid-dice-refval1.json
+├── comid-dice-refval2.json
 ...
-└── tn.json
+└── comid-dice-refvaln.json
 ```
 Then, you can use the `--template-dir` (abbrev. `-T`), and let the tool load,
 validate, and CBOR-encode the templates one by one:
 ```
 $ cocli comid create --template-dir templates
->> created "t1.cbor" from "templates/t1.json"
->> created "t2.cbor" from "templates/t2.json"
+>> created "comid-dice-refval1.cbor" from "templates/comid-dice-refval1.json"
+>> created "comid-dice-refval2.cbor" from "templates/comid-dice-refval2.json"
 ...
->> created "tn.cbor" from "templates/tn.json"
+>> created "comid-dice-refvaln.cbor" from "templates/comid-dice-refvaln.json"
 ```
 
 You can specify both the `-T` and `-t` switches as many times as needed, and
@@ -75,51 +75,42 @@ validation error will be printed alongside the corresponding file name.
 
 For example:
 ```
-$ cocli comid display --file m1.cbor
+$ cocli comid display --file comid-dice-refval.cbor
 ```
-provided the `m1.cbor` file contains valid CoMID, would print something like:
+provided the `comid-dice-refval.cbor` file contains valid CoMID, would print something like:
 ```
->> [m1.cbor]
+>> [comid-dice-refval.cbor]
 {
-  "lang": "en-GB",
   "tag-identity": {
-    "id": "43bbe37f-2e61-4b33-aed3-53cff1428b16"
+    "id": "1d5a8c7c-1c70-4c56-937e-3c5713ae5a83"
   },
-  "entities": [
-    {
-      "name": "ACME Ltd.",
-      "regid": "https://acme.example",
-      "roles": [
-        "tagCreator",
-        "creator",
-        "maintainer"
-      ]
-    }
+  "triples": {}
 [...]
+}
 ```
-While a `comids.d` folder with the following contents:
+While a `data/comid/` folder with the following contents:
 ```
-$ tree comids.d/
-comids.d/
+$ tree data/comid/
+data/comid/
 ├── rubbish.cbor
-├── valid-comid-1.cbor
-└── valid-comid-2.cbor
+├── 1.cbor
+└── 2.cbor
 ```
 could be inspected in one go using:
 ```
-$ cocli comid display --dir comids.d/
+$ cocli comid display --dir data/comid/
 ```
 which would output something like:
 ```
 >> failed displaying "comids.d/rubbish.cbor": CBOR decoding failed: EOF
->> [comids.d/valid-comid-1.cbor]
+>> [data/comid/1.cbor]
 {
   "tag-identity": {
     "id": "43bbe37f-2e61-4b33-aed3-53cff1428b16"
   },
 [...]
 }
->> [comids.d/valid-comid-2.cbor]
+>> [data/comid/2.cbor]
 {
   "tag-identity": {
     "id": "366d0a0a-5988-45ed-8488-2f2a544f6242"

cocli/CORIM.md

@@ -1,12 +1,11 @@
-
-## CoRIMs manipulation
+# CoRIMs manipulation
 
 The `corim` subcommand allows you to create, display, sign, verify CoRIMs or submit
 a CoRIM using the [Veraison provisioning API](https://github.com/veraison/docs/tree/main/api/endorsement-provisioning).
 It also provides a means to extract as-is the embedded CoSWIDs, CoMIDs and CoTSs and save
 them as separate files.
 
-### Create
+## Create
 
 Use the `corim create` subcommand to create a CBOR-encoded, unsigned CoRIM, by
 passing its JSON representation via the `--template` switch (or equivalently its `-t` shorthand)
@@ -15,41 +14,41 @@ together with the CBOR-encoded CoMIDs, CoSWIDs and/or CoTS to be embedded.
 * Please inspect `corim` JSON templates as examples under `data/corim/templates` `corim-*.json`
 
 ```
-$ cocli corim create --template c1.json --comid m1.cbor --coswid s1.cbor --cots c1.cbor
+$ cocli corim create --template data/corim/templates/corim-full.json --comid comid-dice-refval.cbor --coswid data/coswid/1.cbor --cots data/cots/c1.cbor
 ```
 On success, you should see something like the following printed to stdout:
 ```
->> created "c1.cbor" from "c1.json"
+>> created "corim-full.cbor" from "corim-full.json"
 ```
 
 The CBOR-encoded CoRIM file is stored in the current working directory with a
 name derived from its template.  If you want, you can specify a different
 file name using the `--output` command line switch (abbrev. `-o`):
 ```
-$ cocli corim create -t r1.json -m m1.cbor -s s1.cbor -c c1.cbor -o my.cbor
->> created "my.cbor" from "r1.json"
+$ cocli corim create -t data/corim/templates/corim-full.json -m comid-dice-refval.cbor -s data/coswid/1.cbor -c data/cots/c1.cbor -o my-corim.cbor
+>> created "my-corim.cbor" from "corim-full.json"
 ```
 
 CoMIDs, CoSWIDs and CoTSs can be either supplied as individual files, using the
 `--comid` (abbrev. `-m`), `--coswid` (abbrev. `-s`) and `--cots` (abbrev. `-c`) switches respectively, or
 as "per-folder" blocks using the `--comid-dir` (abbrev. `-M`), `--coswid-dir` and `--cots-dir`
 (abbrev. `-C`) switch.  For example:
 ```
-$ cocli corim create --template c1.json --comid-dir comids.d/
+$ cocli corim create --template data/corim/templates/corim-full.json --comid-dir data/comid/cbor/
 ```
 
 Creation will fail if *any* of the inputs is non conformant.  For example, if
-`comids.d` contains an invalid CoMID file `rubbish.cbor`, an attempt to create a
+`data/comid/cbor/` contains an invalid CoMID file `rubbish.cbor`, an attempt to create a
 CoRIM:
 ```
-$ cocli corim create -t c1.json -M comids.d/
+$ cocli corim create -t data/corim/templates/corim-full.json -M data/comid/cbor/
 ```
 will fail with:
 ```
-Error: error loading CoMID from comids.d/rubbish.cbor: EOF
+Error: error loading CoMID from data/comid/cbor/rubbish.cbor: EOF
 ```
 
-### Sign
+## Sign
 
 Use the `corim sign` subcommand to cryptographically seal the unsigned CoRIM
 supplied via the `--file` switch (abbrev. `-f`).  The signature is produced
@@ -68,35 +67,35 @@ $ cocli corim sign --file corim.cbor --key ec-p256.jwk --meta meta.json
 ```
 Or, the same but with a custom output file:
 ```
-$ cocli corim sign --file corim.cbor \
-                 --key ec-p256.jwk \
+$ cocli corim sign --file data/corim/corim.cbor \
+                 --key data/keys/ec-p256.jwk \
                  --meta meta.json \
                  --output /var/spool/signed-corim.cbor
 >> "corim.cbor" signed and saved to "/var/spool/signed-corim.cbor"
 ```
 
-### Verify
+## Verify
 
 Use the `corim verify` subcommand to cryptographically verify the signed CoRIM
 supplied via the `--file` switch (abbrev. `-f`).  The signature is checked
 using the key supplied via the `--key` switch (abbrev. `-k`), which is expected
 to be in [JWK](https://www.rfc-editor.org/rfc/rfc7517) format.  For example:
 ```
-$ cocli corim verify --file signed-corim.cbor --key ec-p256.jwk
->> "corim.cbor" verified
+$ cocli corim verify --file data/corim/signed-corim.cbor --key data/keys/ec-p256.jwk
+>> "signed-corim.cbor" verified
 ```
 
 Verification can fail either because the cryptographic processing fails or
 because the signed payload or protected headers are themselves invalid.  For example:
 ```
-$ cocli corim verify --file signed-corim-bad-signature.cbor --key ec-p256.jwk
+$ cocli corim verify --file data/corim/signed-corim-bad-signature.cbor --key data/keys/ec-p256.jwk
 ```
 will give
 ```
 Error: error verifying signed-corim-bad-signature.cbor with key ec-p256.jwk: verification failed ecdsa.Verify
 ```
 
-### Display
+## Display
 
 Use the `corim display` subcommand to print to stdout a signed CoRIM in human
 readable (JSON) format.
@@ -108,7 +107,7 @@ validation errors will be printed instead.
 The output has two logical sections: one for Meta and one for the (unsigned)
 CoRIM:
 ```
-$ cocli corim display --file signed-corim.cbor
+$ cocli corim display --file data/corim/signed-corim.cbor
 Meta:
 {
   "signer": {
@@ -132,7 +131,7 @@ will see is the base64 encoding of their CBOR serialisation.  If you want to
 peek at the tags' content, supply the `--show-tags` (abbrev. `-v`) switch, which
 will add a further Tags section with one entry per each expanded tag:
 ```
-$ cocli corim display --file signed-corim.cbor --show-tags
+$ cocli corim display --file data/corim/signed-corim.cbor --show-tags
 Meta:
 {
 [...]
@@ -163,7 +162,7 @@ Tags:
 }
 ```
 
-### Extract CoSWIDs, CoMIDs and CoTSs
+## Extract CoSWIDs, CoMIDs and CoTSs
 
 Use the `corim extract` subcommand to extract the embedded CoMIDs, CoSWIDs and CoTSs
 from a signed CoRIM.