New routing example document, typo corrections

docs/GettingStartedAriesDev/AriesRoutingExample.md

@@ -0,0 +1,84 @@
+# Aries Routing - an example
+
+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.
+
+![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). While the process below is all about Bob, Alice and her agents are doing the same interactions within her domain.
+
+## 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 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 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
+
+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 DIDDoc with the new key.
+  - The `recipientKeys` entry is a key reference for Bob's iPhone specifically for Alice.
+  - 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. 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:
+  - 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 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 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 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
+
+**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.
+
+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.

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
 

docs/GettingStartedAriesDev/README.md

@@ -10,12 +10,15 @@ 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)
 * To Do: [Next steps: Creating your own Aries Agent](YourOwnAriesAgent.md)
 * [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)
+* [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.