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