Skip to content

DIDComm v2 Mediator Implementation

Jump to bottom
Lance edited this page Feb 7, 2022 · 2 revisions

DIDComm v2 Mediator Implementation (INITIAL DRAFT)

As a general principle, the Mediator implements the latest specifications and protocols from DIF and Aries Interoperability Profiles, in particular:

The initial implementation uses HTTPS transport with Transport Return Route, meaning that the mobile user sends messages to the mediator as HTTPS POST requests, and receives a message back from the mediator in the HTTPS response body.

Additionally, the Pickup Protocol is implemented so mobile users can retrieve pending messages from the mediator asynchronously. Future releases will implement a websocket transport with Live Mode capability that adds a better realtime communication when both parties are online.

Process Flow Overview

In the following process Alice(A) wants to invite Bob(B) to create a connection by exchanging DID (did:peer). Since A is a mobile user and can't provide a direct link to communicate, she will use a mediator(M) as a means to be reached out. B may or may not need a mediator, but if that is the case, the mediator can be the same (M) or another.

The process below includes as reference the @type of the message as defined in Aries protocols:

  1. Initially, A needs to connect with M, so M provides to A an out-of-band invitation in an URL or QR code stating a connection URL in serviceEndoint and a did:peer inrecipientKeys ("@type": "https://didcomm.org/out-of-band/%VER/invitation"). Note that this did:peer is a general invite DID used only for initial communication set up.
  2. A creates a dedicated did:peer to connect to M A.didpeer@A:M.
  3. A generates a request messsage ("@type": "https://didcomm.org/didexchange/1.0/request") providing her DID documment for key A.didpeer@A:M. The message is encrypted with M invitation keys and POSTed to the URL obteined in serviceEndpoint
  4. M creates a dedicated did:peer to connect to A M.didpeer@M:A
  5. M responds the received http POST message with a response message ("@type": "https://didcomm.org/didexchange/1.0/response") providing the DID documment for M.didpeer@M:A. Message is encrypted for A.didpeer@A:M
  6. To conlcude the communication setup, A sends a complete message to M ("@type": "https://didcomm.org/didexchange/1.0/complete"), that M responds with 200 success. This final message is still encrypted with M's invitation keys. Subsecuent communication will use M.didpeer@M:A and A.didpeer@A:M.
  7. Now A starts a mediation request by POSTing a mediate-request message ("@type": "https://didcomm.org/coordinate-mediation/1.0//mediate-request") to M, which is replied with a mediate-grant message("@type": "https://didcomm.org/coordinate-mediation/1.0//mediate-grant"). Messages are encrypted with A.didpeer@A:M and M.didpeer@M:A. The mediate-grant message provides the endpoint and routing-keys needed by B (TODO: check if routing-keys are per mediate-grant or per user)
  8. A creates a did:peer to invite B A.didpeer@Ainvite:B
  9. A updates the list of recipient keys in M by POSTing a keylist-update message to M ("@type": "https://didcomm.org/coordinate-mediation/1.0//keylist-update") including A.didpeer@Ainvite:B
  10. M responds the keylist-update with a keylist-update-response message("@type": "https://didcomm.org/coordinate-mediation/1.0//keylist-update-response")
  11. A creates an out-of-band inviation with mediator endpoint and routing-keys, and A.didpeer@A:B in recipientKeys ("@type": "https://didcomm.org/out-of-band/%VER/invitation"). B gets this message as a QR code or URL
  12. B creates a dedicated did:peer to communicate with A B.didpeer@B:A
  13. B creates a request messsage ("@type": "https://didcomm.org/didexchange/1.0/request") providing B.didpeer@B:A DID document. He may also needs to add a serviceEndpoint and/or routing-keys if using also a mediator. The message is encrypted with A.didpeer@Ainvite:B keys.
  14. B wraps the message in a Forward message ("type": "https://didcomm.org/routing/2.0/forward") and encrypts with M routing-keys
  15. B POST the message to M at endpoint defined in the out-of-band invitation
  16. M unpacks the forward message, inspects the to field, looks up keys in its DB and stores the message as pending delivery for A
  17. Asynchronously, A checks with M if there're pending messsages by POSTing to M a status-request ("@type": "https://didcomm.org/messagepickup/2.0/status-request") that is replied with the status message ("@type": "https://didcomm.org/messagepickup/2.0/status")
  18. If there're pending messages, A POST a delivery-request message to M ("@type": "https://didcomm.org/messagepickup/2.0/delivery-request") that is responded with the delivery message ("@type": "https://didcomm.org/messagepickup/2.0/delivery") that includes message from B.
  19. A finalizes the message pickup with a messages-received message ("@type": "https://didcomm.org/messagepickup/2.0/messages-received")
  20. After receiving the connection request from B, A generates a new dedicated did:peer to connect with B A.didpeer@A:B.
  21. A updates the list of recipient keys in M by POSTing a keylist-update message to M ("@type": "https://didcomm.org/coordinate-mediation/1.0//keylist-update") including A.didpeer@A:B and removingA.didpeer@Ainvite:B.
  22. A creates a response message ("@type": "https://didcomm.org/didexchange/1.0/response") including her DID documment with key A.didpeer@A:B, mediator's routing key, and mediator's endpoint in serviceEndpoint. Message is encrypted for B.didpeer@B:A
  23. A sends the message to B using B serviceEndpoint or routing-keys. That process may require a mediator as well, that can be same mediator or another.
  24. B sends the complete message to finalize communication setup and wrap it in a Forward message as before.
  25. A receives the complete message from the mediator by quering M for message pickup as before
  26. A and B are now ready to communicate

NOTE: all post message from A will have the decorator for Transports Return Route (TODO: check mediation_id)

Clone this wiki locally