From 415b766d72f23ea5f4109ef766ec2c65c7429928 Mon Sep 17 00:00:00 2001 From: Stephen Curran Date: Wed, 14 Feb 2024 23:55:25 +0000 Subject: [PATCH] Demo description of reuse in establishing a connection Signed-off-by: Stephen Curran --- docs/demo/ReusingAConnection.md | 139 ++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 docs/demo/ReusingAConnection.md diff --git a/docs/demo/ReusingAConnection.md b/docs/demo/ReusingAConnection.md new file mode 100644 index 0000000000..a28ba88c9b --- /dev/null +++ b/docs/demo/ReusingAConnection.md @@ -0,0 +1,139 @@ +# Reusing a Connection + +The Aries [RFC 0434 Out of Band] protocol enables the concept of reusing a +connection such that when using [RFC 0023 DID Exchange] to establish a +connection with an agent with which you already have a connection, you can reuse +the existing connection instead of creating a new one. This is something you +couldn't do a with the older [RFC 0160 Connection Protocol] that we used in the +early days of Aries. It was a pain, and made for a lousy user experience, as on +every visit to an existing contact, the invitee got a new connection. + +The requirements on your invitations (such as in the example below) are: + +- The invitation `services` item **MUST** be a resolvable DID. + - Or alternatively, the invitation `services` item **MUST NOT** be an `inline` service. +- The DID in the invitation `services` item is the same one in every invitation. + +Example invitation: + +```jsonc +{ + "@type": "https://didcomm.org/out-of-band/1.1/invitation", + "@id": "77489d63-caff-41fe-a4c1-ec7e2ff00695", + "label": "faber.agent", + "handshake_protocols": [ + "https://didcomm.org/didexchange/1.0" + ], + "services": [ + "did:sov:4JiUsoK85pVkkB1bAPzFaP" + ] +} +``` + +[RFC 0434 Out of Band]: https://github.com/hyperledger/aries-rfcs/tree/main/features/0434-outofband +[RFC 0023 DID Exchange]: https://github.com/hyperledger/aries-rfcs/tree/main/features/0023-did-exchange +[RFC 0160 Connection Protocol]: https://github.com/hyperledger/aries-rfcs/tree/main/features/0160-connection-protocol +[RFC 0434 Out of Band invitation]: https://github.com/hyperledger/aries-rfcs/tree/main/features/0434-outofband#invitation-httpsdidcommorgout-of-bandverinvitation +[RFC 0023 DID Exchange request]: https://github.com/hyperledger/aries-rfcs/tree/main/features/0023-did-exchange#1-exchange-request +[RFC 0434 Out of Band reuse]: https://github.com/hyperledger/aries-rfcs/tree/main/features/0434-outofband#reuse-messages + +Here's the flow that demonstrates where reuse helps. For simplicity, we'll use the terms "Issuer" +and "Wallet" in this example, but it applies to any connection between any two +agents (the inviter and the invitee) that establish connections with one another. + +- The Wallet user is using a browser on the Issuers website and gets to the + point where they are going to be offered a credential. As part of that flow, + they are presented with a QR code that they scan with their wallet app. +- The QR contains an [RFC 0434 Out of Band invitation] to connect that the + Wallet processes as the *invitee*. +- The Wallet uses the information in the invitation to send an [RFC 0023 DID Exchange request] + DIDComm message back to the Issuer to initiate establishing a connection. +- The Issuer responds back to the `request` with a `response` message, and the + connection is established. +- Later, the Wallet user returns to the Issuer's website, and does something + (perhaps starts the process to get another credential) that results in the + same QR code being displayed, and again the users scans the QR code with their + Wallet app. +- The Wallet recognizes (based on the DID in the `services` item in the + invitation -- see example below) that it already has a connection to the + Issuer, so instead of sending a DID Exchange `request` message back to the + Issuer, they send an [RFC 0434 Out of Band reuse] DIDComm message, and both + parties know to use the existing connection. + - Had the Wallet used the DID Exchange `request` message, a new connection + would have been established. + +The [RFC 0434 Out of Band] protocol requirement enables `reuse` message by the +invitee (the Wallet in the flow above) is that the `service` in the invitation +**MUST** be a resolvable DID that is the same in all of the invitations. In the +example invitation above, the DID is a `did:sov` DID that is resolvable on a public +Hyperledger Indy network. The DID could also be a [Peer DID] of types 2 or 4, +which encode the entire DIDDoc contents into the DID identifier (thus they are +"resolvable DIDs"). What cannot be used is either the old "unqualified" DIDs +that were commonly used in Aries prior to 2024, and [Peer DID] type 1. Both of +those have DID types include both an identifier and a DIDDoc in the `services` +item of the Out of Band invitation. As noted in the Out of Band specification, +`reuse` cannot be used with such DID types even if the contents are the same. + +[Peer DID]: https://identity.foundation/peer-did-method-spec/ + +Example invitation: + +```jsonc +{ + "@type": "https://didcomm.org/out-of-band/1.1/invitation", + "@id": "77489d63-caff-41fe-a4c1-ec7e2ff00695", + "label": "faber.agent", + "handshake_protocols": [ + "https://didcomm.org/didexchange/1.0" + ], + "services": [ + "did:sov:4JiUsoK85pVkkB1bAPzFaP" + ] +} +``` + +The use of conenction reuse can be demonstrated with the Alice / Faber demos as +follows. We assume you have already somewhat familiar with your options for +running the [Alice Faber Demo] (e.g. locally or in a browser). Follow those +instruction up to the point where you are about to start the Faber and Alice agents. + +[Alice Faber Demo]: ./README.md + +1. On a command line, run Faber with these parameters: `./run_demo faber + --reuse-connection --events`. +2. On a second command line, run Alice as normal, perhaps with the `events` + option: `./run_demo alice --events` +3. Copy the invitation from the Faber terminal and paste it into the Alice + terminal at the prompt. +4. Verify that the connection was established. + 1. If you want, go to the Alice OpenAPI screen (port `8031`, path + `api/docs`), and then use the `GET Connections` to see that Alice has one + connection to Faber. +5. In the Alice terminal, type `4` to get a prompt for a new connection, and + paste the same invitation as in Step 3 (above). +6. Note from the webhook events in the Faber terminal that the `reuse` message + is received from Alice, and as a result, no new connection was created. + 1. Execute again the `GET Connections` endpoint on the Alice OpenAPI screen + to confirm that there is still just one established connection. +7. In the Faber terminal, type `4` to get a new invitation, copy the invitation, + in the Alice terminal, type `4` to get prompted for an invitation, and paste + in the new invitation from Faber. Again, the `reuse` webhook event will be + visible in the Faber terminal. + 1. Execute again the `GET Connections` endpoint on the Alice OpenAPI screen + to confirm that there is still just one established connection. + 2. Notice that in the invitations in Step 3 and 7 both have the same DID in + the `services`. +8. Try running the demo again **without** the `--reuse-connection` parameter and + compare the `services` value in the new invitation vs. what was generated in + Steps 3 and 7. It is not a DID, but rather a one time use, inline DIDDoc + item. + +While in the demo Faber uses in the invitation the same DID they publish as an +issuer (and uses in creating the schema and Cred Def for the demo), Faber could +use any *resolvable* (not inline) DID, including DID Peer types 2 or 4 DIDs, as +long as the DID is the same in every invitation. It is the fact that the DID is +always the same that tells the invitee that they can reuse an existing connection. + +Note that the invitation does **NOT** have to be a multi-use invitation for +reuse to be useful, as long as the other requirements (at the top of this +document) are met.