The Present Proof Protocol allows:
- a Verifier to request a verifiable credential presentation from a Holder/Prover
- a Holder/Prover responds by presenting a cryptographic proof to the Verifier
The protocol provides endpoints for a Verifier to request new proof presentations from Holder/Provers and for a Holder/Prover to respond to the presentation request using a specific verifiable credential they own.
The present proof protocol has two roles:
- Verifier: A subject requesting a proof presentation by sending a request presentation message, then verifying the presentation.
- Holder/Prover: A subject that receives a proof presentation request, prepares a proof, and sends it to the verifier by sending a proof presentation message.
Before using the Proof Presentation protocol, the following conditions must be present:
- Holder/Prover and Verifier PRISM Agents must be up and running
- A connection must be established between the Holder/Prover and Verifier PRISM Agents (see Connections)
- The Holder/Prover should hold a verifiable credential (VC) received from an Issuer see Issue.
This protocol supports the presentation of verifiable claims between two Atala PRISM Agents, the Holder/Prover and the Verifier.
The protocol consists of the following main parts:
- The Verifier creates a new proof presentation request using the
/present-proof/presentations
endpoint. It includes the identifier of an existingconnection
between both parties,domain
, and achallenge
to protect from potential replay attacks. - The Holder/Prover receives the presentation request from the Verifier and can retrieve the list of existing requests using the
/present-proof/presentations
endpoint. - The Holder/Prover can then review and accept a specific request using the
/present-proof/presentations/{presentationId}
endpoint, providing the identifier of thecredential
record to use in the proof presentation. - The Verifier receives the proof presentation from the Holder/Prover and can accept it using the
/present-proof/presentations/{presentationId}
endpoint, specifyingpresentation-accept
as the action type.
Endpoint | Method | Description | Role |
---|---|---|---|
/present-proof/presentations |
POST | Creates and sends a new proof presentation request. | Verifier |
/present-proof/presentations |
GET | Retrieves the collection of all the existing presentation proof records - sent or received. | Verifier, Holder/Prover |
/present-proof/presentations/{id} |
GET | Retrieves a specific presentation proof record by id . |
Verifier, Holder/Prover |
/present-proof/presentations/{id} |
PATCH | Updates an existing presentation proof record to, e.g., accept the request on the Holder/Prover side or accept the presentation on the Verifier side. | Verifier, Holder/Prover |
:::info For more detailed information, please, check the full PRISM Agent API. :::
This section describes the interactions available to the Verifier with the PRISM Agent.
The Verifier needs to create a proof presentation request to start the process.
To do this, he makes a POST
request to the /present-proof/presentations
endpoint with a JSON payload that includes the following information:
connectionId
: This field represents the unique identifier of an existing connection between the verifier and the Holder/prover. It is for exchanging messages related to the protocol flow execution.challenge
anddomain
: The Verifier provides the random seed challenge and operational domain, and the Holder/Prover must sign the generated proof to protect from replay attacks.
curl -X 'POST' 'http://localhost:8070/prism-agent/present-proof/presentations' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H "apiKey: $API_KEY" \
-d '{
"connectionId": "872ddfa9-4115-46c2-8a1b-22c24c7431d7",
"proofs":[],
"options": {
"challenge": "11c91493-01b3-4c4d-ac36-b336bab5bddf",
"domain": "https://prism-verifier.com"
}
}'
Upon execution, a new presentation request record gets created with an initial state of RequestPending
. The Verifier PRISM Agent will send the presentation request message to the PRISM Agent of the Holder/Prover through the specified DIDComm connection. The record state then is updated to RequestSent
.
The Verifier can retrieve the list of presentation records by making a GET
request to the /present-proof/presentations
endpoint:
curl -X 'GET' 'http://localhost:8070/prism-agent/present-proof/presentations' \
-H 'accept: application/json' \
-H "apiKey: $API_KEY"
Once the Holder/Prover has received a proof presentation request, he can accept it using an appropriate verifiable credential. The PRISM Agent of the Verifier will receive that proof and verify it. Upon successful verification, the presentation record state gets updated to PresentationVerified
.
The Verifier can then explicitly accept the specific verified proof presentation to change the record state to PresentationAccepted
by making a PATCH
request to the /present-proof/presentations/{id}
endpoint:
curl -X 'PATCH' 'http://localhost:8070/prism-agent/present-proof/presentations/{PRESENTATION_ID}' \
-H 'Content-Type: application/json' \
-H "apiKey: $API_KEY" \
-d '{
"action": "presentation-accept"
}'
---
title: Verifier Flow
---
stateDiagram-v2
[*] --> RequestPending: new presentation request created by the Verifier
RequestPending --> RequestSent: presentation request sent to the Holder/Prover PRISM Agent
RequestSent --> PresentationReceived: presentation proof received from the Holder/Prover
PresentationReceived --> PresentationVerified: presentation proof verified by the Verifier PRISM Agent
PresentationVerified --> PresentationAccepted: verified presentation proof explicitly accepted by the Verifier
This section describes the interactions available to the Holder/Prover with his PRISM Agent.
The Holder/Prover can retrieve the list of presentation requests received by its PRISM Agent from different Verifiers making a GET
request to the /present-proof/presentations
endpoint:
curl -X 'GET' 'http://localhost:8090/prism-agent/present-proof/presentations' \
-H 'accept: application/json' \
-H "apiKey: $API_KEY"
The Holder/Prover can then accept a specific request, generate the proof, and send it to the Verifier PRISM Agent by making a PATCH
request to the /present-proof/presentations/{id}
endpoint:
curl -X 'PATCH' 'http://localhost:8090/prism-agent/present-proof/presentations/{PRESENTATION_ID}' \
-H 'Content-Type: application/json' \
-H "apiKey: $API_KEY" \
-d '{
"action": "request-accept",
"proofId": ["{CRED_RECORD_ID}"]
}'
The Holder/Prover will have to provide the following information:
presentationId
: The unique identifier of the presentation record to accept.proofId
: The unique identifier of the verifiable credential record to use as proof.
The record state is updated to PresentationPending
and processed by the Holder/Prover PRISM Agent. The agent will automatically generate the proof presentation, change the state to PresentationGenerated
, and will eventually send it to the Verifier Agent, and change the state to PresentationSent
.
---
title: Holder/Prover Flow
---
stateDiagram-v2
[*] --> RequestReceived: presentation request received by the PRISM Agent
RequestReceived --> PresentationPending: request accepted by the Holder/Prover
PresentationPending --> PresentationGenerated: presentation proof generated by the PRISM Agent
PresentationGenerated --> PresentationSent: generated proof sent to the Verifier PRISM Agent
The following diagram shows the end-to-end flow for a verifier to request and verify a proof presentation from a Holder/prover.