From 30f373a8e1aa8deeaca5e49d3b20d69006582f7a Mon Sep 17 00:00:00 2001 From: Stephen Curran Date: Mon, 1 Jul 2019 19:26:57 +0000 Subject: [PATCH 1/2] New document about establishing routes in DIDDocs Signed-off-by: Stephen Curran --- .../AriesRoutingExample.md | 76 +++++++++++++++++++ .../IndyAriesDevOptions.md | 6 +- docs/GettingStartedAriesDev/README.md | 7 +- 3 files changed, 84 insertions(+), 5 deletions(-) create mode 100644 docs/GettingStartedAriesDev/AriesRoutingExample.md diff --git a/docs/GettingStartedAriesDev/AriesRoutingExample.md b/docs/GettingStartedAriesDev/AriesRoutingExample.md new file mode 100644 index 0000000000..7bea67aed3 --- /dev/null +++ b/docs/GettingStartedAriesDev/AriesRoutingExample.md @@ -0,0 +1,76 @@ +# Aries Routing - an example + +In this example, we'll walk through an example of routing in Aries, outlining some of the possibilities that can be implemented with Aries. + +We'll start with the Alice and Bob example from the [Cross Domain Messaging]() Aries RFC. + +![Cross Domain Messaging Example](https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0094-cross-domain-messaging/domains.jpg "Cross Domain Messaging Example") + +What are the DIDs involved, what's in their DIDDocs, and what communications are happening between the agents as the connections are made? + +## The Scenario + +Bob and Alice want to establish a connection so that they can communicate. Bob uses an Agency endpoint ("https://agents-r-us.com), labelled as 9 and will have an agent used for routing, labelled as 3. We'll also focus on Bob's messages from his main iPhone, labelled as 4. We'll ignore Bob's other agents (5 and 6) and we won't worry about Alice's configuration (agents 1, 2 and 8). + +## All the DIDs + +A DID and DIDDoc are generated by each participant in each relationship. For Bob's agents (iPhone and Routing), that includes: + +- Bob and Alice +- Bob and his Routing Agent +- Bob and Agency +- Bob's Routing Agent and Agency + +That's a lot more than just the Bob and Alice relationship we usually think about! + +## DIDDoc Data + +From a routing perspective the information that is important in the DIDDoc is the following (as defined in the [DIDDoc Conventions Aries RFC](https://github.com/hyperledger/aries-rfcs/blob/master/features/0067-didcomm-diddoc-conventions/README.md)): + +- The public keys for each agent referenced in the routing +- The `services` of type `did-communication` services, including: + - the one `serviceEndpoint` + - the `recipientKeys` array of referenced keys for the ultimate target(s) of the message + - the `routingKeys` array of referenced keys for the mediators + +Let's look at the `did-communication` service data in the DIDDocs generated by Bob's iPhone and Routing agents, listed above: + +- Bob and Alice: + - The `serviceEndpoint` that Bob tells Alice about is the endpoint for the Agency. + - We'll use for the endpoint the Agency's public DID. That way the Agency can change rotate the keys for the endpoint without all of it's clients from having to update every DID with the change. + - The `recipientKeys` entry is a key reference for Bob's iPhone specifically for Alice. + - The `routingKeys` entries is the public DID for the Agency and a reference to the public key for the Routing Agent. +- Bob and his Routing Agent: + - The `serviceEndpoint` is empty because Bob's iPhone has no endpoint. We'll get to how that works later. + - The `recipientKeys` entry is a key reference for Bob's iPhone specifically for the Routing Agent. + - The `routingKeys` array is empty. +- Bob and Agency: + - The `serviceEndpoint` is the endpoint for Bob's Routing Agent. + - The `recipientKeys` entry is a key reference for Bob's iPhone specifically for the Agency. + - The `routingKeys` is a single entry for the key reference for the Routing Agent key. +- Bob's Routing Agent and Agency: + - The `serviceEndpoint` is the endpoint for Bob's Routing Agent. + - The `recipientKeys` entry is a key reference for Bob's Routing Agent specifically for the Agency. + - The `routingKeys` array is empty. + +The null `serviceEndpoint` for Bob's iPhone is worth a comment. Mobile apps work by sending requests to servers, but cannot be accessed directly from a server. A DIDcomm mechanism ([Transports Return Route](https://github.com/hyperledger/aries-rfcs/tree/master/features/0092-transport-return-route)) enables a server to send messages to a Mobile agent by putting the messages into the response to a request from the mobile agent. While not formalized in an Aries RFC (yet), cloud agents can use mobile platforms' (Apple and Google) notification mechanisms to trigger a user interface event. + +## Preparing Bob's DIDDoc for Alice + +Given that background, let's go through the sequence of events and messages that occur in building a DIDDoc for Bob's edge agent to send to Alice's edge agent. We'll start the sequence with all of the Agents in place, as the bootstrapping of the Agency, Routing Agent and Bob's iPhone is trickier than we need to go through here. We'll call that an "exercise left for the reader". + +We'll start the process with Alice sending an out of band connection invitation message to Bob, e.g. through a QR code. Here's one possible sequence for creating the DIDDoc. Note that there are other ways this could be done: + +- Bob's iPhone agent generates a new DID for Alice and prepares, and partially completes, a DIDDoc +- Bob messages the Routing Agent to send the DID and to get a new public key for the Alice relationship. + - The Routing Agent records the DID for Alice and the keypair to be used for messages from Alice. +- The Routing Agent sends the the DID to the Agency to let the Agency know that messages for that DID are to go to the Routing Agent. +- The Routing Agent sends the data to Bob's iPhone agent. +- Bob's iPhone agent fills in the rest of the DIDDoc: + - the public key for the Routing Agent for the Alice relationship + - the `did-communication` service endpoint is set to the Agency public DID and + - the routing keys array with the values of the Agency public DID key reference and the Routing Agent key reference + +With the DIDDoc ready, Bob uses the path provided in the invitation to send a `connection-request` message to Alice with the new DID and DIDDoc. Subsequently, when Alice sends messages to Bob's agent, she uses the information in the DIDDoc to securely get the message to the Agency endpoint, through the Routing Agent and on to Bob's iPhone agent for processing. + +At this time, there are **not** specific DIDcomm protocols for the messages between the agents in Bob's domain (Agency, Routing and iPhone). Those could be implemented to be proprietary by each agent provider, but it's likely those will be specified as standard DIDcomm protocols. diff --git a/docs/GettingStartedAriesDev/IndyAriesDevOptions.md b/docs/GettingStartedAriesDev/IndyAriesDevOptions.md index ef693e74bc..d319475c8f 100644 --- a/docs/GettingStartedAriesDev/IndyAriesDevOptions.md +++ b/docs/GettingStartedAriesDev/IndyAriesDevOptions.md @@ -4,7 +4,7 @@ Now that you know the basics of the Indy/Aries eco-system, what do you want to w This is an important summary for newcomers, as often the temptation is to start at a level far below where you plan to focus your attention. Too often devs coming into the community start at "the blockchain"; at `indy-node` (the Indy public ledger) or the `indy-sdk`. That is far below where the majority of developers will work and is not really that helpful if what you really want to do is build decentralized identity applications. -In the following, we go through the layers from the top of the stack to the bottom. Our expectation is that the majority of developers will work at the application level, and there will be fewer contributing developers each layer down the stack you go. This is not to dissuade anyone from contributing at the lower levels, but rather to say if you are not going to contribute at the lower levels, you don't need to everything about it. It's much like web development - you don't need to know TCP/IP to build web apps. +In the following, we go through the layers from the top of the stack to the bottom. Our expectation is that the majority of developers will work at the application level, and there will be fewer contributing developers each layer down you go. This is not to dissuade anyone from contributing at the lower levels, but rather to say if you are not going to contribute at the lower levels, you don't need to everything about it. It's much like web development - you don't need to know TCP/IP to build web apps. ## Building Decentralized Identity Applications @@ -18,7 +18,7 @@ Note that if building apps is what you want to do, you don't need to do a deep d ## Contributing to `aries-cloudagent-python` -Of course as you build applications using `aries-cloudagent-python`, you will no doubt find deficiencies in the code and things you need added. Contributions to this repo will **always** be welcome. +Of course as you build applications using `aries-cloudagent-python`, you will no doubt find deficiencies in the code and features you want added. Contributions to this repo will **always** be welcome. ## Supporting Additional Ledgers @@ -30,7 +30,7 @@ Although controllers for an `aries-cloudagent-python` instance can be written in ## Improving Aries SDK -This code base and other Aries agent implementations currently embed the `indy-sdk`. However, much of the code in the `indy-sdk` is being migrated into a variety of Aries language specific repositories. How this is migration is to be done is still being decided, but it makes sense that the agent-type things be moved to Aries repositories. A number of [language specific Aries SDK](https://github.com/hyperledger?utf8=%E2%9C%93&q=aries+sdk&type=&language=) repos have been created and are being populated. +This code base and other Aries agent implementations currently embed the `indy-sdk`. However, much of the code in the `indy-sdk` is being migrated into a variety of Aries language specific repositories. How this migration is to be done is still being decided, but it makes sense that the agent-type things be moved to Aries repositories. A number of [language specific Aries SDK](https://github.com/hyperledger?utf8=%E2%9C%93&q=aries+sdk&type=&language=) repos have been created and are being populated. ## Improving the Indy SDK diff --git a/docs/GettingStartedAriesDev/README.md b/docs/GettingStartedAriesDev/README.md index 2841cfece7..8da747e79a 100644 --- a/docs/GettingStartedAriesDev/README.md +++ b/docs/GettingStartedAriesDev/README.md @@ -10,7 +10,7 @@ Note that in the guidance we have here, we include not only the links to look at * [Aries Agents in Context: The Big Picture](AriesBigPicture.md) * [Aries Internals - Deployment Components](AriesAgentArchitecture.md) * [An overview of Aries messaging](AriesMessaging.md) -* [Aries Developer Demos](AriesDeveloperDemos.md) +* [Demos - Aries Developer](AriesDeveloperDemos.md) * To Do: [Establishing a connection between Aries Agents](AgentConnections.md) * To Do: [Issuing an Indy credential: From Issuer to Holder/Prover](IssuingIndyCredentials.md) * To Do: [Presenting an Indy credential: From Holder/Prover to Verifier](PresentingIndyProofs.md) @@ -18,4 +18,7 @@ Note that in the guidance we have here, we include not only the links to look at * [What should I work on? Options for Aries/Indy Developers](IndyAriesDevOptions.md) * [Deeper Dive: DIDcomm Messages](DIDcommMsgs.md) * [Deeper Dive: DIDcomm Message Routing and Encryption](RoutingEncryption.md) -* To Do: [Deeper Dive: Running and Connecting to an Indy Network](ConnectIndyNetwork.md) \ No newline at end of file +* [Deeper Dive: Routing Example](AriesRoutingExample.md) +* To Do: [Deeper Dive: Running and Connecting to an Indy Network](ConnectIndyNetwork.md) + +Want to help with this guide? Please add issues or submit a pull request to improve the document. Point out things that are missing, things to improve and especially things that are wrong. \ No newline at end of file From b1f857cd73fa807b2cd2b8a7169eefa13631efbc Mon Sep 17 00:00:00 2001 From: Stephen Curran Date: Tue, 2 Jul 2019 16:10:09 +0000 Subject: [PATCH 2/2] Updates to the routing example from reviewers Signed-off-by: Stephen Curran --- .../AriesRoutingExample.md | 36 +++++++++++-------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/GettingStartedAriesDev/AriesRoutingExample.md b/docs/GettingStartedAriesDev/AriesRoutingExample.md index 7bea67aed3..9b84f20679 100644 --- a/docs/GettingStartedAriesDev/AriesRoutingExample.md +++ b/docs/GettingStartedAriesDev/AriesRoutingExample.md @@ -1,6 +1,6 @@ # Aries Routing - an example -In this example, we'll walk through an example of routing in Aries, outlining some of the possibilities that can be implemented with Aries. +In this example, we'll walk through an example of complex routing in Aries, outlining some of the possibilities that can be implemented. We'll start with the Alice and Bob example from the [Cross Domain Messaging]() Aries RFC. @@ -10,7 +10,7 @@ What are the DIDs involved, what's in their DIDDocs, and what communications are ## The Scenario -Bob and Alice want to establish a connection so that they can communicate. Bob uses an Agency endpoint ("https://agents-r-us.com), labelled as 9 and will have an agent used for routing, labelled as 3. We'll also focus on Bob's messages from his main iPhone, labelled as 4. We'll ignore Bob's other agents (5 and 6) and we won't worry about Alice's configuration (agents 1, 2 and 8). +Bob and Alice want to establish a connection so that they can communicate. Bob uses an Agency endpoint ("https://agents-r-us.com), labelled as 9 and will have an agent used for routing, labelled as 3. We'll also focus on Bob's messages from his main iPhone, labelled as 4. We'll ignore Bob's other agents (5 and 6) and we won't worry about Alice's configuration (agents 1, 2 and 8). While the process below is all about Bob, Alice and her agents are doing the same interactions within her domain. ## All the DIDs @@ -25,10 +25,10 @@ That's a lot more than just the Bob and Alice relationship we usually think abou ## DIDDoc Data -From a routing perspective the information that is important in the DIDDoc is the following (as defined in the [DIDDoc Conventions Aries RFC](https://github.com/hyperledger/aries-rfcs/blob/master/features/0067-didcomm-diddoc-conventions/README.md)): +From a routing perspective the important information in the DIDDoc is the following (as defined in the [DIDDoc Conventions Aries RFC](https://github.com/hyperledger/aries-rfcs/blob/master/features/0067-didcomm-diddoc-conventions/README.md)): -- The public keys for each agent referenced in the routing -- The `services` of type `did-communication` services, including: +- The public keys for agents referenced in the routing +- The `services` of type `did-communication`, including: - the one `serviceEndpoint` - the `recipientKeys` array of referenced keys for the ultimate target(s) of the message - the `routingKeys` array of referenced keys for the mediators @@ -37,11 +37,11 @@ Let's look at the `did-communication` service data in the DIDDocs generated by B - Bob and Alice: - The `serviceEndpoint` that Bob tells Alice about is the endpoint for the Agency. - - We'll use for the endpoint the Agency's public DID. That way the Agency can change rotate the keys for the endpoint without all of it's clients from having to update every DID with the change. + - We'll use for the endpoint the Agency's public DID. That way the Agency can change rotate the keys for the endpoint without all of it's clients from having to update every DIDDoc with the new key. - The `recipientKeys` entry is a key reference for Bob's iPhone specifically for Alice. - - The `routingKeys` entries is the public DID for the Agency and a reference to the public key for the Routing Agent. + - The `routingKeys` entries is a reference to the public key for the Routing Agent. - Bob and his Routing Agent: - - The `serviceEndpoint` is empty because Bob's iPhone has no endpoint. We'll get to how that works later. + - The `serviceEndpoint` is empty because Bob's iPhone has no endpoint. See the note below for more on this. - The `recipientKeys` entry is a key reference for Bob's iPhone specifically for the Routing Agent. - The `routingKeys` array is empty. - Bob and Agency: @@ -57,20 +57,28 @@ The null `serviceEndpoint` for Bob's iPhone is worth a comment. Mobile apps work ## Preparing Bob's DIDDoc for Alice -Given that background, let's go through the sequence of events and messages that occur in building a DIDDoc for Bob's edge agent to send to Alice's edge agent. We'll start the sequence with all of the Agents in place, as the bootstrapping of the Agency, Routing Agent and Bob's iPhone is trickier than we need to go through here. We'll call that an "exercise left for the reader". +Given that background, let's go through the sequence of events and messages that occur in building a DIDDoc for Bob's edge agent to send to Alice's edge agent. We'll start the sequence with all of the Agents in place as the bootstrapping of the Agency, Routing Agent and Bob's iPhone is trickier than we need to go through here. We'll call that an "exercise left for the reader". -We'll start the process with Alice sending an out of band connection invitation message to Bob, e.g. through a QR code. Here's one possible sequence for creating the DIDDoc. Note that there are other ways this could be done: +We'll start the process with Alice sending an out of band connection invitation message to Bob, e.g. through a QR code or a link in an email. Here's one possible sequence for creating the DIDDoc. Note that there are other ways this could be done: - Bob's iPhone agent generates a new DID for Alice and prepares, and partially completes, a DIDDoc -- Bob messages the Routing Agent to send the DID and to get a new public key for the Alice relationship. +- Bob messages the Routing Agent to send the newly created DID and to get a new public key for the Alice relationship. - The Routing Agent records the DID for Alice and the keypair to be used for messages from Alice. -- The Routing Agent sends the the DID to the Agency to let the Agency know that messages for that DID are to go to the Routing Agent. +- The Routing Agent sends the the DID to the Agency to let the Agency know that messages for the new DID are to go to the Routing Agent. - The Routing Agent sends the data to Bob's iPhone agent. - Bob's iPhone agent fills in the rest of the DIDDoc: - the public key for the Routing Agent for the Alice relationship - the `did-communication` service endpoint is set to the Agency public DID and - the routing keys array with the values of the Agency public DID key reference and the Routing Agent key reference -With the DIDDoc ready, Bob uses the path provided in the invitation to send a `connection-request` message to Alice with the new DID and DIDDoc. Subsequently, when Alice sends messages to Bob's agent, she uses the information in the DIDDoc to securely get the message to the Agency endpoint, through the Routing Agent and on to Bob's iPhone agent for processing. +**Note**: Instead of using the DID Bob created, the Agency and Routing Agent might use the public key used to encrypt the messages for their internal routing table look up for where to send a message. In that case, the Bob and the Routing Agent share the public key instead of the DID to their respective upstream routers. -At this time, there are **not** specific DIDcomm protocols for the messages between the agents in Bob's domain (Agency, Routing and iPhone). Those could be implemented to be proprietary by each agent provider, but it's likely those will be specified as standard DIDcomm protocols. +With the DIDDoc ready, Bob uses the path provided in the invitation to send a `connection-request` message to Alice with the new DID and DIDDoc. Alice now knows how to get any DIDcomm message to Bob in a secure, end-to-end encrypted manner. Subsequently, when Alice sends messages to Bob's agent, she uses the information in the DIDDoc to securely send the message to the Agency endpoint, it is sent through to the Routing Agent and on to Bob's iPhone agent for processing. Now Bob has the information he needs to securely send any DIDcomm message to Alice in a secure, end-to-end encrypted manner. + +At this time, there are **not** specific DIDcomm protocols for the "set up the routing" messages between the agents in Bob's domain (Agency, Routing and iPhone). Those could be implemented to be proprietary by each agent provider (since it's possible one vendor would write the code for each of those agents), but it's likely those will be specified as open standard DIDcomm protocols. + +Based on the DIDDoc that Bob has sent Alice, for her to send a DIDcomm message to Bob, Alice must: + +* Prepare the message for Bob's Agent. +* Encrypt and place that message into a "Forward" message for Bob's Routing Agent. +* Encrypt and send the "Forward" message to Bob's Agency endpoint.