Establishing New Connections
Accept connection invitations, establish new peer connections, and manage pending connections.
In Decentralized Identity, establishing an end-to-end encrypted communication channels with a peer is an essential step before receiving or proving credentials. As such, the agent's ConnectionExchangeModule
provides all functionality needed to establish those connections with peers, and manage pending connections.
The functionality of the ConnectionExchangeModule
is accessed via the agent
's fields: agent.connections.exchange
. The functionality provided is described below.
Receive a Connection Invitation
A ConnectionExchange
, representing a pending connection, will be created by the agent once a connection invitation is received. To have the agent 'receive' an invitation message, this can be achieved in multiple ways. An invitation JSON payload message can be pre-processed and passed to the agent via the receiveMessage
API. Or, if the invitation is in its URL form (as it typically is when scanned from a QR Code), our URL Message Source can be used to process and receive that payload.
After an invitation is received by the agent, a ConnectionExchange
is created in the agent's wallet and can be accessed and used by the other APIs mentioned below. If the agent is subscribed to agent events, a new ConnectionExchange
will invoke a connection update event.
A ConnectionExchange
created as a result of receiving an invitation will have a role of INVITEE
.
Create a Connection Invitation
Alternatively, the Edge Agent can create connection invitations to be received by other agents. The module's createInvitation
API can be used to create connection invitations. This API takes a configuration, which has variants depending on the format of the invitation which should be created.
After calling the createInvitation
API, a CreatedInvitation
data structure will be returned, which contains the created invitation URL encoding, and the newly created ConnectionExchange
in the INVITATION
state. The ID of this ConnectionExchange
object can be used to track updates in it's state (e.g. an incoming connection request from a peer who receives the invitation).
A ConnectionExchange
created as a result of creating an invitation will have a role of INVITER
.
Creating AIP1 Connection Invitations
To create a pairwise single-use Aries Connection Invitation (RFC 0160), the createInvitation
should be used with the "legacy pairwise" variant of the CreateInvitationConfiguration
input configuration. This configuration takes the following input:
A
Routing
object, which is an item that the agent will use to inform the peer about how this agent should be contacted. This object notably includes aserviceEndpoint
(a HTTP endpoint where the peer should send DIDComm messages to), and an optional list ofroutingVerkeys
, which (if using a mediator) describes what layers of encryption the peer should wrap their messages in. If the agent is being used with the Sudo DI Relay, then a relay postbox can be used to create aRouting
for thatPostbox
(see below). If a custom message source is being used,Routing
will need to be manually constructed.overrideLabel
- a connection label which the inviter should present to the peer as a nickname for themself. If this input is provided, it will override the globally configured label.overrideBaseUrl
- the base URL for the encoded invitation URL (see RFC 0160). If this input is provided, it will override the globally configured invitation base URL.
Creating AIP2 Out of Band Invitation
Coming soon...
Accepting a Connection
Once a connection invitation is received (INVITATION
state in the INVITEE
role), or a connection request is received in response to a connection created by the Edge Agent (REQUEST
state in the INVITER
role) the agent can "accept" that connection. This will begin the next steps of the Aries protocol to establish an end-to-end encrypted channel with that peer.
Note that after calling the acceptConnection
API as an invitee, the connection is not fully established immediately, further messages between the peer and agent are sent in the background. The status updates of the establishment process can be tracked via agent events.
The acceptConnection
requires the following;
A
connectionExchangeId
- ID of theConnectionExchange
to accept,A
Routing
object, which is an item that the agent will use to inform the peer about how this agent should be contacted. This object notably includes aserviceEndpoint
(a HTTP endpoint where the peer should send DIDComm messages to), and an optional list ofroutingVerkeys
, which (if using a mediator) describes what layers of encryption the peer should wrap their messages in. If the agent is being used with the Sudo DI Relay, then a relay postbox can be used to create aRouting
for thatPostbox
(see below). If a custom message source is being used,Routing
will need to be manually constructed.A
ConnectionConfiguration
object, containing configuration details about specific configurations for this connection. Including how the agent should present itself to the peer. Any provided configuration here will override the global setting.
Creating a Connection Route from the Sudo Relay SDK
When integrating with the Sudo Relay SDK (i.e. via the relay message source), the Routing
for the acceptConnection
API can be easily created with the routingFromPostbox
helper API on the relay message source.
Please refer to the Sudo Relay SDK documentation for more information about creating Postboxes and more.
To avoid any chance of peers correlating different connections to a specific relay endpoint, it is recommended that a new Postbox
(and therefore new Postbox.serviceEndpoint
and corresponding Routing
) is created per connection.
Get a Pending Connection by ID
As mentioned above, a pending connection is represented by ConnectionExchange
objects. To retrieve the current state of a specific ConnectionExchange
in the agent's wallet, the getById
API can be used. If a connection exchange cannot be found by the given ID, then null
is returned:
Delete a Pending Connection by ID
Similarly, a ConnectionExchange
in the wallet can be easily deleted via the deleteById
API:
Updating the Metadata of a Pending Connection
ConnectionExchange
objects contain some metadata that can be controlled by SDK consumers, allowing custom information to be attached to each ConnectionExchange
, and allowing custom listing functionality to be leveraged.
Each ConnectionExchange
contains a list of RecordTag
(ConnectionExchange.tags
) attached to it, where a RecordTag
is simply a name-value pair stored with the record. By default, some tags are attached to a new ConnectionExchange
, this includes:
tag-name:
~started_timestamp
tag-value: The UNIX epoch seconds which this connection began establishment
The tags on a ConnectionExchange
can be replaced or updated by using the updateConnectionExchange
API, and providing a new set to update. This will replace whatever the current set of tags is:
Like most data in the wallet, RecordTag
will be stored encrypted. Unless, the tag name is prefixed with ~
, then the tag value will be stored unencrypted. Storing a tag value as unencrypted will allow some additional listing queries to be performed (see below).
Listing Pending Connections
To list all pending connections in the agent's wallet, the listAll
API can be used:
Filtered Listing
More complicated ConnectionExchange
list queries can also be achieved by utilizing the ListConnectionExchangeFilters
.
These filters allow for the list of ConnectionExchange
to be filtered by their state
, tags
, or both together.
Filtering by state
can be achieved as follows:
To filter by tags
applied to the ConnectionExchange
(i.e. applied via the update API), the tagFilter
field of ListConnectionExchangeFilters
should be used. This field takes a String
in compliance with a Wallet Query Language (WQL) Query.
Continuing from the example in the Update section:
Last updated