Skip to content

docs: endorsement lifecycle mgmt. API #73

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
shefali-kamal wants to merge 1 commit into from
+240 −2
Closed

docs: endorsement lifecycle mgmt. API #73

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 129 additions & 0 deletions api/endorsement-provisioning/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
90 changes: 88 additions & 2 deletions api/endorsement-provisioning/endorsement-provisioning.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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'
Expand Down Expand Up @@ -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:
Expand Down
23 changes: 23 additions & 0 deletions api/endorsement-provisioning/schemas/components.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading