DIDAuth Presentations

This page covers the handshake for DIDAuth Presenations

Verifiable presentations are directional interactions between two specific parties.

Overview

These interactions involve the following steps:

DID-Auth Verifiable Presentation Flow

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.

Directional Interactions

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.

1. Indicating Presentation Intent

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 /v1/organizations/{organizationId}/presentations/available

Note!

It is important to note here that the call is made by the presenter, but “pointing at” the organizationId of the presentation receiver.

Below is an example to illustrate usage of this endpoint:

curl --location --request POST 'https://staging.platform.transmute.industries/v1/organizations/5538c716-549e-4c98-93a0-948e5776744b/presentations/available' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer **Your token here**' \
 --data-raw '{
     "query": [
         {
             "type": "RequestQueryByFrame",
             "credentialQuery": [
                 {
                     "type": [
                         "VerifiableCredential",
                         "IntentToImport"
                     ],
                     "reason": "Steel Inc requesting import of a shipment of steel."
                 }
             ]
         }
     ]
 }'

2. Responding to Presentation Intent

The above call will return a response from the presentation receiver similar to this:

{
    "query": [
        {
            "type": "QueryByExample",
            "credentialQuery": {
                "reason": "e6212fac-2265-42d8-bd89-b6214e6be772 is requesting credentials, in response to RequestQueryByFrame",
                "example": {
                    "@context": [
                        "https://www.w3.org/2018/credentials/v1"
                    ],
                    "type": []
                }
            }
        }
    ],
    "challenge": "4cab30ec-51b7-4d0a-a5ab-6e5118e6e7e8",
    "domain": "e6212fac-2265-42d8-bd89-b6214e6be772"
}

The challenge and domain are the main attributes for the presenter to pick out of this; they 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).

3. Generating a Signed Verifiable Presentation

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:

curl --location --request POST 'https://staging.platform.transmute.industries/v1/organizations/934d0eb0-accd-4f0e-ba00-656841976275/presentations/prove' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer ** Your token here**' \
 --data-raw '{
   "presentation": {
     "@context": ["https://www.w3.org/2018/credentials/v1"],
     "type": ["VerifiablePresentation"],
     "verifiableCredential": [
       **List of included verifiable credentials here** 
     ]
   },
   "options": {
     "verificationMethod": null,
     "created": "2020-04-02T18:48:36Z",
     "proofPurpose": "assertionMethod",
     "challenge": "4cab30ec-51b7-4d0a-a5ab-6e5118e6e7e8",
     "domain": "e6212fac-2265-42d8-bd89-b6214e6be772"
   }
 }'

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 challenge and domain which was provided by the presentationReceiver.

The “/prove” call returns the verifiable presentation, which includes a proof element:

{
    "@context": [
        "https://www.w3.org/2018/credentials/v1"
    ],
    "type": [
        "VerifiablePresentation"
    ],
    "holder": "did:key:z6Mkpk9PZnvpvK3TUjPYpzJgewrNCxM36SsuWjrm42PFeXCT",
    "verifiableCredential": [
        **List of included verifiable credentials here**
    ],
    "proof": {
        "type": "Ed25519Signature2018",
        "created": "2021-07-05T21:10:23Z",
        "challenge": "4cab30ec-51b7-4d0a-a5ab-6e5118e6e7e8",
        "domain": "e6212fac-2265-42d8-bd89-b6214e6be772",
        "jws": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..DZ89gTqx4d5ILOMGgT4608qaJhcKhIExOiqSQxaZIKRTPfvd18o_j8rik3OQgS3xTG4YnHkAlcowpbxo5jR7BQ",
        "proofPurpose": "authentication",
        "verificationMethod": "did:key:z6Mkpk9PZnvpvK3TUjPYpzJgewrNCxM36SsuWjrm42PFeXCT#z6Mkpk9PZnvpvK3TUjPYpzJgewrNCxM36SsuWjrm42PFeXCT"
    }
}

4. Submitting the Verifiable Presentation

The presentation submission is completed by passing the above signed verifiable presentation directly to the “/submissions” endpoint:

POST /v1/organizations/{receiverId}/presentations/submissions

curl --location --request POST 'https://staging.platform.transmute.industries/v1/organizations/e6212fac-2265-42d8-bd89-b6214e6be772/presentations/submissions' \
 --header 'Content-Type: application/json' \
 --data-raw '
  **Verifiable presentation here, as shown above**
'

Storing Own Submmitted Presentations

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 presentations/sent

5. Receiving a Verifiable Presentation

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.

Listing Inbound Presentations

The presentation receiver can see inbound verifiable presentations by calling the “/shared-with-me” endpoint:

curl --location --request GET 'https://staging.platform.transmute.industries/v1/organizations/e6212fac-2265-42d8-bd89-b6214e6be772/presentations/received' \
 --header 'Authorization: Bearer **Your token here**'

This returns an array of all past presentions, each wrapped with metadata about the sender, its id and the status of the presentations. The status will always initially be “pending” as illustrated on the snippet below:

 [
    {
        "id": "https://staging.platform.transmute.industries/submissions/bc756a45-6010-41a5-ae43-d43df546e258",
        "receiver": {
            "id": "https://staging.platform.transmute.industries/organizations/e6212fac-2265-42d8-bd89-b6214e6be772",
            "type": "Organization",
            "name": "Steel Inc API Test Org"
        },
        "sender": {
            "id": "did:key:z6Mkpk9PZnvpvK3TUjPYpzJgewrNCxM36SsuWjrm42PFeXCT",
            "type": "Website",
            "name": "did:key:z6Mkpk9PZnvpvK3TUjPYpzJgewrNCxM36SsuWjrm42PFeXCT"
        },
        "type": "Submission",
        "status": "pending",
        "timestamp": 1625520735104,
        "verifiablePresentation": {
            ...
        }
    },
    ...
]

6. Verifying and Accepting 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:

curl --location --request POST 'https://staging.platform.transmute.industries/v1/organizations/e6212fac-2265-42d8-bd89-b6214e6be772/presentations/verify' \
--header 'Authorization: Bearer **Your token here**' \
--header 'Content-Type: application/json' \
--data-raw '{
  "verifiablePresentation": **Verifiable presentation here**,
  "options": {
    "challenge": "4cab30ec-51b7-4d0a-a5ab-6e5118e6e7e8",
    "domain": "e6212fac-2265-42d8-bd89-b6214e6be772",
    "checks": [
      "proof"
    ]
  }
}
'

Based on this and other decision control, the presentation receiver may ultimately decide to accept or reject the verifiable presentation. This is done with a PATCH call, referencing the submission id listed by “/shared-with-me” above:

PATCH /v1/organizations/receiverId/presentations/{submissionId}

The request payload on this call can be either "status": "accepted" or "status": "rejected". Below is an example:

curl --location --request PATCH 'https://staging.platform.transmute.industries/v1/organizations/e6212fac-2265-42d8-bd89-b6214e6be772/presentations/bc756a45-6010-41a5-ae43-d43df546e258' \
 --header 'Authorization: Bearer **Your token here**' \
 --header 'Content-Type: application/json' \
 --data-raw '{
   "status": "accepted"
 }'