diff --git a/data/comid/README.md b/data/comid/README.md new file mode 100644 index 0000000..43faf9c --- /dev/null +++ b/data/comid/README.md @@ -0,0 +1,213 @@ + +# CoMID Template Format + +## Introduction + +**CoMID (Concise Model Identifier)**, is a structured tag that encapsulates detailed information about the composition of hardware, firmware, or modules. Each CoMID is uniquely identified by a specific ID, enabling unambiguous reference to CoMID instances, particularly in contexts such as typed link relations or CoBOM (Concise Bill of Material) tags. + +## Template Structure + +A CoMID template is a JSON document composed of **top-level fields** and a **triples** object. The **top-level fields** provide overall identification, language, and authorship, while the **triples** object contains domain-specific data (e.g., reference values, attester keys). + +``` +{ + "lang": "", + "tag-identity": { ... }, + "entities": [ ... ], + "triples": { + "reference-values": [ ... ], + "attester-verification-keys": [ ... ] + ... + } +} +``` + +### 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. +- **entities** (`Array`): Lists the entities (organizations, individuals, etc.) contributing to or maintaining the document, along with their roles. + +### 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 **attestation public key**. + + +## Components + +### Environment + +An **environment** captures the context of a measurement or verification key: + +- **class**: Vendor, model, and possibly an ID (`type` + `value`). +- **instance** (`optional`): For distinguishing multiple instances of the same environment (e.g., using `ueid` or `uuid`). +- **layer** and **index** (`optional`): For layered environments (e.g., DICE layers in multi-stage boot processes). + +### Measurements + +Each measurement has two crucial subfields: + +- **key**: Identifies the measurement, including possible fields like `label`, `version`, and `signer-id`. +- **value**: Holds the actual measurement data (e.g., cryptographic digests, raw values, or operational flags). + +### Attester Verification Keys + +Used to store **public keys** associated with an environment. This is essential for verifying the attestation claims or measurement signatures produced by that environment. + +## Field-By-Field Explanation + +### Global Fields +| Field | Type | Description | Example | +|:------------: |:------: |:-------------------------------------------------------: |:--------------------------------------------: | +| lang | String | Language/country code. | "en-GB" | +| tag-identity | Object | Identity of this CoMID tag (UUID + version). | "id": "43BBE37F-2E61-4B33-AED3-53CFF1428B16" | +| entities | Array | The organizations/roles associated with this CoMID tag. | [ { "name": "ACME Ltd." ... } ] | + +### Reference-Value Fields +| Field | Type | Description | Example | +|:------------------:|:------:|:----------------------------------------------------------------------------------:|:---------------------------------------------------------------------------------------------:| +| environment | Object | Contains class and optionally instance, layer, index. | See 3.1 Environment. | +| measurements | Array | List of measurement objects. | [ { "key": { ... }, "value": { ... } } ] | +| measurements.key | Object | Identifies the measurement. Could be a psa.refval-id, cca.platform-config-id, etc. | { "type": "psa.refval-id", "value": { "label": "BL", "version": "2.1.0", ... } } | +| measurements.value | Object | Holds the actual measurement data. | { "digests": ["sha-256:..."] }, or { "raw-value": { "type": "bytes", "value": "..." } }, etc. | + +### Attester-Verification-Key Fields +| 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-----..." } ] | +---------- + +### High Level Structure for CoMID Templates + +```mermaid +graph TD + A[CoMID Template] --> B[Global Fields] + A --> C[Triples] + B --> B1[lang] + B --> B2[tag-identity] + B --> B3[entities] + C --> C1[Reference Values] + C --> C2[Attester Verification Keys] + C1 --> C1a[Environment] + C1 --> C1b[Measurements] + C2 --> C2a[Environment] + C2 --> C2b[Verification Keys] +``` + +## Full Examples and Walkthroughs + +Below are the **seven** template files, each highlighting different aspects of CoMID usage. + +### comid-cca-mult-refval.json + +[comid-cca-mult-refval.json](https://github.com/veraison/cocli/blob/0d8fae8210ae527589792de2fba54442302380f7/data/comid/templates/comid-cca-mult-refval.json#L1-L93) + +**Key Points** + +- **Multiple Reference Values**: Demonstrates multiple reference values within a single environment. +- **Identifier Types**: Uses `psa.impl-id` for environment identifier. +- **Diverse Measurement Keys**: Showcases different measurement keys (`psa.refval-id` and `cca.platform-config-id`). +- **Raw Values**: Includes raw byte values for platform configuration. + +### comid-cca-realm-refval.json + +[comid-cca-realm-refval.json](https://github.com/veraison/cocli/blob/0d8fae8210ae527589792de2fba54442302380f7/data/comid/templates/comid-cca-mult-refval.json#L1-L93) + +**Key Points** + +- **UUID Identifiers**: Utilizes `uuid` type for environment identifiers, ensuring uniqueness. +- **Instance Field**: Includes an `instance` field of type `bytes` to differentiate instances. +- **Integrity Registers**: Uses `integrity-registers` to hold multiple cryptographic hash values across different measurement registers (`rim`, `rem0`, `rem1`, etc.). +- **Operational Flags**: Contains `op-flags` indicating properties like `notSecure` and `debug`. +- **Software Version Number (svn)**: Specifies software versioning with exact values. + +### comid-cca-refval.json + +[comid-cca-realm-refval.json](https://github.com/veraison/cocli/blob/0d8fae8210ae527589792de2fba54442302380f7/data/comid/templates/comid-cca-mult-refval.json#L1-L93) + +**Key Points** + +- **Multiple Reference-Value Entries**: Illustrates handling of multiple reference values within a single CoMID. +- **Operational Flags**: Uses `op-flags` to indicate operational states like `notSecure` and `debug`. +- **Software Version Numbers (svn)**: Uses `svn` to specify exact software versions for each measurement. +- **Layered Environments**: Demonstrates multi-layered environments (e.g., layer 0 and layer 1) with unique identifiers. +- **Digest Arrays**: Shows multiple digest entries within a single measurement for enhanced integrity verification. + +### comid-dice-refval.json + +[comid-cca-realm-refval.json](https://github.com/veraison/cocli/blob/0d8fae8210ae527589792de2fba54442302380f7/data/comid/templates/comid-cca-mult-refval.json#L1-L93) + +**Key Points** + +- **DICE Framework Integration**: The file name `comid-dice-refval.json` suggests integration with the DICE framework, which utilizes layered measurements for enhanced security. +- **Layered Measurements**: Contains multiple layers (`layer`: 0 and `layer`: 1), each with distinct environments and measurements. +- **Operational Flags**: Includes flags like `notSecure` and `debug` to indicate the operational state of each environment. +- **Software Version Numbers (svn)**: Uses `svn` to specify exact software versions for each measurement. +- **Multiple Digests**: Some measurements contain multiple digests to strengthen integrity verification. + +### comid-psa-iakpub.json + +[comid-cca-realm-refval.json](https://github.com/veraison/cocli/blob/0d8fae8210ae527589792de2fba54442302380f7/data/comid/templates/comid-cca-mult-refval.json#L1-L93) + +**Key Points** + +- **Public Keys for Attestation**: Stores two **verification-keys** under different **instances** (`ueid`: Unique Entity Identifier), enabling attesters to verify measurements or claims. +- **Key Formats**: Utilizes `pkix-base64-key` type, ensuring keys are in a standard PEM format. +- **Consistent Environment Class**: Both verification keys are associated with the same `class` (`psa.impl-id`, `vendor`, `model`), indicating they belong to the same hardware or firmware class. +- **Unique Instances**: Differentiates verification keys using unique `ueid` values, allowing multiple keys per environment. + +### comid-psa-integ-iakpub.json + +[comid-cca-realm-refval.json](https://github.com/veraison/cocli/blob/0d8fae8210ae527589792de2fba54442302380f7/data/comid/templates/comid-cca-mult-refval.json#L1-L93) + +**Key Points** + +- **Integration with PSA**: The file name indicates integration with the Platform Security Architecture (PSA), emphasizing secure key management. +- **Multiple Verification Keys**: Similar to `comid-psa-iakpub.json`, this file includes multiple verification keys, each associated with distinct `ueid` instances. +- **Key Material Variations**: Demonstrates how different environments can have unique key materials, enhancing security through key separation. +- **Consistent Class Definition**: Maintains the same `class` details across verification keys, ensuring they are recognized as part of the same environment. + +### comid-psa-refval.json + +- https://github.com/veraison/cocli/blob/0d8fae8210ae527589792de2fba54442302380f7/data/comid/templates/comid-psa-refval.json#L1 + +**Key Points** + +- **Consistent Reference Values**: All reference values utilize the `psa.refval-id` type, maintaining consistency in measurement identification. +- **Uniform Digest Algorithm**: Employs `sha-256` across all measurements, ensuring uniform integrity verification. +- **Signer Identification**: Each measurement includes a `signer-id`, linking the digest to its trusted signer. +- **Standard Structure**: Adheres to the standard CoMID structure for PSA-based reference values, facilitating interoperability and ease of verification. + + +### Lifecycle of a CoMID Templates + +```mermaid +flowchart TD + A[Start] --> B[Parse Command-Line Arguments] + B --> C{Templates Provided?} + C -- Yes --> D[Compile List of Template Files] + C -- No --> E[Error: No Templates Supplied] + E --> F[Exit] + D --> G{Files Found?} + G -- Yes --> H[Iterate Over Each Template] + G -- No --> I[Error: No Files Found] + I --> F + H --> J[Read Template File] + J --> K[Decode JSON Template] + K --> L[Validate Template Structure] + L --> M{Is Valid?} + M -- Yes --> N[Convert JSON to CBOR] + M -- No --> O[Log Validation Error] + O --> P{More Templates?} + P -- Yes --> H + P -- No --> Q{Errors Encountered?} + Q -- Yes --> R[Report Total Errors] + Q -- No --> S[Report Success] + R --> F + S --> F + N --> T[Determine Output Filename] + T --> U[Write CBOR File to Output Directory] + U --> P +``` diff --git a/data/corim/README.md b/data/corim/README.md new file mode 100644 index 0000000..c4fde41 --- /dev/null +++ b/data/corim/README.md @@ -0,0 +1,247 @@ +# CoRIM Template Format + +## Introduction + +**CoRIM** stands for **Concise Reference Integrity Manifest**, a structured format for describing reference integrity information, such as profiles, validity windows, entities, and dependent reference integrity manifests (RIMs). CoRIM can be leveraged in **remote attestation** scenarios, where it provides crucial metadata enabling **Verifiers** to evaluate trust in an **Attester** (e.g., a device or platform). + +## Conceptual Overview + +### What Is CoRIM? + +CoRIM is a **data model** that captures the high-level attributes of a reference integrity manifest, which might include: + +- **Profile URI** identifying a specification (e.g., CCA, PSA). +- **Validity** period during which the manifest is considered valid. +- **Entity** metadata describing organizations or roles in the manifest’s lifecycle. +- **Dependent RIMs** that describe or reference additional manifests. + +### CoRIM in the RATS Architecture + +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: + +- **As a container for Reference Values**: A CoRIM can describe what valid states or configurations look like (e.g., version info, cryptographic digests). +- **As part of an Endorsement**: Some Endorsers may package CoRIM data as “static claims” about a platform or firmware. +- **To link multiple RIMs**: CoRIM’s `dependent-rims` field can chain or reference external manifests, aligning with the multi-layer approach in RATS. + +## Template Structure + +A **CoRIM template** is frequently represented in JSON for **human-friendly editing**. At a minimum, it includes `corim-id` (a unique identifier). Optional fields like `profile`, `validity`, and `entities` provide deeper context: + +``` +{ + "corim-id": "", + "profile": "", + "validity": { + "not-before": "", + "not-after": "" + }, + "entities": [ ... ], + "dependent-rims": [ ... ] +} +``` + +### Top-Level Fields + +- **corim-id** (String/UUID): A globally unique identifier for the CoRIM. +- **profile** (String, optional): A URI referencing a particular standard (e.g., PSA, CCA). +- **validity** (Object, optional): A time window (`not-before` / `not-after`) of when the manifest is valid. +- **entities** (Array, optional): An array of organizations or roles involved. +- **dependent-rims** (Array, optional): An array referencing other RIMs or manifest resources. + +## Key Components + +### Profile + +- **Type**: `String (URI)` +- **Examples**: + - `"http://arm.com/cca/realm/1"` + - `"http://arm.com/psa/iot/1"` + +This field associates the manifest with a specific specification or profile. + +### Validity + +- **Type**: `Object` +- **Fields**: + - `not-before`: The earliest valid timestamp for using this manifest. + - `not-after`: The expiry timestamp after which the manifest is invalid. + +### Entities + +- **Type**: `Array of Objects` +- **Purpose**: Identifies the organizations or individuals related to the manifest (e.g., “manifestCreator”). +- **Fields**: + - `name`: Human-readable name of the entity. + - `regid`: A registration/domain identifier (e.g., `acme.example`). + - `roles`: Array of roles (e.g., `[ "manifestCreator" ]`). + +### Dependent RIMs (Optional) + +- **Type**: `Array of Objects` +- **Purpose**: Points to other reference integrity manifests or external references. +- **Fields**: + - `href`: A URL or resource identifier pointing to the external RIM. + - `thumbprint`: A cryptographic hash (e.g., `sha-256:...`) identifying the referenced object. + +---------- + +## Field-by-Field Explanation + +### Global Fields + +| Field | Type | Description | Example | | | +|:--------------:|:----------------:|:--------------------------------------------------------------:|:--------------------------------------------------------:|---|---| +| corim-id | String/UUID | Unique identifier for the CoRIM. | "5c57e8f4-46cd-421b-91c9-08cf93e13cfc" | | | +| profile | String (URI) | Points to a specific standard or specification. | "http://arm.com/cca/realm/1" | | | +| validity | Object | Optional object defining a time range (not-before, not-after). | "validity": {"not-before": "2021-12-31T00:00:00Z", ... } | | | +| entities | Array (optional) | Lists organizations and roles. | [{ "name": "ACME Ltd.", "regid": "acme.example", ... }] | | | +| dependent-rims | Array | Zero or more references to external RIMs. | [{"href": "...", "thumbprint": "sha-256:..."}] | | | + +### Meta Fields + +Often, separate **meta** files store supplementary data, such as **signer** information, which can be combined with a CoRIM for extended usage: + +| Field | Type | Description | Example | +|:--------:|:------:|:-----------------------------------------------------:|:----------------------------------------------:| +| signer | Object | Includes signer details (name, optional uri). | {"name": "ACME Ltd signing key", "uri": "..."} | +| validity | Object | May redefine or supplement the time window for usage. | {"not-before": "2021-12-31T00:00:00Z", ...} | + +---------- + +### High Level Structure for CoRIM Templates + +```mermaid +graph TD + A[CoMID Template] --> B[Global Fields] + A --> C[Triples] + B --> B1[lang] + B --> B2[tag-identity] + B --> B3[entities] + C --> C1[Reference Values] + C --> C2[Attester Verification Keys] + C1 --> C1a[Environment] + C1 --> C1b[Measurements] + C2 --> C2a[Environment] + C2 --> C2b[Verification Keys] +``` + +## Full Examples and Walkthroughs + +We have six JSON files that demonstrate various CoRIM states: + +### corim-cca-realm.json + +``` +{ + "corim-id": "5c57e8f4-46cd-421b-91c9-08cf93e13cfc", + "profile": "http://arm.com/cca/realm/1", + "validity": { + "not-before": "2021-12-31T00:00:00Z", + "not-after": "2025-12-31T00:00:00Z" + }, + "entities": [ + { + "name": "ACME Ltd.", + "regid": "acme.example", + "roles": [ + "manifestCreator" + ] + } + ] +} +``` + +- Demonstrates **CCA Realm** profile, a standard validity window, and basic entity info. + +### corim-cca.json + +``` +{ + "corim-id": "5c57e8f4-46cd-421b-91c9-08cf93e13cfc", + "profile": "http://arm.com/cca/ssd/1", + "validity": { + "not-before": "2021-12-31T00:00:00Z", + "not-after": "2025-12-31T00:00:00Z" + }, + "entities": [ + { + "name": "ACME Ltd.", + "regid": "acme.example", + "roles": [ + "manifestCreator" + ] + } + ] +} +``` +- Targets a **CCA SSD** profile with similar structure to the `corim-cca-realm.json`. + +### corim-full.json + +``` +{ + "corim-id": "5c57e8f4-46cd-421b-91c9-08cf93e13cfc", + "dependent-rims": [ + { + "href": "https://parent.example/rims/ccb3aa85-61b4-40f1-848e-02ad6e8a254b", + "thumbprint": "sha-256:5Fty9cDAtXLbTY06t+l/No/3TmI0eoJN7LZ6hOUiTXU=" + } + ], + "profile": "http://arm.com/psa/iot/1", + "validity": { + "not-before": "2021-12-31T00:00:00Z", + "not-after": "2025-12-31T00:00:00Z" + }, + "entities": [ + { + "name": "ACME Ltd.", + "regid": "acme.example", + "roles": [ + "manifestCreator" + ] + } + ] +} +``` + +- Includes a **dependent-rims** array referencing another RIM by `href` and `thumbprint`. +- Shows `profile` for a **PSA IoT** specification. + +### corim-mini.json + + +``` +{ + "corim-id": "5c57e8f4-46cd-421b-91c9-08cf93e13cfc" +} +``` + +- **Minimal** CoRIM: only the required `corim-id` is present. + +### meta-cca.json + +``` +{ + "signer": { + "name": "ACME Ltd signing key", + "uri": "https://acme.example" + }, + "validity": { + "not-before": "2021-12-31T00:00:00Z", + "not-after": "2025-12-31T00:00:00Z" + } +} +``` + +- A **meta** file providing `signer` details and a separate validity window. + +### meta-mini.json +``` +{ + "signer": { + "name": "ACME Ltd signing key" + } +} +``` + +- Minimal meta file defining only the `signer.name`. \ No newline at end of file diff --git a/data/pics/CoMID.png b/data/pics/CoMID.png new file mode 100644 index 0000000..f4f7759 Binary files /dev/null and b/data/pics/CoMID.png differ diff --git a/data/pics/comidLife.png b/data/pics/comidLife.png new file mode 100644 index 0000000..b439fe3 Binary files /dev/null and b/data/pics/comidLife.png differ