Skip to content

docs: endorsement lifecycle management API #74

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

Open
shefali-kamal wants to merge 2 commits into
base: main
Choose a base branch
from
+159 −3
Open

docs: endorsement lifecycle management API #74

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
57a2445
docs: endorsement lifecycle mgmt. API
atulfj Apr 14, 2026
3c1823e
feat: use coserv data model for activation/deactivation
atulfj Apr 23, 2026
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
94 changes: 94 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,97 @@ 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 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.

## Query Format

Following is the CDDL format for an ELM query:
```
elm-query = {
&(profile: 0) => coserv.profile
Copy link
Copy Markdown
Contributor

@thomas-fossati thomas-fossati May 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The profile does not belong in the rim query. I think it makes more sense to move it into the environment query.

Copy link
Copy Markdown

@atulfj atulfj May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used this diagnostic notation as a reference: rv-rim-query.diag, where the profile is included in the rim query. I'm not sure why it makes sense there but not here.
Slightly on the same topic, I would like to confirm if it's okay for the ELM query to diverge from the CoSERV data model beyond the fields that it imports? For example, I have removed coserv.result-type from the query because it is not useful here. Removing the profile from the rim query would be a step in the same direction.

Copy link
Copy Markdown
Contributor

@thomas-fossati thomas-fossati May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I used this diagnostic notation as a reference: rv-rim-query.diag, where the profile is included in the rim query. I'm not sure why it makes sense there but not here.

here, we are not constrained by the wrapping choices made by coserv, we have a bit more leeway to rearrange the objects in the most logical way for the use case… which segways into:

Slightly on the same topic, I would like to confirm if it's okay for the ELM query to diverge from the CoSERV data model beyond the fields that it imports?

Yes.

For example, I have removed coserv.result-type from the query because it is not useful here. Removing the profile from the rim query would be a step in the same direction.

Yes.

Copy link
Copy Markdown
Author

@shefali-kamal shefali-kamal May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI: @thomas-fossati so then because we have can diverge from the CoSERV data model please note in implementation we might have to write new structs and probably modify current coserv code so that these fields can be made optional.

&(query: 1) => query
}

query = {
( environment-query // rim-query )
}

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

### Deactivate keys
Use the `environment-query` variant to deactivate two keys by `instance-id`.

#### Request

```
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",
/ query / 1: {
/ artifact-type / 0: 1 / trust-anchors /
/ environment-selector / 1: {
/ instance / 1: [
[ 550( h'01 ...' ) ],
[ 550( h'01 ...' ) ]
]
},
}
}
```

#### Response

```
HTTP/1.1 204 No Content
```

### 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/vnd.veraison.elm-v1+cbor

-- body in EDN

{
/ 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
```
55 changes: 53 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-ietf-rats-corim/
version: '1.0.0alpha'
servers:
- url: 'https://veraison.example/endorsement-provisioning/v1'
Expand Down Expand Up @@ -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/problem+json:
schema:
$ref: './schemas/components.yaml#/components/schemas/Problem'
default:
$ref: './schemas/components.yaml#/components/responses/Error'

/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/problem+json:
schema:
$ref: './schemas/components.yaml#/components/schemas/Problem'
default:
$ref: './schemas/components.yaml#/components/responses/Error'
components:
parameters:
SessionID:
Expand Down
9 changes: 8 additions & 1 deletion 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,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
Expand Down Expand Up @@ -74,4 +81,4 @@ components:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
$ref: '#/components/schemas/Problem'
4 changes: 4 additions & 0 deletions api/well-known/schemas/components.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading