From 466489d87c245e2e718008b5554ea71a9eef5cf1 Mon Sep 17 00:00:00 2001 From: Tekum Emmaanuella Date: Thu, 21 Nov 2024 11:27:24 +0100 Subject: [PATCH] updated arc doc with Architecture Decisions and Quality Requirements. --- docs/Architecture.md | 121 ------------------------------------------- docs/arc42.md | 93 ++++++++++++++++++++++++++------- 2 files changed, 73 insertions(+), 141 deletions(-) delete mode 100644 docs/Architecture.md diff --git a/docs/Architecture.md b/docs/Architecture.md deleted file mode 100644 index b803b101..00000000 --- a/docs/Architecture.md +++ /dev/null @@ -1,121 +0,0 @@ -# DIDComm Mediator Architecture Document - -### **Table of Contents** -- [**DIDComm Mediator Architecture Document**](#didcomm-mediator-architecture-document) -- [**Table of Contents**](#table-of-contents) -- [**1. Introduction**](#1-introduction) - - [**1.1 Purpose**](#11-purpose) - - [**1.2 System Overview**](#12-system-overview) - - [**1.3 Quality Goals**](#13-quality-goals) - - [**1.4 Stakeholders**](#14-stakeholders) -- [**2. Constraints**](#2-constraints) -- [**3. System Scope and Context**](#3-system-scope-and-context) - - [**3.1 Business Context**](#31-business-context) - - [**3.2 Technical Context**](#32-technical-context) -- [**4. Solution Strategy**](#4-solution-strategy) -- [**5. Building Block View**](#5-building-block-view) -- [**6. Runtime View**](#6-runtime-view) -- [**7. Deployment View**](#7-deployment-view) -- [**8. Cross Cutting Concerns**](#8-cross-cutting-concerns) -- [**9. Architectural Decisions**](#9-architectural-decisions) -- [**10. Quality Requirements**](#10-quality-requirements) -- [**11. Risk and Technical Debt**](#11-risk-and-technical-debt) -- [**12. Glossary**](#12-glossary) - -## 1. Introduction -### 1.1 Purpose -This document provides a detailed architecture for the DIDComm Mediator, a system designed to mediate communication between decentralized identities (DIDs) using the DIDComm protocol. The document outlines the design decisions, components, and interactions in the system. - -### 1.2 System Overview -The DIDComm Mediator acts as an intermediary that forwards messages between decentralized identifiers (DIDs) while maintaining security, privacy, and scalability. It adheres to the DIDComm messaging protocol, enabling seamless communication between agents. - -### 1.3 Quality Goals -- ***Security***: End-to-End encryption and authentication. -- ***Scalability***: Handle high message volume efficiently. -- ***Reliability***: Ensure fault tolerance and high availability -- ***Extensibility***: Support future enhancements and additional DID methods - -### 1.4 Stakeholders -Key stakeholders include DATEV, the adorsys development team, and third-party developers - -## 2. Constraints -- The project will be implemented in rust so as to take advantage of it's performance and safety features -- Only asynchronous Rust frameworks like tokio, axum, hyper, tracing can be used to ensure non-blocking operations -- The project must adhere to DIDComm V2 specifications - -## 3. System Scope and Context -### 3.1 Business Context -The DIDComm Mediator acts as a bridge to enable seemless communication between decentralized agents, ensuring secure and reliable message routing. - -### 3.2 Technical Context -![images](work-flow.png) - -The DIDComm Mediator operates within decentralized identity systems, leveraging the DIDComm protocol and Decentralized Identifiers (DIDs) to provide secure and scalable communication between agents. - -***Key Technical Considerations** -- ***DIDComm Protocol:** Provides secure messaging with end-to-end encryption and authentication, creating a secure communication channel between decentralized agents. -- ***Decentralized Identifiers (DIDs):** Unique identifiers that enable self-sovereign, verifiable identities within the system. -- ***Secure Messaging Mechanisms:** TLS and other mechanisms ensure confidentiality and integrity of messages during transmission. -- ***Asynchronous Rust Frameworks:** Utilizes libraries such as tokio, axum, hyper, and tracing for high-performance, non-blocking operations. -- ***Adherence to Specifications:** The system adheres to the DIDComm V2 specifications for compatibility and standardization. - -***Core Components and Responsibilities** -- ***Mediator Core Module:** The central component responsible for receiving, storing, and routing messages while ensuring DIDComm V2 compliance. -- ***DID Resolver:** Interfaces with decentralized networks/registries to validate and retrieve DID documents, enabling proper routing based on public keys or routing details. -- ***Message Handling and Routing:** Supports various DIDComm message types (e.g., forward messages) and ensures robust routing based on recipient details. -- ***Message Storage** Temporarily stores messages until recipients retrieve them, using optimized storage mechanisms and asynchronous I/O. - -***Key Technical Challenges** -- ***Message Confidentiality and Integrity:** Ensures messages remain secure and tamper-proof with end-to-end encryption and compliance with security standards. -- ***Performance Optimization:** Handles high message volumes using asynchronous Rust frameworks (tokio, hyper) to ensure scalable, non-blocking operations. -- ***Message Routing and Delivery:** Supports various DIDComm message types (e.g., forward messages) and ensures proper routing based on recipient details. - -***External Integrations** -- ***DID Registries and Networks**: Communicates with registries to perform reliable DID resolution. -- ***External Agents and Clients:** Interfaces with clients such as mobile and desktop applications for secure message routing. -- ***Verifiable Credential Systems:** Potentially integrates with credential issuance and verification workflows. - -***System Architecture Considerations** -- ***Security Protocols:** Implements TLS alongside end-to-end encryption within the DIDComm protocol, prioritizing security across all layers. -- ***Asynchronous Communication**: Uses asynchronous programming (via tokio and similar libraries) to manage high throughput without blocking operations. - -***Technology Choices:** -- ***Rust:** Rust language Chosen for memory safety, performance, and strong concurrency support. - -***Key Libraries:** -- ***serde:** For efficient serialization/deserialization. -- ***actix-web / axum:** Handles HTTP requests/web socket connections (based on the preferred framework). -- ***didkit (if applicable):** Supports DID operations, creation, and verification. - -# 4. Solution Strategy -The solution strategy outlines the foundational decisions that guide the system's architecture, aligning with the key quality goals, constraints, and overall system requirements. - -**Technology Decisions** -- **Programming Language**: Rust is chosen for its high performance, memory safety, and strong concurrency support. This decision aligns with the security and scalability goals of the mediator. -- **Cryptographic Libraries:** Askar is selected as the cryptographic library to provide high-level cryptographic functions specifically designed for decentralized identity systems. Askar offers key management, encryption, and decryption capabilities that are essential for DIDComm communication. Its focus on modularity and interoperability with other decentralized identity (DID) systems ensures that the system can evolve and stay secure over time. -- **Database:** MongoDB is selected as the database for its flexibility in handling semi-structured data, scalability, and ease of horizontal scaling. It is ideal for storing DID-related metadata, messages, and other data in a schema-less format that can adapt as the system evolves. - -**Organisational Decisions** -- **Development Process:**Agile methodology is adopted to deliver incremental updates and adapt to changing requirements. -- **Task Delegation:** Integration with external DID registries is modularized, enabling future partnerships with third-party providers for registry or DID resolution services. -- **Team Structure:** Assign dedicated team to core components (e.g., Mediator Core, Key Management, Communication Interfaces) for focused development and testing. - - -## 5. Building Block View - -## 6. Runtime View - -## 7. Deployment View - -## 8. Cross Cutting Concerns - -## 9. Architectural Decisions - -## 10. Quality Requirements - -## 11. Risk and Technical Debt - -## 12. Glossary -- ***DID(Decentralized Identifier):*** A unique identifier that enables verifiable, self-sovereign identities -- ***DIDComm:*** A secure messaging protocol used to communicate over decentralized networks -- ***Mediator:*** An intermediary service that routes DIDComm messages between agents diff --git a/docs/arc42.md b/docs/arc42.md index 4ce83521..d9e82d2d 100644 --- a/docs/arc42.md +++ b/docs/arc42.md @@ -22,7 +22,7 @@ Here is an ARC42 architecture document tailored for the Rust-based `didcomm-medi --- -## 1. Introduction +## 1. [Introduction](#introduction) ### 1.1 Document Goals This document outlines the architecture of the `didcomm-mediator-rs`, a Rust-based implementation of a DIDComm v2 mediator. Its purpose is to ensure secure, efficient, and reliable routing of DIDComm messages while providing clarity to stakeholders, architects, and developers. @@ -36,7 +36,7 @@ This document outlines the architecture of the `didcomm-mediator-rs`, a Rust-bas --- -## 2. Architecture Constraints +## 2. [Architecture Constraints](#architecture-constraints) ### 2.1 Technical Constraints - **Rust Programming Language**: Ensures high performance and memory safety. @@ -49,7 +49,7 @@ This document outlines the architecture of the `didcomm-mediator-rs`, a Rust-bas --- -## 3. System Scope and Context +## 3. [System Scope and Context](#system-scope-and-context) ### 3.1 Business Context The mediator facilitates routing of DIDComm messages for agents unable to maintain direct communication channels. It acts as an intermediary, ensuring reliability and privacy. @@ -71,7 +71,7 @@ graph LR --- -## 4. Solution Strategy +## 4. [Solution Strategy](#solution-strategy) A microservices approach ensures modularity and scalability. `didcomm-mediator-rs` employs Rust's async capabilities to handle concurrent message routing efficiently. ### Key Features: @@ -106,7 +106,7 @@ This modular and extensible implementation ensures the mediator evolves with the --- -## 5. Building Block View +## 5. [Building Block View](#building-block-view) ### 5.1 Overview @@ -168,7 +168,7 @@ graph TD --- -## 6. Runtime View +## 6. [Runtime View](#runtime-view) ### 6.1 Message Flow 1. Agent sends a message to the mediator. @@ -222,7 +222,7 @@ This interaction ensures that messages intended for the recipient are appropriat --- -## 7. Deployment View +## 7. [Deployment View](#deployment-view) ### 7.1 Deployment Strategy @@ -343,7 +343,7 @@ This detailed deployment view provides clarity on how the system can be deployed --- -## 8. Cross-cutting Concepts +## 8. [Cross-cutting Concepts](#cross-cutting-concepts) ### 8.1 Security @@ -517,38 +517,91 @@ This combination integrates **application security** and **SSDLC best practices* --- -## 9. Architecture Decisions -- **Rust for Performance**: Chosen for safety and speed. -- **Transport Agnosticism**: Supports various communication protocols. -- **Cloud-First**: Optimized for deployment in cloud environments. +## 9. [Architecture Decisions](#architecture-decisions) + +### 9.1 Technology Decisions +- **Rust for Performance**: + - Chosen for its memory safety, high-speed execution, and ability to handle concurrent processes efficiently. + - Ensures robust and reliable mediation services in a decentralized environment. + +- **Transport Agnosticism**: + - Supports various communication protocols (e.g., HTTP, WebSocket, and others). + - Designed to integrate seamlessly into diverse ecosystems, enhancing interoperability. + +- **Cloud-First**: + - Optimized for deployment in modern cloud environments. + - Employs containerized solutions (e.g., Docker) and orchestration tools (e.g., Kubernetes) for scalability and ease of maintenance. + + +### 9.2 Architectural Features +- **DIDComm Protocol Implementation**: + - Follows the DIDComm v2 standard for secure and decentralized identity communication. + - Supports encrypted, authenticated, and transport-agnostic messaging. + +- **Scalability and Modularity**: + - Architected to handle growing user and message loads without performance bottlenecks. + - Modular design allows for easy extension of features like advanced message routing or additional protocol support. + +- **Secure Message Mediation**: + - Incorporates robust cryptographic mechanisms to protect sensitive data. + - Ensures confidentiality, integrity, and authenticity in all message exchanges. + +### 9.3 Deployment and Maintenance +- **CI/CD Integration**: + - Automated pipelines for testing, building, and deploying ensure rapid and error-free updates. + +- **On-Premise and Hybrid Support**: + - Though optimized for the cloud, the solution is also adaptable for on-premise deployment. + - Suitable for organizations with strict data sovereignty or privacy requirements. + +- **Logging and Monitoring**: + - Designed to include observability features such as detailed logs and performance monitoring. + - Aids in debugging and enhances operational reliability. + +### 9.4 Future Considerations +- **Additional Protocol Support**: + - Exploring further transport protocols to expand integration capabilities. + +- **Dynamic Scaling**: + - Introducing auto-scaling mechanisms to manage resource usage based on real-time demand. + +- **Advanced Observability**: + - Adding comprehensive monitoring and analytics dashboards to track system performance and detect anomalies. --- -## 10. Quality Requirements + +## 10. [Quality Requirements](#quality-requirements) ### Functional -- Reliable message storage and delivery. -- DID rotation support. +* **Reliable Message Storage and Delivery**: + The system must ensure that messages are stored persistently and delivered reliably to the correct recipient, even in the event of system failures. This includes handling retries, acknowledgments, and maintaining message order. The system should support eventual consistency and be able to recover from intermittent network failures, ensuring that no messages are lost during transmission. + +* **DID Rotation Support**: + The system should support Decentralized Identifier (DID) rotation to ensure secure communication can continue uninterrupted when the keys or identifiers change. This includes the ability to handle key rotation, update trust stores, and ensure that the recipient is aware of the new DID information. Rotation must not disrupt communication, ensuring transparency in key changes and maintaining message integrity through appropriate versioning and key management mechanisms. ### Non-Functional -- **Scalability**: Supports 10,000+ concurrent connections. -- **Security**: Fully encrypted message routing. +* **Scalability**: + The system must be capable of handling a high number of concurrent connections while maintaining performance and reliability. Scalability can be achieved through load balancing, horizontal scaling across multiple servers, and efficient resource management. Techniques such as data partitioning, caching, and asynchronous processing will ensure that the system can handle increased load without performance degradation. + +* **Security**: + All messages must be routed and stored in an encrypted format to ensure the privacy and integrity of the data. The system should comply with established cryptographic standards, using public-key encryption for message transmission and ensuring that keys are securely managed. Additional measures like integrity checks (e.g., HMAC, digital signatures) must be used to protect data from tampering or unauthorized access. The system must also support end-to-end encryption to ensure that only the intended recipients can decrypt the messages, with mechanisms for key revocation and renewal built-in. --- -## 11. Risks and Technical Debt +## 11. [Risks and Technical Debt](#risks-and-technical-debt) - **Risks**: Potential bottlenecks in message pickup under high loads. - **Debt**: Optimization of transport layer abstraction. --- -## 12. Product Management +## 12. [Product Management](#product-management) - **Tech Stack**: Rust, Actix-web, SQLite, Kubernetes. - **Versioning**: Semantic versioning for compatibility. --- -## 13. Glossary +## 13. [Glossary](#glossary) - **DID**: Decentralized Identifier. - **DIDComm**: Messaging protocol for DIDs. - **Mediator**: Intermediary facilitating message delivery.