Add: Documentation for CoMID templates #20
Conversation
Signed-off-by: Ravjot Singh <[email protected]>
Signed-off-by: Ravjot Singh <[email protected]>
| ### 2.1 Top-Level Fields | ||
|
|
||
| - **lang** (`String`): Defines the language or locale (e.g., `"en-GB"`). | ||
| - **tag-identity** (`Object`): Uniquely identifies this CoMID document via an ID (often a UUID) and includes a version number. |
There was a problem hiding this comment.
Tag identifiers don’t have versions according to the spec.
There was a problem hiding this comment.
as in template, tag-identify have version information in it
"tag-identity": {
"id": "43BBE37F-2E61-4B33-AED3-53CFF1428B16",
"version": 0
},
|
|
||
| Each measurement has two crucial subfields: | ||
|
|
||
| - **key**: Identifies the measurement, including possible fields like `label`, `version`, and `signer-id`. |
There was a problem hiding this comment.
These don’t match the CoMID spec.
There was a problem hiding this comment.
@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="
}
}
| ### 2.2 Triples | ||
|
|
||
| - **reference-values**: One or more **reference-value** objects, each containing an **environment** and one or more **measurements**. | ||
| - **attester-verification-keys**: One or more **attester-verification-key** objects, each containing an **environment** and an array of **verification-keys**. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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-----"
}
]
}
| ### 4.2 Reference-Value Fields | ||
| | Field | Type | Description | Example | | ||
| |:------------------:|:------:|:----------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------:| | ||
| | environment | Object | Contains class and optionally instance, layer, index. | See 3.1 Environment. | |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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
| | Field | Type | Description | Example | | ||
| |:-----------------:|:------:|:---------------------------------------:|:---------------------------------------------------------------------------:| | ||
| | environment | Object | Defines the environment for these keys. | See 3.1 Environment. | | ||
| | verification-keys | Array | Holds one or more public keys. | [ { "type": "pkix-base64-key", "value": "-----BEGIN PUBLIC KEY-----..." } ] | |
There was a problem hiding this comment.
Still would rename these
data/comid/README.md
Outdated
|
|
||
| ## 1 Introduction | ||
|
|
||
| **CoMID (Concise Model Identifier)**, is a data model and serialization format (in JSON) for capturing **reference values** and **verification keys** that can be used in remote attestation and other trust-verification scenarios. By standardizing how measurements are captured and shared, CoMID facilitates **interoperability**, **integrity**, and **traceability** across various systems and vendors. |
There was a problem hiding this comment.
Please keep separate sentences on separate lines. I don’t know what is meant by traceability here.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
sure i will keep separate sentences on separate lines.
There was a problem hiding this comment.
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.
Co-authored-by: Dionna Amalie Glaze <[email protected]>
Signed-off-by: Ravjot Singh <[email protected]>
|
@deeglaze i have documented example templates and added some flowcharts for more clarity. pl review them |
@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