Documentation: Design Overview - RetroShare/documentation GitHub Wiki
Most of this page is unfinished
Contents
- Design Document for libretroshare (Overview)
- Introduction
- libretroshare Design Overview
- Design Considerations.
- Architectural Strategies.
- Model / Design.
- Retroshare's Subsystems
- External Interfaces
- Internal Resources
- Configuration.
- Use Cases.
- Low Level Design.
- Transport Layer 1. Introduction / Usage 2. Interface / Exports. 3. Resources. 4. Design / Model 5. Configuration 6. Use Cases / Interactions. 7. References 8. Connection Manager. 9. Introduction / Usage 10. Interface / Exports. 11. Resources. 12. Design / Model 13. Configuration 14. Use Cases / Interactions. 15. References
- Authentication Manager 1. Introduction / Usage 2. Interface / Exports. 3. Resources. 4. Design / Model 5. Configuration 6. Use Cases / Interactions. 7. References
- FileTransfer. 1. Introduction / Usage 2. Interface / Exports. 3. Resources. 4. Design / Model 5. Configuration 6. Use Cases / Interactions. 7. References
- Cache System 1. Introduction / Usage 2. Interface / Exports. 3. Resources. 4. Design / Model 5. Configuration 6. Use Cases / Interactions. 7. References
- Service Layer. 1. Introduction / Usage 2. Interface / Exports. 3. Resources. 4. Design / Model 5. Configuration 6. Use Cases / Interactions. 7. References
- Serialiser 1. Introduction / Usage 2. Interface / Exports. 3. Resources. 4. Design / Model 5. Configuration 6. Use Cases / Interactions. 7. References
- Benefits, assumptions, risks/issues
Design Document for libretroshare (Overview)
Introduction
Retroshare is a decentralised private social networking system. libretroshare provides the whole networking, authentication and service layer, requiring only a GUI to make it fully functional.
libretroshare Design Overview
Design Considerations.
Retroshare is designed to be a communication platform which is:
- secure - all communications are encrypted using standard OpenSSL streams.
- private - you only connect and share information with peers
- decentralised - There is no central server or database to manage either authentication or sharing.
- authenticated - Uses a Web-Of-Trust to ensure that your peers are the right people.
- social network - shares lists of friends of friends, and other information.
It should be able to provide a low level transport for other systems, and work as well as possible in an offline scenario.
Architectural Strategies.
To keep the routing and communication systems as simple as possible, retroshare was designed to create direct Friend to Friend communication channels. This has caused some significant issues - in these modern days of NAT's and virii. How do you connect to a PC behind a firewall?
Network Communications.
RetroShare The networking
This has transfered complexity from the network routing protocols to the Connection Manager.
Offline capabilites
Retroshare makes heavy use of Caches to maintain information when peers are offline.
Other Services.
A very generic Interface is provided to enable future
Model / Design.
Retroshare's Subsystems
There are several main subsystems:
- Transport Layer
- Connection Manager
- Authentication Manager
- Cache System
- FileTransfer
- Service Layer
which are demonstrated on this diagram and described briefly below.
External Interfaces
Retroshare has a quite significant upper layer interface which interacts with the GUI. This interface is split into a series of sub-interfaces, typically one per service. Only the basic interface - required to launch a libretroshare application is described here.
Internal Resources
Configuration.
libretroshare stores it configuration in a series of files. This is typically passed to the library as a 'configuration directory'.
Use Cases.
Low Level Design.
Transport Layer
This is described in more detail in the Transport Layer design document (TODO)
Introduction / Usage
The Transport Layer provides a single secure OpenSSL socket connection to each online peer. All traffic to a peer is sent over this single channel.
The connection is controlled by the Connection Manager.
Interface / Exports.
The transport layer provides basic SendItem() and RecvItem() functionality for any Serialiser Items.
Items to be sent are routed to the peer identified by the PeerId(); Received Items have PeerId() set to their source.
If the peer is offline, then the packets are destroyed. (Unreliable Delivery)
Resources.
Design / Model
See the Transport Layer documentation
Configuration
Use Cases / Interactions.
References
Connection Manager.
Introduction / Usage
The role of the connection manager is to determine which of you friends are online, and establish connections to them - if possible. The Connection Manager, is therefore a key component, and interfaces with the Transport Layer, Authentication Manager. It is responsible for controlling the DHT and UPnP components, and also interacts with the AutoDiscovery Service.
Interface / Exports.
The connection manager Interface is available to all objects in libretroshare. It can be used to add and remove friends and modify their configuration (IP Address etc)
This interface is also exported to the external GUI Interface.
There is also a callback interface that modules can register with, which is called when the state of a peer changes.
Resources.
Design / Model
Configuration
The state of each peer is stored vi p3configMgr interface.
Use Cases / Interactions.
References
Authentication Manager
Introduction / Usage
Validates peer certificates, and ensures that your friends are properly authenticated.
Interface / Exports.
There is a generic p3AuthMgr Interface which is provided to all of libretroshare.
Resources.
- OpenSSL XPGP certificates.
- XPGP KeyRing.
Design / Model
Primarily interfaces with OpenSSL / XPGP_KeyRing.
Configuration
Signed Configuration file contains a list of Authenticated Peer. directory of Certificates
Use Cases / Interactions.
Flow diagrams of how it interacts are useful here.
References
The design should be described in another design document.
FileTransfer.
Introduction / Usage
Overview of purpose and typical usage of this entity.
Interface / Exports.
what interface does this entity expose, and who should be using it
Resources.
what internal data structures, or other entities does this class use or maintain?
Design / Model
What Happens inside the Entity?
Configuration
Internal state? how is it initialised / restored? Can the state / behaviour be controlled by others.
Use Cases / Interactions.
Flow diagrams of how it interacts are useful here.
References
Is this Entity described in other documents (Interactions or More Details),
Cache System
Introduction / Usage
Overview of purpose and typical usage of this entity.
Interface / Exports.
what interface does this entity expose, and who should be using it
Resources.
what internal data structures, or other entities does this class use or maintain?
Design / Model
What Happens inside the Entity?
Configuration
Internal state? how is it initialised / restored? Can the state / behaviour be controlled by others.
Use Cases / Interactions.
Flow diagrams of how it interacts are useful here.
References
Is this Entity described in other documents (Interactions or More Details),
Service Layer.
Introduction / Usage
Overview of purpose and typical usage of this entity.
Interface / Exports.
what interface does this entity expose, and who should be using it
Resources.
what internal data structures, or other entities does this class use or maintain?
Design / Model
What Happens inside the Entity?
Configuration
Internal state? how is it initialised / restored? Can the state / behaviour be controlled by others.
Use Cases / Interactions.
Flow diagrams of how it interacts are useful here.
References
Is this Entity described in other documents (Interactions or More Details),
Serialiser
Introduction / Usage
Overview of purpose and typical usage of this entity.
Interface / Exports.
what interface does this entity expose, and who should be using it
Resources.
what internal data structures, or other entities does this class use or maintain?
Design / Model
What Happens inside the Entity?
Configuration
Internal state? how is it initialised / restored? Can the state / behaviour be controlled by others.
Use Cases / Interactions.
Flow diagrams of how it interacts are useful here.
References
Is this Entity described in other documents (Interactions or More Details),
Benefits, assumptions, risks/issues
any other notes that you think might be important.