In part 1 I gave an introduction to the terms used in the Self-Sovereign Identity space. In part 2 I explained the tools and command-line arguments for the development environment. In this part I’m going to set up two agents, and they are going to connect using the invite and request/response protocol. The first version of this blog post described how ACA-py agents can connect using the RFC0160 Connection Protocol. I did not use the Out-of-Band protocol as I did not see how that would add anything. In this blog post I will use the Out-of-Band protocol and RFC0023 DID Exchange because a first version of DID Exchange has been implemented in ACA-py v0.6.0.
The work on connecting two agents to create a connection and exchange messages is ongoing. This means that whatever I write here might be outdated tomorrow.
DID Exchange v1 and Out-of-Band messaging
Whenever two agents want to connect with each other, they do a connection-dance, a series of messages that go back and forth to establish a connection and exchange information. The first iteration of this connection protocol is described in HIPE-0031 and has been adopted into Aries RFC0160. When it became clear that communication between Indy agents required a separate form of standardization, the Indy RFCs were adopted into Aries RFCs. Aries RFC0160 has been implemented in ACA-py for quite some time now and works perfectly well for connecting two agents.
A next iteration of the protocols is nearing completion. Yes, plural, because RFC0160 will be split into Aries RFC0023, which describes DID Exchange v1, and Aries RFC0434 which describes Out-of-Band messaging.
ACA-py is currently adding support in v0.6.0 for DID Exchange which will allow for communication between ACA-py agents and other agents that implement it, for example github.com/hyperledger/aries-framework-go.
The DID Exchange protocol is used for communication using DIDComm between two agents to establish a connection. However, when a connection is made between two agents, how do they know where to find each other, and how do they communicate this with each other? To solve that problem, the Out-of-Band protocol has been made.
An agent can create an invitation for another agent to connect with it. The other agent receives the invitation, for example as a link in an email or by scanning a QR-code, and starts the connection-dance.
Basically, the /connections/create-invitation and /connections/receive-invitation endpoints have been replaced with the Out-of-Band endpoints /out-of-band/create-invitation and /out-of-band/receive-invitation. Similarly, the /connections/{conn_id}/accept-invitation and /connections/{conn_id}/accept-request endpoints have been replaced with the DID Exchange endpoints /didexchange/{conn_id}/accept-invitation and /didexchange/{conn_id}/accept-request. This makes that the other /connections endpoints are just there to manage connections.
Starting two ACA-py clients
Let’s say there are two clients: Alice and Bob. They are both going to start their ACA-py instances and connect.
To start an ACA-py client, you first need to have a DID. You can register a DID by going to your VON-network browser at localhost:9000 and enter a Wallet seed (for example your first name), and an alias (for example your full name). You can leave the DID field blank.
The value of Seed is required as command line argument --seed Laurence000000000000000000000000 when running your ACA-py instance. Because of this dependency (you need to have a DID before you can start ACA-py), the demo agents in ACA-py and the example agent in go-acapy-client will run aca-py for you in the background. They first do a call to localhost:9000/register and then use the values to start ACA-py.
During development, it is a good idea to randomize the wallet seed value when registering a DID, so you can start with a clean slate every run. The same goes for --wallet-name. When ACA-py starts it will check the DID in the wallet to see if it matches with the provided seed. If it doesn’t match it will give an error an exit:
1
aries_cloudagent.config.base.ConfigError: New seed provided which doesn't match the registered public did 6i7GFi2cDx524ZNfxmGWcp
You can override this behaviour with --replace-public-did, after which it will update the DID in the wallet with the DID that matches the provided seed. Another option is to randomize the wallet name.
With the release of ACA-py v0.6.0, the provisioning of a wallet has changed. In general, ACA-py has two main commands: start and provision. The provision command is there to separate the creation of wallets and the usage of wallets. In a production application, you do not want to create or overwrite a wallet by accident. Your wallet contains the keys for using a specific DID, and a DID is registered in an Indy blockchain for real money. That’s why there are separate steps. On the other hand, for development it is convenient to not have to do two separate steps. That’s why a new command-line parameter (--auto-provision) has been added that automatically provisions a wallet in case it does not exist.
It is required to have either handshake_protocols or attachments or both in the body. I have not managed to get any attachments example to work, so let’s stick to handshake_protocols.
The field use_public_did signifies that the public DID will be used in invites, more on that in the tip below.
Public vs non-public invites
A public invites contains a DID for other agents to connect with. For a public invite, the ledger needs to know at which endpoint an agent can be reached. This means that it requires a lookup in the ledger by the invited agent. A non-public invite does not use a public DID, instead it contains a service endpoint url, so the invited agent can connect to inviter directly.
alias is the name that Bob will give to this connection, so in this case Alice.
auto_accept the invitation can be automatically accepted, if you set this to false, then Bob needs to accept the invitation in next step.
If you run two ACA-py instances next to each other you can just copy and paste the invitation. In the real world the invitation of Alice will usually go to Bob either as a QR-code or as link.
3
Bob accepts the invitation
Use the /didexchange/{id}/accept-invitation endpoint. The {id} should be the connection_id from the response of /out-of-bounds/receive-invitation. You can also find the connection_id by using the /connections endpoint.
Again you can provide an alias, it’s still from Bob’s perspective, so it should be ‘Alice’. You can leave the my_endpoint query parameter empty, it will use the value of --endpoint.
4
Bob responds with a connection request
This happens automatically when Bob accepts the invitation. The request will directly go from Bob’s ACA-py instance to Alice’s ACA-py instance.
Even though Alice started this interaction by creating an invitation, it is actually Bob that sends a connection request to Alice, therefore Bob is called the requester. Alice is called the responder.
5
Alice receives the connection request
This happens automatically as Bob’s instance knows how to reach Alice’s instance. The information is either in the serviceEndpoint field in case of non-public invite, or it is part of the DIDDoc in the ledger for the public DID of Alice.
6
Alice accepts the connection request
Use the /didexchange/{id}/accept-request endpoint. The {id} should be the connection_id that got created when Alice received the connection request. If you have --debug-connections enabled you can see it in Alice’s ACA-py logs:
Use the /connections/{id}/send-message endpoint. The {id} is the connection_id for Alice’s connection to Bob. For Bob there is a different connection_id for the connection with Alice. Unfortunately the basic messages are not printed in the ACA-py terminal. For you to be notified about a basic message coming in, we need to take a look at webhooks.
Automatic accepting
ACA-py support command line options to automatically accept invites and requests when they come in. This allows you to skip step 3 to 8. This is useful for development, but of course should not be used for production. The command line flags are --auto-accept-invites and --auto-accept-requests. The same parameters can be overridden in step 1 for Alice to automatically accept Bob’s request in step 5. Similarly, Bob can specify auto-accept in step 2 so step 3 will be done automatically.
Conclusion
It takes some effort to understand with which parameters to start the ACA-py instances and how to connect two agents. In the end the connecting of two agents can be done entirely via Swagger. In part 4 I will discuss how you can do this using my go-acapy-client library.