Detailed guide on DIDComm messaging for edge device registration and …

…OOB message exchange.

docs/edge-device-doc.md

@@ -0,0 +1,93 @@
+#             DIDComm Messaging for Edge Device Registration and Message Exchange
+## Introduction
+With the growth of IoT and connected devices, ensuring secure, private communication between edge devices—like smart sensors, appliances, and mobile devices—has become essential. DIDComm (Decentralized Identifier Communication) provides a protocol for private, out-of-band (OOB) messaging, enabling communication without intermediaries directly accessing data. This makes it a powerful tool for IoT networks where privacy and security are paramount.
+
+A core component of DIDComm messaging is mediation coordination. Through a central Mediator, devices like Alice and Bob can establish reliable OOB communication channels, even across complex network structures. The Mediator plays a key role in managing secure routing, enabling Alice and Bob to communicate seamlessly and privately.
+
+#                      Benefits of DIDComm Messaging for Edge Devices
+## Enhanced Security: 
+DIDComm's encryption mechanisms protect message content, even when routed through a mediator.
+## Privacy Preservation:
+Only routing information is exposed to intermediaries, keeping the message content confidential.
+## Role Flexibility: 
+Devices can alternate between sender and recipient roles, enabling more dynamic OOB communication.
+## Reliable Message Delivery: 
+Mediation coordination allows devices to maintain reliable communication paths, even with network complexity.
+
+This guide explores the DIDComm messaging process in three main stages, from initial registration of Alice with the Mediator to secure OOB message exchange with Bob. We'll detail the roles of each participant, the secure exchange of keys, and the flow of messages, with a focus on maintaining flexibility and privacy.
+
+#                               Key Roles in DIDComm Messaging
+## Mediator:
+ The Mediator is a trusted service that coordinates OOB routing for edge devices like Alice and Bob. Beyond just forwarding messages, the Mediator provides routing information, manages encryption keys, and ensures sender and recipient identities remain masked from each other. This coordination allows Alice and Bob to connect securely, even across different networks or with indirect reachability.
+
+## Alice (Edge Device):
+ Alice is an edge device initiating OOB communication. As she prepares to reach Bob, she first connects with the Mediator to obtain essential routing details, such as a routing Decentralized Identifier (DID). This setup establishes a secure OOB communication path while using the Mediator as a private relay.
+
+## Bob (Edge Device/Recipient):
+ Bob is the target recipient of Alice’s messages. However, Bob can also initiate communication, dynamically switching roles as needed. Both Alice and Bob can act as sender and recipient, ensuring adaptability in their interactions.
+
+#                             DIDComm Messaging Phases
+The DIDComm messaging process for Alice and Bob involves three phases, each with specific actions to ensure secure, efficient OOB communication.
+
+## Establishing Mediation 
+– Alice sets up a trusted connection with the Mediator to acquire routing details.
+## Message Exchange Preparation 
+– Alice and the Mediator establish cryptographic keys for secure communication.
+## Message Pickup and Delivery 
+– Alice and Bob securely exchange OOB messages, with the Mediator coordinating routing.
+
+#                          Phase 1: Establishing Mediation
+In this initial phase, Alice registers with the Mediator, setting up the necessary framework for routing future OOB messages. By establishing mediation, Alice gains the essential routing details needed to connect with Bob securely.
+
+## Mediation Request:
+  Alice initiates a request to the Mediator, indicating her intention to use the Mediator’s services for secure OOB message routing. This request formally begins the mediation coordination process, signaling that Alice needs an intermediary to handle her future communications with other devices, such as Bob.
+
+## Mediation Grant:
+ The Mediator confirms the relationship by granting mediation to Alice. Along with this grant, Alice receives a routing DID—a decentralized identifier for the Mediator’s routing path. This routing DID establishes a secure and private connection for future OOB messages between Alice and Bob, helping the Mediator direct messages appropriately.
+
+With mediation established, Alice is equipped to communicate securely, knowing she has a reliable OOB route through the Mediator.
+
+#                          Phase 2: Message Exchange Preparation
+ With the mediation relationship in place, Alice now prepares to send an OOB message to Bob by ensuring the cryptographic keys required for secure communication are up-to-date and properly aligned with the Mediator’s setup.
+
+## Key Management:
+ Alice reviews her encryption keys to confirm they are current. This process often involves updating keys if the device identity has changed, if there are new recipients involved, or if Alice’s configuration has been updated. To ensure secure communication, Alice sends a keylist-update message to the Mediator, specifying any additions, removals, or changes to her encryption keys.
+
+## Secure Key Exchange:
+ Alice and the Mediator then exchange public keys, establishing a secure foundation for encrypting future OOB messages. This allows the Mediator to handle message routing for Alice while preserving message confidentiality, as the Mediator does not have access to the actual message content.
+
+With secure keys in place, Alice can now initiate or respond to OOB messages, confident in the privacy and security of the communication pathway.
+
+#                        Phase 3: Message Pickup and Delivery
+With routing and encryption set, Alice is ready to send and receive OOB messages through the Mediator. This phase involves requests, deliveries, and acknowledgments to ensure reliable OOB message exchange between Alice and Bob.
+
+## Checking for Messages:
+ To stay informed about any incoming OOB messages, Alice periodically checks with the Mediator. She sends a status request, allowing her to pick up messages on demand. This provides asynchronous communication where Alice can retrieve OOB messages as needed.
+
+## Message Creation and Delivery Request:
+ Alice composes an encrypted OOB message for Bob, wrapping it in multiple layers of encryption—DIDComm’s “onion encryption”—for added security. She includes Bob’s routing DID (provided by the Mediator) as part of the routing information, which specifies how the Mediator should forward the message.
+
+## Message Forwarding by the Mediator:
+ Upon receiving the OOB message, the Mediator unpacks only the outer layer. This outer layer reveals only the necessary routing information, allowing the Mediator to forward the message to Bob without accessing its content. This process maintains privacy, as the Mediator never decrypts the actual message intended for Bob.
+
+## Message Pickup by Bob:
+ Once the Mediator has routed Alice’s OOB message, Bob receives it and decrypts it using his private key. This decryption allows him to access Alice’s message securely, maintaining the integrity of their communication.
+
+## Acknowledgment of Receipt:
+ After decrypting and reading Alice’s OOB message, Bob sends an acknowledgment back through the Mediator. This confirmation helps Alice verify that her message has successfully reached Bob, adding reliability and traceability to the exchange.
+
+## Final Status Check:
+ After the message exchange, Alice can perform a final status check with the Mediator to confirm that all OOB messages have been delivered. While this check often follows an initial exchange, it can be repeated as necessary, helping Alice verify delivery status and check for any pending messages. This flexibility is valuable in environments where devices frequently shift roles or reconnect.
+
+#                       Flexibility and Privacy in the DIDComm Process
+DIDComm’s design prioritizes a flexible and privacy-preserving communication structure:
+
+## Role Interchangeability:
+ Alice and Bob can dynamically shift between sender and recipient roles based on communication needs. This flexibility allows either device to initiate or respond to OOB messages as situations evolve.
+
+## Privacy Preservation:
+ The Mediator only unpacks the outer layer of encryption for routing, ensuring the inner content remains confidential. Each layer of encryption reinforces privacy while allowing the Mediator to route messages securely.
+
+#                                           Conclusion
+
+DIDComm messaging offers a robust framework for secure, private OOB communication between edge devices. Through effective mediation coordination, devices like Alice and Bob can connect and communicate reliably, even in complex network settings.