DIDAuth Presentations
This page covers the handshake for DIDAuth Presenations
Last updated
This page covers the handshake for DIDAuth Presenations
Last updated
Verifiable presentations are directional interactions between two specific parties.
These interactions involve the following steps:
The presenter indicates an intention to make a presentation, invoking the receivers endpoint (1). The presentation receiver replies with a “challenge” which will be cryptographically included in the presentation, and optionally directions on which verifiable credentials are required (2). The presenter bundles the necessary (parts of) the Verifiable Credentials to be presented, creates a signed verifiable presentation (3), and submits the verifiable presentation to the presentation receiver (4). The presentation receiver accepts (or rejects) the inbound presentation (5), will typically want to verify its content (6), Both presenter and presentation receiver will also typically store the verifiable presentation (7) and (8) for future records.
Note!
The interacting parts of this flow marked in dotted red implements the Traceability Interoperability standard https://github.com/w3c-ccg/traceability-interop.
The following sections describes these steps in deeper technical details. The headline numbering refers to the above diagram. Being directional, there is an important difference here between being the presenter and being the presentation receiver; these roles are clearly marked at each section.
The presenter initiates the presentation procedure by indicating to the presentation receiver that she intents to make a presentation. This is done using the “/available” endpoint:
POST /api/organizations/{organizationId}/presentations/available
Note!
It is important to note here that the call is made by the presenter, but “pointing at” the
organizationIdof the presentation receiver.
Below is an example to illustrate usage of this endpoint:
The above call will return a response from the presentation receiver similar to this:
The nonce will be used shortly in producing the verifiable presentation.
The presenter must also take note of the types of verifiable credentials, which the presentation receiver requires for a given type of presentation. In the above example the empty array indicates that there are no such requirements, so in this case it is up to the presenter to decide on the relevant credentials to present.
Note! Platform features will be added, allowing the presentationReceiver rich control over presenter and credentials requirements.
Note! The nomenclature of these requests and response objects implements the Verifiable Presentation Request Specification standard (https://w3c-ccg.github.io/vp-request-spec).
Upon receiving the above intention to present response, the presenter can go ahead and prepare the verifiable presentation. This is done with the “/prove” endpoint:
POST /presentations/prove
An example of is provided below:
The presentation request includes a number of elements which the verifiable presentation will be based on. It also includes an “options” object, which the platform uses for the generating the verifiable presentation proof, including the nonce which was provided by the presentationReceiver.
The “/prove” call returns the verifiable presentation, which includes a proof element:
The presentation submission is completed by passing the above signed verifiable presentation directly to the “/submissions” endpoint:
POST /api/organizations/{receiverId}/presentations/submissions
Verifiable presentations are one-off interactions between the two interacting parties; the presenter’s verifiable presentation is tied to the specific session with the presentation receiver. It can be queried by calling the “/sent” endpoint:
GET /api/presentations/sent
The following describes necessary steps for the presentation receiver receive an inbound verifiable presentation. It also describes optional configuration which the presentation receiver can make to control access and content of presentations.
The presentation receiver can see inbound verifiable presentations by calling the “/shared-with-me” endpoint:
This returns an array of all past presentations, each wrapped with metadata about the sender, its id and the status of the presentations.
The presentation receiver may verify the inbound presentation anytime, for example as part of deciding whether or not to accept it. Verification is done with the “/presentations/verify” endpoint:
