diff --git a/api/endorsement-provisioning/README.md b/api/endorsement-provisioning/README.md index 01e7f49..1a5522e 100644 --- a/api/endorsement-provisioning/README.md +++ b/api/endorsement-provisioning/README.md @@ -132,3 +132,88 @@ format is CoRIM. "expiry": "2030-10-12T07:20:50.52Z" } ``` + +# Endorsement Lifecycle Management (ELM) Interface + +This interface can be used for activating/deactivating endorsements provisioned +to the verifier. It uses the 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. + +## Query Format + +Following is the CDDL format for an ELM query: +``` +elm-query = { + ( environment-query // rim-query ) +} + +environment-query = ( + &(profile: 0) => coserv.profile + &(artifact-type: 1) => coserv.artifact-type + &(environment-selector: 2) => coserv.environment-selector-map +) + +rim-query = ( + &(rim-selector: 3) => [ + coserv.rim-selector-id ] +) +``` + +## Examples + +### Deactivate keys +Use the `environment-query` variant to deactivate two keys by `instance-id`. + +#### Request + +```http +POST /endorsement-provisioning/v1/deactivate +Host: veraison.example +Content-Type: application/vnd.veraison.elm-v1+cbor + +-- body in EDN + +{ + / profile / 0: "tag:arm.com,2025/example-profile", + / artifact-type / 1: 1, / trust-anchors / + / environment-selector / 2: { + / instance / 1: [ + [ 550( h'01 ...' ) ], + [ 550( h'01 ...' ) ] + ] + } +} +``` + +#### Response + +```http +HTTP/1.1 204 No Content +``` + +### Activate RIMs +Use the `rim-query` variant to activate two CoRIMs and one CoMID. + +#### Request + +```http +POST /endorsement-provisioning/v1/activate +Host: veraison.example +Content-Type: application/vnd.veraison.elm-v1+cbor + +-- body in EDN + +{ + / 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 +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 4e0e9eb..9b64708 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-ietf-rats-corim/ version: '1.0.0alpha' servers: - url: 'https://veraison.example/endorsement-provisioning/v1' @@ -66,6 +66,57 @@ paths: $ref: './schemas/components.yaml#/components/schemas/SessionResource' default: $ref: './schemas/components.yaml#/components/responses/Error' + /activate: + post: + summary: Activate triples matching an endorsement lifecycle mgmt (ELM) query + description: > + 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.elm-v1+cbor: + schema: + $ref: './schemas/components.yaml#/components/schemas/ELMQuery' + responses: + '204': + description: Activation successful + '404': + description: No matching endorsements found + content: + application/concise-problem-details+cbor: + schema: + $ref: './schemas/components.yaml#/components/schemas/ConciseProblem' + default: + $ref: './schemas/components.yaml#/components/responses/ConciseError' + + /deactivate: + post: + summary: Deactivate triples matching an ELM query + description: > + 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.elm-v1+cbor: + schema: + $ref: './schemas/components.yaml#/components/schemas/ELMQuery' + responses: + '204': + description: Deactivation successful + '404': + description: No matching endorsements found + content: + application/concise-problem-details+cbor: + schema: + $ref: './schemas/components.yaml#/components/schemas/ConciseProblem' + default: + $ref: './schemas/components.yaml#/components/responses/ConciseError' components: parameters: SessionID: diff --git a/api/endorsement-provisioning/schemas/components.yaml b/api/endorsement-provisioning/schemas/components.yaml index e549901..48911dd 100644 --- a/api/endorsement-provisioning/schemas/components.yaml +++ b/api/endorsement-provisioning/schemas/components.yaml @@ -26,6 +26,13 @@ components: type: string description: > Optional field to provide more details about the failure cause when provisioning status is `failed` + + ELMQuery: + type: string + format: binary + description: > + CBOR-encoded endorsement lifecycle management query object using the CoSERV data model. + Problem: required: - title @@ -67,6 +74,32 @@ components: the problem. It may or may not yield further information if dereferenced. example: https://veraison.example/v1/problems/404 + + ConciseProblem: + required: + - title + properties: + title: + type: string + description: > + A short, human-readable summary of the problem type. It SHOULD NOT + change from occurrence to occurrence of the problem, except for + purposes of localization (e.g., using proactive content + negotiation; see [RFC7231], Section 3.4). + example: Not Found + detail: + type: string + description: > + A human-readable explanation specific to this occurrence + of the problem. + example: no active session could be located at the requested URL + additionalProperties: true + description: > + Problem Details object encoded as CBOR and carried in the + application/concise-problem-details+cbor media type as defined + by Appendix B of RFC 9290. + See: rfc-editor.org/rfc/rfc9290#name-basic-problem-details + responses: Error: description: > @@ -75,3 +108,10 @@ components: application/problem+json: schema: $ref: '#/components/schemas/Problem' + ConciseError: + description: > + Unexpected error + content: + application/concise-problem-details+cbor: + schema: + $ref: '#/components/schemas/ConciseProblem' \ 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: