From 57a244500b252ca2add0420457a32afeb58d337c Mon Sep 17 00:00:00 2001 From: "Kumar, Atul" Date: Tue, 14 Apr 2026 10:52:31 +0000 Subject: [PATCH 1/2] docs: endorsement lifecycle mgmt. API API spec for activation/deactivation of triples using CoRIM IDs, CoMID IDs, or CoSERV query. Co-authored-by: Dhanus M Lal Co-authored-by: Kumar, Atul Signed-off-by: Kumar, Atul --- api/endorsement-provisioning/README.md | 129 ++++++++++++++++++ .../endorsement-provisioning.yaml | 90 +++++++++++- .../schemas/components.yaml | 23 ++++ 3 files changed, 240 insertions(+), 2 deletions(-) diff --git a/api/endorsement-provisioning/README.md b/api/endorsement-provisioning/README.md index 01e7f49..b138faf 100644 --- a/api/endorsement-provisioning/README.md +++ b/api/endorsement-provisioning/README.md @@ -132,3 +132,132 @@ format is CoRIM. "expiry": "2030-10-12T07:20:50.52Z" } ``` + +# Endorsement Lifecycle Management Interface + +This interface can be used for activating/deactivating endorsements provisioned +to the verifier. Two modes are supported: + +1. Using CoRIM/CoMID ids +2. Using CoSERV query + +In the first mode, a collection of CoRIM/CoMID ids (or a combination of both) +can be submitted, to activate/deactivate all endorsements that came from those +CoRIM/CoMIDs. The collection of IDs are structured in a JSON document: + +```json +{ + "profile": "tag:example.com,2025/example-profile", + "corim-ids": ["82702896-9ced-4952-88f4-8c1dc2c8af20"], + "comid-ids": ["6720f8cb-6594-493a-8fb7-f1bdff446eb5", "101ef8a1-0e72-449a-a1d2-031ee206b2f0"] +} +``` + +In the second mode, a CoSERV query is submitted and all the endorsements that +match the selection are activated/deactivated. The `result-type` field in +CoSERV query are ignored. + + +## Examples + +### Activating a combination of CoRIMs and CoMIDs +Activate a set of CoRIMs and CoMIDs using the `activate` API. + +#### Request + +``` +POST /endorsement-provisioning/v1/activate +Host: veraison.example +Content-Type: application/vnd.veraison.endorsement-id-collection+json + +{ + "profile": "tag:example.com,2025/example-profile", + "corim-ids": ["82702896-9ced-4952-88f4-8c1dc2c8af20"], + "comid-ids": ["6720f8cb-6594-493a-8fb7-f1bdff446eb5", "101ef8a1-0e72-449a-a1d2-031ee206b2f0"] +} +``` + +#### Response + +``` +HTTP/1.1 204 No Content +``` + +### Activating using CoSERV +Activate the trust anchors for the instance-ids `0x1234` and `0x2345`. + +#### Request +``` +POST /endorsement-provisioning/v1/activate +Host: veraison.example +Content-Type: application/coserv+cbor; profile="tag:vendor.com,2025/example-profile" + +-- body in EDN +{ + / profile / 0: "tag:vendor.com,2025/example-profile", + / query / 1: { + / artifact-type / 0: 1, / trust-anchors / + / environment-selector / 1: { + / instance / 1: [ [h'1234'], [h'2345'] ] + } + / result-type / 2: 0 / collected-artifacts / + } +} +``` + +#### Response +``` +HTTP/1.1 204 No Content +``` + + +### Deactivating a CoMID +Deactivating endorsements from a single CoMID + +#### Request +``` +POST /endorsement-provisioning/v1/deactivate +Host: veraison.example +Content-Type: application/vnd.veraison.endorsement-id-collection+json + +{ + "profile": "tag:example.com,2025/example-profile", + "comid-ids": ["101ef8a1-0e72-449a-a1d2-031ee206b2f0"] +} +``` + +#### Response +``` +HTTP/1.1 204 No Content +``` + +### Deactivating using CoSERV +Deactivate all reference values for a particular class of devices: + +#### Request +``` +POST /endorsement-provisioning/v1/deactivate +Host: veraison.example +Content-Type: application/coserv+cbor; profile="tag:vendor.com,2025/example-profile" + +-- body in EDN +{ + / profile / 0: "tag:vendor.com,2025/example-profile", + / query / 1: { + / artifact-type / 0: 2, / reference-values / + / environment-selector / 1: { + / class / 0: { + [ + [{ / model / 2: "model2" }] + ] + } + } + / result-type / 2: 0 / collected-artifacts / + } +} +``` + +#### Response +``` +HTTP/1.1 204 No Content +``` diff --git a/api/endorsement-provisioning/endorsement-provisioning.yaml b/api/endorsement-provisioning/endorsement-provisioning.yaml index 4e0e9eb..b0fa844 100644 --- a/api/endorsement-provisioning/endorsement-provisioning.yaml +++ b/api/endorsement-provisioning/endorsement-provisioning.yaml @@ -1,8 +1,8 @@ openapi: '3.0.0' info: - title: attestation endorsement provisioning - description: API to provision endorsements. For further details, see datatracker.ietf.org/doc/draft-birkholz-rats-corim + title: Attestation endorsement provisioning and management + description: API to provision and manage endorsements. For further details, see datatracker.ietf.org/doc/draft-birkholz-rats-corim version: '1.0.0alpha' servers: - url: 'https://veraison.example/endorsement-provisioning/v1' @@ -66,6 +66,92 @@ paths: $ref: './schemas/components.yaml#/components/schemas/SessionResource' default: $ref: './schemas/components.yaml#/components/responses/Error' + /activate: + post: + summary: Activate triples using CoMID or CoRIM IDs or CoSERV queries. + description: > + Activate triples using CoRIM/CoMID IDs or using CoSERV queries. + All the triples from the provided list of IDs or the triples + matching the CoSERV query environment are activated. If any of + the supplied IDs are not present or if there are no triples matching + the CoSERV query environment in the database, error is returned. + operationId: activateEndorsementsUsingIDs + requestBody: + required: true + content: + application/vnd.veraison.endorsement-id-collection+json: + schema: + $ref: './schemas/components.yaml#/components/schemas/IDCollection' + application/coserv+cbor: + schema: + type: string + format: binary + description: > + A CoSERV query as per draft-ietf-rats-coserv + responses: + '204': + description: > + Activation successful. All the CoRIM/CoMID ids for the profile, + which were posted are present in the database and all the triples + from those CoRIM/CoRIMs have been converted to active state. If + a coserv was supplied in the request body, this response code + means: There was at least one triple matching the + selection. All the matching triples are now in active state. + '404': + description: > + One or more IDs present in the collection were not found in the + store for the given profile. If a coserv was submitted, then + this response code means no matching triples were found. + content: + application/problem+json: + schema: + $ref: './schemas/components.yaml#/components/schemas/Problem' + default: + $ref: './schemas/components.yaml#/components/responses/Error' + + + /deactivate: + post: + summary: Deactivate triples using CoMID or CoRIM IDs or CoSERV queries. + description: > + Deactivate triples using CoRIM/CoMID IDs or using CoSERV queries. + All the triples from the provided list of IDs or the triples + matching the CoSERV query environment are deactivated. If any of + the supplied IDs are not present or if there are no triples matching + the CoSERV query environment in the database, error is returned. + operationId: deactivateEndorsementsUsingIDs + requestBody: + required: true + content: + application/vnd.veraison.endorsement-id-collection+json: + schema: + $ref: './schemas/components.yaml#/components/schemas/IDCollection' + application/coserv+cbor: + schema: + type: string + format: binary + description: > + A CoSERV query as per draft-ietf-rats-coserv + responses: + '204': + description: > + Deactivation successful. All the CoRIM/CoMID ids for the profile, + which were posted are present in the database and all the triples + from those CoRIM/CoRIMs have been converted to inactive state. If + a coserv was supplied in the request body, this response code + means: There was at least one triple matching the + selection. All the matching triples are now in inactive state. + '404': + description: > + One or more IDs present in the collection were not found in the + store for the given profile. If a coserv was submitted, then + this response code means no matching triples were found. + content: + application/problem+json: + schema: + $ref: './schemas/components.yaml#/components/schemas/Problem' + default: + $ref: './schemas/components.yaml#/components/responses/Error' components: parameters: SessionID: diff --git a/api/endorsement-provisioning/schemas/components.yaml b/api/endorsement-provisioning/schemas/components.yaml index e549901..25f12b1 100644 --- a/api/endorsement-provisioning/schemas/components.yaml +++ b/api/endorsement-provisioning/schemas/components.yaml @@ -26,6 +26,29 @@ components: type: string description: > Optional field to provide more details about the failure cause when provisioning status is `failed` + + IDCollection: + description: List of CoRIM or CoMID IDs. + type: object + required: + - profile + properties: + profile: + type: string + description: + CoRIM profile to which the CoRIM/CoMID ids belong to. + example: "tag:example.com,2025/example-profile" + corim-ids: + type: array + items: + type: string + description: List of CoRIM ids. + comid-ids: + type: array + items: + type: string + description: List of CoMID ids. + Problem: required: - title From 3c1823e76c9babb46a14eaa529aab6ef063192cd Mon Sep 17 00:00:00 2001 From: "Kumar, Atul" Date: Thu, 23 Apr 2026 15:20:09 +0530 Subject: [PATCH 2/2] feat: use coserv data model for activation/deactivation - use coserv data model primitives to create endorsements lifecycle management (ELM) queries >[!TODO] > Migrate from application/problem+json (RFC 9457) to > applicaton/concise-problem-details+cbor (RFC 9290). > This change should be applied to other endpoints > (and services) to maintain consistency in the response > encondings. Better to address it in a future PR when > consensus is reached on the response format(s). Signed-off-by: Kumar, Atul --- api/endorsement-provisioning/README.md | 137 +++++++----------- .../endorsement-provisioning.yaml | 73 +++------- .../schemas/components.yaml | 28 +--- api/well-known/schemas/components.yaml | 4 + 4 files changed, 80 insertions(+), 162 deletions(-) diff --git a/api/endorsement-provisioning/README.md b/api/endorsement-provisioning/README.md index b138faf..9baa31c 100644 --- a/api/endorsement-provisioning/README.md +++ b/api/endorsement-provisioning/README.md @@ -133,47 +133,61 @@ format is CoRIM. } ``` -# Endorsement Lifecycle Management Interface +# Endorsement Lifecycle Management (ELM) Interface This interface can be used for activating/deactivating endorsements provisioned -to the verifier. Two modes are supported: +to the verifier. It allows using CoSERV base types to define an ELM query that +can be used to select endorsements using either (stateful) environments or one or +more RIM identifiers. -1. Using CoRIM/CoMID ids -2. Using CoSERV query +## Query Format -In the first mode, a collection of CoRIM/CoMID ids (or a combination of both) -can be submitted, to activate/deactivate all endorsements that came from those -CoRIM/CoMIDs. The collection of IDs are structured in a JSON document: +Following is the CDDL format for an ELM query: +``` +elm-query = { + &(profile: 0) => coserv.profile + &(query: 1) => query +} -```json -{ - "profile": "tag:example.com,2025/example-profile", - "corim-ids": ["82702896-9ced-4952-88f4-8c1dc2c8af20"], - "comid-ids": ["6720f8cb-6594-493a-8fb7-f1bdff446eb5", "101ef8a1-0e72-449a-a1d2-031ee206b2f0"] +query = { + ( environment-query // rim-query ) } -``` -In the second mode, a CoSERV query is submitted and all the endorsements that -match the selection are activated/deactivated. The `result-type` field in -CoSERV query are ignored. +environment-query = ( + &(artifact-type: 0) => coserv.artifact-type + &(environment-selector: 1) => coserv.environment-selector-map +) +rim-query = ( + &(rim-selector: 3) => [ + coserv.rim-selector-id ] +) +``` ## Examples -### Activating a combination of CoRIMs and CoMIDs -Activate a set of CoRIMs and CoMIDs using the `activate` API. +### Deactivate keys +Use the `environment-query` variant to deactivate two keys by `instance-id`. #### Request ``` -POST /endorsement-provisioning/v1/activate +POST /endorsement-provisioning/v1/deactivate Host: veraison.example -Content-Type: application/vnd.veraison.endorsement-id-collection+json +Content-Type: application/vnd.veraison.elm-v1+cbor + +-- body in EDN { - "profile": "tag:example.com,2025/example-profile", - "corim-ids": ["82702896-9ced-4952-88f4-8c1dc2c8af20"], - "comid-ids": ["6720f8cb-6594-493a-8fb7-f1bdff446eb5", "101ef8a1-0e72-449a-a1d2-031ee206b2f0"] + / profile / 0: "tag:arm.com,2025/example-profile", + / query / 1: { + / artifact-type / 0: 1 / trust-anchors / + / environment-selector / 1: { + / instance / 1: [ + [ 550( h'01 ...' ) ], + [ 550( h'01 ...' ) ] + ] + }, + } } ``` @@ -183,81 +197,32 @@ Content-Type: application/vnd.veraison.endorsement-id-collection+json HTTP/1.1 204 No Content ``` -### Activating using CoSERV -Activate the trust anchors for the instance-ids `0x1234` and `0x2345`. +### Activate RIMs +Use the `rim-query` variant to activate two CoRIMs and one CoMID. #### Request + ``` POST /endorsement-provisioning/v1/activate Host: veraison.example -Content-Type: application/coserv+cbor; profile="tag:vendor.com,2025/example-profile" +Content-Type: application/vnd.veraison.elm-v1+cbor -- body in EDN -{ - / profile / 0: "tag:vendor.com,2025/example-profile", - / query / 1: { - / artifact-type / 0: 1, / trust-anchors / - / environment-selector / 1: { - / instance / 1: [ [h'1234'], [h'2345'] ] - } - / result-type / 2: 0 / collected-artifacts / - } -} -``` - -#### Response -``` -HTTP/1.1 204 No Content -``` - - -### Deactivating a CoMID -Deactivating endorsements from a single CoMID - -#### Request -``` -POST /endorsement-provisioning/v1/deactivate -Host: veraison.example -Content-Type: application/vnd.veraison.endorsement-id-collection+json - -{ - "profile": "tag:example.com,2025/example-profile", - "comid-ids": ["101ef8a1-0e72-449a-a1d2-031ee206b2f0"] -} -``` - -#### Response -``` -HTTP/1.1 204 No Content -``` - -### Deactivating using CoSERV -Deactivate all reference values for a particular class of devices: -#### Request -``` -POST /endorsement-provisioning/v1/deactivate -Host: veraison.example -Content-Type: application/coserv+cbor; profile="tag:vendor.com,2025/example-profile" - --- body in EDN { - / profile / 0: "tag:vendor.com,2025/example-profile", - / query / 1: { - / artifact-type / 0: 2, / reference-values / - / environment-selector / 1: { - / class / 0: { - [ - [{ / model / 2: "model2" }] - ] - } - } - / result-type / 2: 0 / collected-artifacts / - } + / profile / 0: "tag:arm.com,2025/example-profile", + / query / 1: { + / rim-id selector / 3: [ + [ / corim / 2, / CoRIM id / "corim-acme-gizmo-1.0.0" ], + [ / corim / 2, / CoRIM id / "corim-acme-gizmo-1.2.0" ], + [ / comid / 0, / CoMID id / "d7bd6c2c-4844-48e4-a794-eeafdff128df" ] + ] + } } ``` #### Response + ``` HTTP/1.1 204 No Content -``` +``` \ No newline at end of file diff --git a/api/endorsement-provisioning/endorsement-provisioning.yaml b/api/endorsement-provisioning/endorsement-provisioning.yaml index b0fa844..e57f2a7 100644 --- a/api/endorsement-provisioning/endorsement-provisioning.yaml +++ b/api/endorsement-provisioning/endorsement-provisioning.yaml @@ -2,7 +2,7 @@ openapi: '3.0.0' info: title: Attestation endorsement provisioning and management - description: API to provision and manage endorsements. For further details, see datatracker.ietf.org/doc/draft-birkholz-rats-corim + description: API to provision and manage endorsements. For further details, see datatracker.ietf.org/doc/draft-ietf-rats-corim/ version: '1.0.0alpha' servers: - url: 'https://veraison.example/endorsement-provisioning/v1' @@ -68,40 +68,23 @@ paths: $ref: './schemas/components.yaml#/components/responses/Error' /activate: post: - summary: Activate triples using CoMID or CoRIM IDs or CoSERV queries. + summary: Activate triples matching an endorsement lifecycle mgmt (ELM) query description: > - Activate triples using CoRIM/CoMID IDs or using CoSERV queries. - All the triples from the provided list of IDs or the triples - matching the CoSERV query environment are activated. If any of - the supplied IDs are not present or if there are no triples matching - the CoSERV query environment in the database, error is returned. - operationId: activateEndorsementsUsingIDs + Activates triples selected by a CBOR-encoded ELM query. + Operation is idempotent and atomic i.e., if any requested + activation fails, no changes are applied. + operationId: activateEndorsements requestBody: required: true content: - application/vnd.veraison.endorsement-id-collection+json: + application/vnd.veraison.elm-v1+cbor: schema: - $ref: './schemas/components.yaml#/components/schemas/IDCollection' - application/coserv+cbor: - schema: - type: string - format: binary - description: > - A CoSERV query as per draft-ietf-rats-coserv + $ref: './schemas/components.yaml#/components/schemas/ELMQuery' responses: '204': - description: > - Activation successful. All the CoRIM/CoMID ids for the profile, - which were posted are present in the database and all the triples - from those CoRIM/CoRIMs have been converted to active state. If - a coserv was supplied in the request body, this response code - means: There was at least one triple matching the - selection. All the matching triples are now in active state. + description: Activation successful '404': - description: > - One or more IDs present in the collection were not found in the - store for the given profile. If a coserv was submitted, then - this response code means no matching triples were found. + description: No matching endorsements found content: application/problem+json: schema: @@ -109,43 +92,25 @@ paths: default: $ref: './schemas/components.yaml#/components/responses/Error' - /deactivate: post: - summary: Deactivate triples using CoMID or CoRIM IDs or CoSERV queries. + summary: Deactivate triples matching an ELM query description: > - Deactivate triples using CoRIM/CoMID IDs or using CoSERV queries. - All the triples from the provided list of IDs or the triples - matching the CoSERV query environment are deactivated. If any of - the supplied IDs are not present or if there are no triples matching - the CoSERV query environment in the database, error is returned. - operationId: deactivateEndorsementsUsingIDs + Deactivates triples selected by a CBOR-encoded ELM query. + Operation is idempotent and atomic i.e., if any requested + deactivation fails, no changes are applied. + operationId: deactivateEndorsements requestBody: required: true content: - application/vnd.veraison.endorsement-id-collection+json: + application/vnd.veraison.elm-v1+cbor: schema: - $ref: './schemas/components.yaml#/components/schemas/IDCollection' - application/coserv+cbor: - schema: - type: string - format: binary - description: > - A CoSERV query as per draft-ietf-rats-coserv + $ref: './schemas/components.yaml#/components/schemas/ELMQuery' responses: '204': - description: > - Deactivation successful. All the CoRIM/CoMID ids for the profile, - which were posted are present in the database and all the triples - from those CoRIM/CoRIMs have been converted to inactive state. If - a coserv was supplied in the request body, this response code - means: There was at least one triple matching the - selection. All the matching triples are now in inactive state. + description: Deactivation successful '404': - description: > - One or more IDs present in the collection were not found in the - store for the given profile. If a coserv was submitted, then - this response code means no matching triples were found. + description: No matching endorsements found content: application/problem+json: schema: diff --git a/api/endorsement-provisioning/schemas/components.yaml b/api/endorsement-provisioning/schemas/components.yaml index 25f12b1..059ebbd 100644 --- a/api/endorsement-provisioning/schemas/components.yaml +++ b/api/endorsement-provisioning/schemas/components.yaml @@ -27,27 +27,11 @@ components: description: > Optional field to provide more details about the failure cause when provisioning status is `failed` - IDCollection: - description: List of CoRIM or CoMID IDs. - type: object - required: - - profile - properties: - profile: - type: string - description: - CoRIM profile to which the CoRIM/CoMID ids belong to. - example: "tag:example.com,2025/example-profile" - corim-ids: - type: array - items: - type: string - description: List of CoRIM ids. - comid-ids: - type: array - items: - type: string - description: List of CoMID ids. + ELMQuery: + type: string + format: binary + description: > + CBOR-encoded endorsement lifecycle management query object using the CoSERV data model. Problem: required: @@ -97,4 +81,4 @@ components: content: application/problem+json: schema: - $ref: '#/components/schemas/Problem' + $ref: '#/components/schemas/Problem' \ No newline at end of file diff --git a/api/well-known/schemas/components.yaml b/api/well-known/schemas/components.yaml index e2cbefa..a633956 100644 --- a/api/well-known/schemas/components.yaml +++ b/api/well-known/schemas/components.yaml @@ -11,6 +11,10 @@ components: $ref: '#/components/schemas/PublicKey' description: Public key and algorithm to be used to verify the Attestation Result + activate-on-submit: + type: boolean + description: > + Activate endorsements on submission media-types: type: array items: