Add: Documentation for CoMID templates

[ravjot07]

@deeglaze I have created a basic documentation for CoMID templates..

I was working on this PR and thought that it might be useful to add a high level structure to format of these templates so can you take and look add this and decide whether we should put this is in docs or not ??

And one more suggestion i need was does should we add description for all the 7 provided templates in CoMID or not?

Contributes towards #18

[deeglaze]

Thank you, this is a great start.

[deeglaze]

These don’t match the CoMID spec.

[ravjot07]

@deeglaze could you be more specfic as i got it in most of the templates like

            "key": {
              "type": "psa.refval-id",
              "value": {
                "label": "PRoT",
                "version": "1.3.5",
                "signer-id": "rLsRx+TaIXIFUjzkzhokWuGiOa48a/2eeHH35di66Gs="
              }
            }

[deeglaze]

This doesn’t match the common attestation terminology. An attestation private key signs an attestation, and the attestation public key is used to verify attestation signatures, but I wouldn’t call that a verification key.

[ravjot07]

In comid-psa-iakpub.json template file term used is verification keys for array, like could you provide some reference for this

"attester-verification-keys": [
      {
        "environment": {
          "class": {
            "id": {
              "type": "psa.impl-id",
              "value": "YWNtZS1pbXBsZW1lbnRhdGlvbi1pZC0wMDAwMDAwMDE="
            },
            "vendor": "ACME",
            "model": "RoadRunner"
          },
          "instance": {
            "type": "ueid",
            "value": "Ac7rrnuJJ6MiflMDz14PH3s0u1Qq1yUKwD+83jbsLxUI"
          }
        },
        "verification-keys": [
          {
            "type": "pkix-base64-key",
            "value": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEFn0taoAwR3PmrKkYLtAsD9o05KSM6mbgfNCgpuL0g6VpTHkZl73wk5BDxoV7n+Oeee0iIqkW3HMZT3ETiniJdg==\n-----END PUBLIC KEY-----"
          }
        ]
      }

[thomas-fossati]

@ravjot07, you could use "attestation public key" rather than "verification-keys" in L34.

Note: the way we encode verification keys for CCA and PSA will likely change to use the CoTS (i.e., trusted anchors) format instead. So, it's not something worth much sweating at this point.

[deeglaze]

This enumeration confuses what is optional and required, as well as what is where. The layer and index are optional fields of class, whereas instance is at the same level as class.

[ravjot07]

@ravjot07 take a look at these here:- https://github.com/ravjot07/cocli/tree/docs/data/comid#42-reference-value-fields
actually i had simply used excel file for these tables and then later converted it into md format using online tools like table converter

[deeglaze]

Still would rename these

[deeglaze]

Please keep separate sentences on separate lines. I don’t know what is meant by traceability here.

[ravjot07]

this is what i get form https://datatracker.ietf.org/doc/draft-ietf-rats-corim/ page no 15 and from here i meant by tracebility is that we could extract information about hardware, firmware

A CoMID tag contains information about hardware, firmware, or module
   composition.

   Each CoMID has a unique ID that is used to unambiguously identify
   CoMID instances when cross referencing CoMID tags, for example in
   typed link relations, or in a CoBOM tag.

   A CoMID defines several types of Claims, using "triples" semantics.

[ravjot07]

sure i will keep separate sentences on separate lines.

[deeglaze]

I wouldn't say traceability when you really just mean the integrity of the measurements. There's a whole other form of supply chain security that tracks the links in the chain from source to binary that isn't captured by the CoRIM specification.

[ravjot07]

@deeglaze i have documented example templates and added some flowcharts for more clarity. pl review them

[thomas-fossati]

Thanks very much @ravjot07, this is really awesome!

I have left a few comments for you inline.

Besides, could you fix the DCO check, please?

Thank you again for your contribution!

[thomas-fossati]

@ravjot07, you could use "attestation public key" rather than "verification-keys" in L34.

Note: the way we encode verification keys for CCA and PSA will likely change to use the CoTS (i.e., trusted anchors) format instead. So, it's not something worth much sweating at this point.

[thomas-fossati]

Leftover comment/suggestion.

[thomas-fossati]

Suggested change

	In the **IETF RATS architecture** ([RFC9334]), a **Verifier** appraises **Evidence** (the Attester’s state claims) against **Reference Values** or **Endorsements** (often created or authorized by an Endorser). CoRIM can be used:
	In the **IETF RATS architecture** ([RFC9334](https://rfc-editor.org/rfc/rfc9334)), a **Verifier** appraises **Evidence** (the Attester’s state claims) against **Reference Values** or **Endorsements** (often created or authorized by an Endorser). CoRIM can be used:

[ravjot07]

Thanks very much @ravjot07, this is really awesome!

I have left a few comments for you inline.

Besides, could you fix the DCO check, please?

Thank you again for your contribution!

I really appreciate your review on this! I'll make the requested changes accordingly. Thank you for your feedback!

[ravjot07]

@thomas-fossati i have updated docs can you review them..

[thomas-fossati]

since we have the mermaid equivalent, this can be safely removed now

[thomas-fossati]

ditto

[thomas-fossati]

(I thought I had made this comment in the previous review cycle, but I cannot find it here, so...)

Rather than making verbatim copies of the files (which will eventually go out of sync), it's better to reference the originals here.

GitHub has a "code snippet" functionality that comes in handy: by copying the permalink to the JSON file (and adding the wanted lines range), the file is embedded in the rendered markdown -- which is pretty cool.

[thomas-fossati]

To be a bit more concrete: using the permalink to comid-cca-mult-refval.json (including explicit line range) https://github.com/veraison/cocli/blob/0d8fae8210ae527589792de2fba54442302380f7/data/comid/templates/comid-cca-mult-refval.json#L1-L93 will render as:

cocli/data/comid/templates/comid-cca-mult-refval.json

Lines 1 to 93 in 0d8fae8

	{
	"lang": "en-GB",
	"tag-identity": {
	"id": "43BBE37F-2E61-4B33-AED3-53CFF1428B16",
	"version": 0
	},
	"entities": [
	{
	"name": "ACME Ltd.",
	"regid": "https://acme.example",
	"roles": [
	"tagCreator",
	"creator",
	"maintainer"
	]
	}
	],
	"triples": {
	"reference-values": [
	{
	"environment": {
	"class": {
	"id": {
	"type": "psa.impl-id",
	"value": "YWNtZS1pbXBsZW1lbnRhdGlvbi1pZC0wMDAwMDAwMDE="
	},
	"vendor": "ACME",
	"model": "RoadRunner"
	}
	},
	"measurements": [
	{
	"key": {
	"type": "psa.refval-id",
	"value": {
	"label": "BL",
	"version": "2.1.0",
	"signer-id": "rLsRx+TaIXIFUjzkzhokWuGiOa48a/2eeHH35di66Gs="
	}
	},
	"value": {
	"digests": [
	"sha-256:h0KPxSKAPTEGXnvOPPA/5HUJZjHl4Hu9eg/eYMTPJcc="
	]
	}
	},
	{
	"key": {
	"type": "psa.refval-id",
	"value": {
	"label": "PRoT",
	"version": "1.3.5",
	"signer-id": "rLsRx+TaIXIFUjzkzhokWuGiOa48a/2eeHH35di66Gs="
	}
	},
	"value": {
	"digests": [
	"sha-256:AmOCmYm2/ZVPcrqvL8ZLwuLwHWktTecphuqAj26ZgT8="
	]
	}
	},
	{
	"key": {
	"type": "psa.refval-id",
	"value": {
	"label": "ARoT",
	"version": "0.1.4",
	"signer-id": "rLsRx+TaIXIFUjzkzhokWuGiOa48a/2eeHH35di66Gs="
	}
	},
	"value": {
	"digests": [
	"sha-256:o6XnFfDMV0pzw/m+u2vCTzL/1bZ7OHJEwskJ2neaFHg="
	]
	}
	},
	{
	"key": {
	"type": "cca.platform-config-id",
	"value": "cfg v1.0.0"
	},
	"value": {
	"raw-value": {
	"type": "bytes",
	"value": "cmF3dmFsdWUKcmF3dmFsdWUK"
	}
	}
	}
	]
	}
	]
	}
	}

[thomas-fossati]

Does this work as intended? I understand from the GitHub docs you just need to slap the bare permalink URI on a separate line, without any wrapping.

[ravjot07]

Yaa this does not works as intended, i will add bare permalink

[ravjot07]

@thomas-fossati sir a also tried bare link but it does not work as intended

[thomas-fossati]

It's because you are working on a fork (I think). To work, the permalink must refer to the local repo. Try and test it with a permalink to the same files but in the ravjot07/cocli repo. If that works (it should), just replace them with the permalinks to the veraison/cocli copies. Leap of faith! :-)

[ravjot07]

sure @thomas-fossati i will give it a try