Live Demo	Discord	Atala PRISM Website

CI	Project Stage	Commits since latest release

Mediator

A DID Comm v2 mediator
A service that receives messages for many agents at a single endpoint and stores them with privacy. A cloud-based agent that forwards messages to mobile devices.

graph LR
  A((Sender)) -- forward --> M((Mediator))
  M--pickup-->D((Reciever))

Loading

• CI automates builds and tests that push to the main branch for all PRs created.
• Scala Steward automates the creation of pull requests for libraries with updated dependencies, saving maintainers time and effort. It can also help keep libraries updated, improving their reliability and performance.

---

#identus-mediator on Discord:

For the fastest answers, join the #identus-mediator channel in the official Atala Discord and ask your questions, or chat with other Atala developers and pioneers!

More documentation:

• LICENSE - Apache License, Version 2.0
• Mediation Flows - Examples of mediation flows
• Mediator Purpose
• Protocols Supported
  • Mediator Protocol State and Flow
• Pre-reqs
• Getting started
  • Docker only
• Configuring the mediator
  • Mediator identity
  • Mediator storage
    • Mediator-Storage-In-cloud
• Mediator Deployment
• Mediator Test suite
• Mediator Error Handling
• Mediator protocols state flow with problem reporting

Description

DID Comm v2 (Decentralized Identifiers Communication Version 2) is a protocol engineered for secure, private, and decentralized communications between various entities utilizing decentralized identifiers (DIDs). A DID Comm v2 Mediator functions as an intermediary in the communication process, streamlining the exchange of messages among the involved parties.

• Establishing Logical Connections - The Mediator empowers entities, which could be individuals or organizations, to forge secure connections amongst themselves. Each entity possesses a unique DID that acts as its identifier within the decentralized network.
• DID resolution - When an entity seeks to communicate with another, it resolves the recipient's DID to procure the information necessary to establish a connection. This resolution procedure entails retrieving the recipient's public key and correlated metadata from a decentralized identity infrastructure, which could be a blockchain or distributed ledger.
• Message encryption - The sender employs a double encryption technique for the message: initially for the ultimate receiver, and subsequently encapsulates the encrypted message within another encryption layer for the Mediator. This is achieved using the public keys of both the Mediator and the recipient obtained through the DID resolution process. Dual encryption ensures that only the intended recipient has the capacity to decrypt and access the message.

graph LR
  subgraph Encrypted message to Mediator
    subgraph Encrypted message to Reciever
    id1[[The plaintext message]]
    end
  end

Loading

• Message routing - The sender transmits an encrypted message to the Mediator, which serves as a routing agent. In this role, the Mediator receives messages from the sender, decrypts one layer, and forwards them to the appropriate recipient based on the recipient's DID.

• Mediation process- The Mediator verifies the authenticity and integrity of the incoming message by checking the digital signature attached to it. This signature ensures that the message was indeed sent by the claimed sender and that it hasn't been tampered with during transmission.

• Message decryption - After verifying the message's authenticity, the Mediator decrypted one layer of the message using the mediator's private key, which is securely held by the mediator. Once decrypted, the next message becomes readable (the final plaintext intended for the final user it's still encrypted).

• Optional processing - The Mediator may perform additional processing on the message based on predefined rules or business logic. This could include applying filters, applying policies, or invoking external services.

• Message forwarding - If necessary, the Mediator can further forward the decrypted message to additional entities in the communication flow. This enables multi-party communication scenarios.

By acting as an intermediary, the DID Comm v2 Mediator helps facilitate secure and private communication between entities while leveraging the decentralized nature of DIDs and cryptographic techniques to ensure the authenticity, integrity, and confidentiality of the messages exchanged.

The mediator is especially useful when the edge entities are not always online, like the mobile paradigm. Usually, we can assume that the mediator is always online.

Protocols

• [DONE] BasicMessage 2.0 - https://didcomm.org/basicmessage/2.0
• [DONE] MediatorCoordination 2.0 - https://didcomm.org/mediator-coordination/2.0
• See link for the protocol specs
• [TODO] MediatorCoordination 3.0 - https://didcomm.org/mediator-coordination/3.0
• [DONE] Pickup 3 - https://didcomm.org/pickup/3.0
• [DONE] TrustPing 2.0 - https://didcomm.org/trust-ping/2.0/
• [DONE] Report Problem 2.0 https://didcomm.org/report-problem/2.0/

Pre-reqs

To build and run this mediator, locally you will need a few things:

• Install Docker
• Install SBT

Getting started

This DIDComm Mediator comprises two elements: a backend service and a database. The backend service is a JVM application, and the database used is MongoDB. The backend service is also a web service with a single-page application that will give the final user an invitation page

• Clone the repository

git clone [email protected]:hyperledger/identus-mediator.git

shell> cd atala-prism-mediator
shell> docker compose up mongo

In another shell from the project root directory atala-prism-mediator

shell> sbt
sbt> mediator/reStart

By default mediator will start on port 8080

You can open the http://localhost:8080/ URL in a web browser, and it will show a QR code that serves as an out-of-band invitation for the Mediator.

How to run mediator as docker image

Docker only

It is possible to run everything with a single command with Docker compose docker-compose.yml The latest stable image version is available in the Hyperledger Identus-Mediator repository. To build a docker image locally, run NODE_OPTIONS=--openssl-legacy-provider sbt docker:publishLocal.

shell> cd atala-prism-mediator
shell> NODE_OPTIONS=--openssl-legacy-provider sbt docker:publishLocal
shell> MEDIATOR_VERSION=$(sbt "print mediator/version" --error) docker compose up

Configure the Mediator

The default configuration is set up application.conf. So in order to configure the mediator for your needs. You can either change the default configuration or you can set up environment variables that overrides the defaults:

identity

KEY_AGREEMENT, KEY_AUTHENTICATION use JOSE (JSON Object Signing and Encryption) format, utilizing OKP (Octet Key Pair) type with base64url-safe encoded keys.

To set up the mediator identity:

How to generate mediator identity

• KEY_AGREEMENT_D - is the key agreement private key (MUST be a X25519 OKP key type).
• KEY_AGREEMENT_X - is the key agreement public key (MUST be a X25519 OKP key type).
• KEY_AUTHENTICATION_D - is the key authentication private key (MUST be an Ed25519 OKP key type).
• KEY_AUTHENTICATION_X - is the key authentication public key (MUST be an Ed25519 OKP key type).
• SERVICE_ENDPOINTS - is the list of endpoints of the mediator split by ';' where the mediator will listen to incoming DIDComm messages.

mediator-storage

To set up the mediator storage (MongoDB):

• MONGODB_PROTOCOL - is the protocol type used by Mongo.
• MONGODB_HOST - is the endpoint where the MongoDB will be listening.
• MONGODB_PORT - is the endpoint's port where the MongoDB will be listening.
• MONGODB_USER - is the username used by the Mediator service to connect to the database.
• MONGODB_PASSWORD - is the password used by the Mediator service to connect to the database.
• MONGODB_DB_NAME - is the name of the database used by the Mediator.

Mediator storage

• The messages collection contains two types of messages: Mediator and User.

1. Mediator Messages:
   • Any Message to interacts with the mediator. For example: messages for setting up mediation, requesting mediation, picking up messages from the mediator, or forward message to another agent through the mediator.
   • The messages stored in the collection are usable for debugging purposes, mediator functionality, and interactions with the mediator. Hence, after a predetermined period, deleting them is possible.
   • This message type Mediator can be set up to have a configurable Time-To-Live (TTL) value, after which they can expire.
   • This is how the TTL is configurable for the collection messages initdb.js
2. User Messages:

   • These are the actual messages, e.g. the Forward message from the mediator, containing a User message inside. This inside message gets stored as User deliverable to the user.

   • They do not have a TTL and will persist in the system until the user retrieves them using a pickup protocol and deletes them.

   • The mediator is responsible for storing and making these user messages available for delivery to the intended recipients. For existing users, please utilize the migration script migration_mediator_collection.js to migrate the collection.

   • For existing users, please utilize the migration script migration_mediator_collection.js to migrate the collection.

Run

The DIDComm Mediator comprises two elements: a backend service and a database. The backend service is a JVM application, and the database used is MongoDB. The backend service is also a web service with a single-page application that will give the final user an invitation page.

Run locally

Everything runs with a single Docker compose command: docker compose up. You can set up a specific version with MEDIATOR_VERSION like MEDIATOR_VERSION=0.9.2-SNAPSHOT docker-compose up.

Troubleshooting

If you see the compilation error

[error]   opensslErrorStack: [ 'error:03000086:digital envelope routines::initialization error' ],
[error]   library: 'digital envelope routines',
[error]   reason: 'unsupported',
[error]   code: 'ERR_OSSL_EVP_UNSUPPORTED'

You can try to run with NODE_OPTIONS=--openssl-legacy-provider to use the legacy provider.

MongoDB In the cloud

Use the Mongodb from the cloud like MongoDB Atlas. You will need to create the table and indexes before starting the backend service. See the file initdb.js.

Deploy

You can easily deploy the image everywhere. We recommend a minimum of 250 mb ram to run the mediator backend service.

mediator-tests

https://github.com/input-output-hk/didcomm-v2-mediator-test-suite https://input-output-hk.github.io/didcomm-v2-mediator-test-suite/Reports.html

---

LICENSE - Apache License, Version 2.0