Note: I started from Stephen's work, then adapted it to DIDComm v2 and suggest some simplifications.
The PEx effort is focused on the process of a verifier sending a request for a presentation message to a prover, and the prover responding with a presentation that (crytopgraphically at least) satisfies the verifier's request. The request is a DIF Presentation Exchange presentation definition, and the response is a DIF Presentation Exchange presentation submission containing one or more verifiable presentations. Those are the only two messages allowed in the flow.
The WACI protocol specification's Request/Share section describes how that exchange is accomplished using that protocol with a challenge token (the request) and a callback to an HTTP endpoint for the response.
Within the set of protocols that make up Aries Interop Profile (AIP) 2.0 are two messages (Out of Band and Present Proof V2) that implement this same exchange on top of a DIDComm v1 connection using DIDComm v2 message envelopes. This document details the flow, including both the messages that are sent, a summary of the internal Aries agent processing that is occuring and the callouts to the business code (in Aries terms, the "controller" for the verfier and the prover). The internal processing notes are included to provide visibility into the message and protocol handling in the Aries frameworks to simplify the business processing layer. All of the cryptographic processing, identifier resolution, and message and protocol handling is handled by the Aries framework, and the business layer deals with send requests via an HTTP API to, and receiving events from, an Aries framework.
An Aries AIP 1.0 Connection-less presentation begins with a verifier creating an "out-of-band" invitiation message to be given to one or more provers. The invitiation is of the form that the specific presentation request (from Aries RFC 0454 Present Proof V2) in a message to the invitee is included (as an attachment or link to an attachment) in the invitation and the DIDComm service block to which the response is to be sent is either resolvable (from a DID) or inline in the invitation. The presentation request message itself includes an attachment that provides the details of the presentation requested based on the desired verifiable credentials format(s) (e.g. Indy and/or JSON-LD and/or BBS+).
The invitation may be created specifically for one invitee or to be shared with many invitees, perhaps by posting it in a public place. The invitation message is made available to the wallet via some "out-of-band" communication channel, a URL, a shortened-URL, a QR code of the URL/shortened-URL, etc.
The prover's wallet (somehow) receives the invitation, extracts/resolves the attached "Request Presentation" message and processes it. That involves searching the wallet secure storage to find the credentials that satisfy the request. The wallet might also check to see if any of the candidate credentials have been revoked. A user interface opens to offer the Prover (e.g. the person) the opportunity to review the submission, make any decisions about the credentials to share, and if the presentation should be sent to the verifier. "Decisions" in this case would be needed if the automated credential search determined more than one way to satisfy the request. The Prover adjusts as needed the response, and agrees to deliver the presentation. Again, an attachment to the message contains the presentation in a format that satisifies the presentation request.
The prover wallet uses the DIDComm information in (or resolved from) the invitation to prepare and send the message to the verifier. That includes at least the encryption key(s) to use for preparing the message and envelope(s), and a physical endpoint to which the message is to be delivered. The id field from the invitation is used as the parent thread ID (pthid) for the response message so that the verifier has some context for processing the message.
The verifier receives the response and uses the pthid to associate the response with the invitation to which it is related, and passes the message and context to a message handler. The presentation is processed and the verifiable presentation(s) is/are verified.
Since no DIDComm connection is established between the prover and verifier, a response from the verifier cannot be sent back to the prover. As such, the verifier's action following the verification is communicated in some other way – for example, as a message to a person monitoring the verifications at a point of entry, who can allow the Prover to continue or not.
DIDs can by any method that supports the required key types and a service block of the following format:
"service": [{
"id": "#someid",
"type": "didcommmessaging",
"serviceEndpoint": "https://example.com/endpoint",
"routingKeys": ["did:example:somemediator#somekey"]
}]
If ledger reliance is an issue, Peer DIDs (particularly method 2) may be used.
An out of band invitation is created by the verifier that includes a presentation request message. The layers of this message are defined in this section.
{
"type": "https://didcomm.org/out-of-band/2.0/invitation",
"id": "<id used for context as pthid>",
"body": {
"goal_code": "streamlined-vp",
"accept": ["didcomm/v2"],
"services": ["did:example:verifier"]
}
}
streamlined-vp signals to the Prover what is desired.services array are DIDs. Peer DIDs may be used to avoid the need of recording anything on a ledger.Note: For the purpose of the streamlined flow, a maximum of 1 mediator will be used in the service block.
Upon receipt (scanning) of this message, the Prover knows that the Verifier desires a credential. The actual credential request is large, and so retrieved as part of the flow.
The invitation must be conveyed (somehow) to the Prover. Often this is done by converting the invitation into an HTTP URL, possibly shortened, and then into a QR code for display or printing. The encoding into URL and QR code is defined here in Aries RFC 0434 Out-of-Band. In the same RFC, the URL shortening is formalized here.
Notes:
didcomm protocol has been used to have the mobile OS launch a wallet to handle the link. #helpwanted!!The prover receives the invitation message and processes it. Generally, an Aries framework will have a message dispatcher to handle the common elements of processing a message.
request-presentation message to the Present Proof "request-presentation" message handler.In processing the invitation, the out-of-band handler, a connection object would be created for holding the verifier's DIDComm invitation. As needed, the services DID would be resolved, and the DIDComm service block persisted, with the ID for the connection included with protocol state information passed to the request-presentation message handler.
prover reaches out to verifier to see what they want, and receive nonce info {<–s/ nonce info /challenge for signing a VP/? __jc}.
{
"type": "https://didcomm.org/present-proof/3.0/propose-presentation",
"id": "<message unique id>",
"pthid": "<id present in invitation>",
"from": "did:example:prover",
"to": "did:example:verifier"
}
The verifier can tell which link or QR code this came from by correlating the pthid of this message with the id of the invitation message.
The propose-presentation message often contains details about what the prover thinks they should present, but it can also be blank to indicate just that they want to start that conversation
verifier returns what the presentation defintion they want.
{
"type": "https://didcomm.org/present-proof/3.0/request-presentation",
"id": "0ac534c8-98ed-4fe3-8a41-3600775e1e92",
"from": "did:example:verifier",
"to": "did:example:prover",
"body": {},
"attachments": [
{
"id": "ed7d9b1f-9eed-4bde-b81c-3aa7485cf947",
"mime_type": "application/json",
"format": "dif/presentation-exchange/definitions@v1.0",
"data": {
"json": {
"dif": {
"options": {
"challenge": "3fa85f64-5717-4562-b3fc-2c963f66afa7",
"domain": "4jt78h47fh47"
},
"presentation_definition": {
}
}
}
}
}
]
}
Notes:
Within the "request-presentation" message handler, the message would be processed, as (more or less) follows.
presentation message is prepared and sent.A generalized Aries message handler may serialize and persist an in-flight protocol state object as part of sending the request to a User Interface for a response from the wallet owner. The response would be received back as an event to the general dispatcher, much as described in the section above when the invitation was received and processed.
The following is an example of a full presentation message. This JSON shows an Aries messsage, with an attachment of a presentation using DIF Presentation Exchange document with the an array of (one, in this example) Verifiable Presentations and a presentation_submission item that describes what is being provided.
{
"type": "https://didcomm.org/present-proof/3.0/presentation",
"id": "f1ca8245-ab2d-4d9c-8d7d-94bf310314ef",
"from": "did:example:verifier",
"to": "did:example:prover",
"body": {},
"attachments": [
{
"@id": "2a3f1c4c-623c-44e6-b159-179048c51260",
"mime-type": "application/ld+json",
"format": "dif/presentation-exchange/submission@v1.0",
"data": {
"@context": [
"https://www.w3.org/2018/credentials/v1"
],
"type": [
"VerifiablePresentation"
],
"verifiableCredential": [
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://w3id.org/citizenship/v1",
"https://w3id.org/security/bbs/v1"
],
"id": "https://issuer.oidp.uscis.gov/credentials/83627465",
"type": [
"PermanentResidentCard",
"VerifiableCredential"
],
"credentialSubject": {
"id": "did:sov:4QxzWk3ajdnEA37NdNU5Kt",
"type": [
"Person",
"PermanentResident"
],
"givenName": "JOHN"
},
"issuanceDate": "2010-01-01T19:53:24Z",
"issuer": "did:key:zUC72DsuZqSbiiLLydyssCW82PMjn25VNNXguv6irxuB4LNAu145PE9iG2qbYgzPuGTwhbSmDwmcTDu677VKH7w9PkcRxZPtGD2RgZ9ACQEPCs1bZyrk8RRDpuCTUr4F6ETeQQP",
"proof": {
"type": "BbsBlsSignatureProof2020",
"nonce": "W0HJw8OvyFonxWDnz1npXVn1u4JWqkVoS1493CDQFVVOChGKuVaxOzAahX7v5r6MzS0=",
"proofValue": "ABkBuAaPsfObokMu/zsmoRpoBhiQdpRNm3Q9dzm6Nj6wpnIfosYhkDHyIdkmC8D3YUFe6CvvkAvUauxu1jMpA2A1haPHu2D4/BqoNseCIEE6Fqmuy1BFkbdTYqC9g+KTx5tnPnvngG7RrYiMvHX9xcci8vmM6sMlZD6hJGpJoVVGgg0wHFP+IIQDi+B20T6QaJwSSMzWAAAAdIlPi49Usfp2/9ycjA9WFLhALC7G2R/vgUk/taRMRNDVIROXNzCIJuqAeZvoBX9xKAAAAAI0Obo9NqWhCCkJHEyaezmwnuZ52yKKPcHM6uISt2zrV17Mvc2nqLN+I1JjIHoTlNQ4F5WwBxxBmaCrrrhAtyDylje7JwQNQWoIVRUb3i7LFcg6ZYGG50Rap8FXHX7yO5ryGVUxjiPaz+qqE5njmYrzAAAAD3J10bdmab+ASYKM9RoJJ8YwAQmgsnfwuZv4GYm4xzaTV0FlTvqOzqc9Fa5zW0amz4r5ozvZY94mXksKQilUVFEQr4uUKH5dFlagmOjCelrlVGmMXOzEWkPzH7OH70GxET5e3qqf3pec3ny541jMj/8+8FwHwnTR4gdHDrweqZnBUQNblPY3cHxekXgE2H+xUTq0fZxGO0ghrVQE/prqka1DpiZpou3FwIYftP8ecLJ0k8DCCKcDlT6Y7hO0NW4tQz2KM72BnzOR+hdBoRI28uZKNv4OkI522LtaI2RYSnvWMBA/jXieR+wsUwxp9GOEo0/rJ0IVgwrEATdg+IDNp2McmZaVmF9BM2IScpzEpKbZlO3aY8NcCvfxkl6615JrLDqOBxLXX4RbKxIw22Fy4tFkjlyKRCilPvb0/vXRRnDaJhoQWmzEcsvMFtuJUSLNcX0Yktg9AC5JYPUqyPVMbV0qCtFWKAb4kwZRlJF4WBm5alvY37hLa/DTFymmwo7EsxlkNrHxjPyvM4OpzUA5DP1T9nETNGvwoYX7Ovl+na6ucZ1HF6MxE54EppLfFZHCulvU2OsSmsZ6XV7NCTJ4+QozNpvyqHS93oAiIabt20oRR6i9d4N8N0iRtB+ffNBV0Q==",
"verificationMethod": "did:key:zUC72DsuZqSbiiLLydyssCW82PMjn25VNNXguv6irxuB4LNAu145PE9iG2qbYgzPuGTwhbSmDwmcTDu677VKH7w9PkcRxZPtGD2RgZ9ACQEPCs1bZyrk8RRDpuCTUr4F6ETeQQP#zUC72DsuZqSbiiLLydyssCW82PMjn25VNNXguv6irxuB4LNAu145PE9iG2qbYgzPuGTwhbSmDwmcTDu677VKH7w9PkcRxZPtGD2RgZ9ACQEPCs1bZyrk8RRDpuCTUr4F6ETeQQP",
"proofPurpose": "assertionMethod",
"created": "2021-05-14T20:16:05.457334"
}
}
],
"presentation_submission": {
"id": "1d257c50-454f-4c96-a273-c5368e01fe63",
"definition_id": "32f54163-7166-48f1-93d8-ff217bdb0654",
"descriptor_map": [
{
"id": "citizenship_input_1",
"format": "ldp_vp",
"path": "$.verifiableCredential[0]"
}
]
},
"proof": {
"type": "Ed25519Signature2018",
"verificationMethod": "did:sov:4QxzWk3ajdnEA37NdNU5Kt#key-1",
"created": "2021-05-14T20:16:29.565377",
"proofPurpose": "authentication",
"challenge": "3fa85f64-5717-4562-b3fc-2c963f66afa7",
"jws": "eyJhbGciOiAiRWREU0EiLCAiYjY0IjogZmFsc2UsICJjcml0IjogWyJiNjQiXX0..7M9LwdJR1_SQayHIWVHF5eSSRhbVsrjQHKUrfRhRRrlbuKlggm8mm_4EI_kTPeBpalQWiGiyCb_0OWFPtn2wAQ"
}
}
}
]
}
Notes:
presentations~attach is an Aries RFC 0454 Present Proof V2 presentation message. Check the RFC for the details about the items in the JSON, optional fields and so on.presentations~attach is a standard Aries RFC 0017 Attachment, with the payload (the json item value) the presentation (see next bullet item). As with the invitation attachment, this attachment could be json, base64 or (extremely unlikely) links to HTTP(S) URLs.verifiable presentation in the document, a signature over the array of (one) presentations, and the presentation_submission that relates to the requested presentation_definition that shows how the request was satisfied. While this example is a very simple version of a Presentation Exchange, they can get significantly more complicated.The prepared presentation message is included in the protocol state object and passed to an outbound message dispatcher. The outbound message dispatcher takes the message, gets the required connection object, prepares and sends the message in the necessary DIDComm envelope(s). Once prepared the message would be sent to the requested endpoint over the requested transport protocol–as defined in the verifier's DIDComm service block.
The DIDComm envelope is prepared, encrypting and wrapping the payload (the presentation message) for the verifier. The DIDComm service block provided by the verifier is used to prepare the envelope(s).
@TelegramSam – can you add the JSON and notes in the style above.
The verifier receives the DIDcomm message and processes it. This is the same process with different data as described in the Receive Invitation section above.
pthid (parent thread ID) should match an invitation ID previously prepared by the verfier. That ID should provide sufficient state for the remainder of the flow.The "presentation" message handler would use the protocol state object to provide access to the presentation request data, and process the message to extract the DIF Presentation Exchange (PE) data. This includes verifying each of the verifiable presentations (as required) and verifying the PE proof. The verification statuses (true, false) and the presentation is then passed to the verifier business logic to act on the statues and claims data as needed.
Note that since there was no DIDComm connection established with the prover, the verifier has no way to back the result of the processing – success or failure.
-
Any changes
Be notified of any changes
-
Mention me
Be notified of mention me
-
Unsubscribe
Subscribe