1. Introduction and Goals
Shmoose is a XMPP client for Sailfish OS. XMPP is an open standard and is using free, open and decentralized servers for communicating with other users. Instead of using 'walled garden' instant messaging solutions to communicate with other users, XMPP is federalized and therefore more resistant to censorship and outage.
Shmoose will enable SailfishOS users to use this ecosystem with all the XMPP features a modern instant messenger should provide today.
1.1. Requirements Overview
This is a list of the high level requirements which must be fulfilled.
-
The client shall be able to provide 1to1 communication
-
The client shall be able to provide 1 to many communication (aka rooms in XMPP)
-
The client shall display the status of a sent message
-
The client shall be able to add, edit and delete contacts
-
The client shall be able to distribute pictures
-
The client shall be able to communicate in a secure manner
-
The client shall support TLS connections to the server
-
The client shall support OMEMO E2EE (end to end encryption)
-
1.2. Quality Goals
Reliability
Each sent message must be guaranteed to be delivered to the receiver. Each received message must be analyzed and processed by the client.
Security
A message must be encrypted to ensure the privacy of the message content. Additional, it must be detected if the message content was altered in any way to fulfill integrity. Authenticity must be ensured to prove the message is from the assumed message partner.
Modularity
Each feature should be loosely coupled to be able to easily exchange the implementation if necessary.
Portability
It should be possible to run the client on the SailfishOS platform as well as on any desktop linux environment.
1.3. Stakeholders
| Role/Name | Group | Expectations |
|---|---|---|
Developer |
github / maemo |
Understanding the structure of the code |
User |
Sailfish Community |
Get into the functionality |
me |
Architect |
Playground to test new stuff |
2. Architecture Constraints
2.1. Organisational
Uncertain number of developers |
As this open source project implements a niche protocol (XMPP) on a niche OS (Sailfish) it’s hardly foreseeable how many contributions would be made |
2.2. Technical
Specific versions of libraries |
The implemented client should be runnable on any Unix like system. But the main target OS would be Sailfish OS. Because of this the Qt Version is currently limited to v5.6 and the C++ standard to C++11 with some parts of C++14 |
3. System Scope and Context
3.1. Business Context
User (Actor)
The user is the person who uses the client to communicate with other users.
Network (Actor)
To communicate with other users, a network is necessary where other users interconnect their clients.
Communicate 1o1
A user is able to make private communication with one other user of the network.
Communicate in group
A user is able to communicate with more then one user at a time. Group communication in the XMPP jargon is done by using rooms.
Send picture
A user is able to send pictures. Either by 1o1 messaging or by group messaging.
Check message status
A user is able to check the status of a message. The status is something like
-
received by server
-
received by client
-
displayed to users
Handle contacts
The user is able to handle contacts. This can be
-
add a new contact
-
edit an existing contact
-
remove a contact
The contacts also have states like
-
online
-
offline
-
subscriptions
3.2. Technical Context
The technical context is straight forward. The client communicates with a XMPP server by using the XMPP protocol via TCP/IP.
4. Solution Strategy
To reduce the workload and boost the quality of Shmoose, the client should be build on already existing and proven components. A XMPP library is used to handle most of the implementation details of the main XEP’s, needed by a modern client. Additional all the encryption stuff will not be implemented from scratch but also used from already existing libraries.
What is leftover to be new developed is the integration between the libraries and the missing XEP’s which are not provided by the library. Also the GUI part must be written from scratch.
4.1. Overview
TODO Map the quality goals to the details
5. Building Block View
The GUI part will be implemented in QML. This allows a loosely coupled graphical interface from the rest of the implementation. On Sailfish OS, there is a proprietary QML extension named silica. This QML extension is not available on other platforms. Because of this, the GUI part has to be developed separately for different target devices which is possible without touching or even recompiling the rest of the source code.
Swiften, the main library used by Shmoose is responsible to handle most of the XMPP protocol details.
Libomemo and axc are used to be able to implement the OMEMO XEP and are mainly responsible to implement the E2E security details.
The client part puts all the pieces together and makes heavy use of the Qt library.
5.1. Whitebox Overall System
The whitebox description will mainly concentrate on the 'Client' part, described in the 'Building Block View'. The used librarys Qt and Swiften are accessed from many components in different classes, wheres libomemo and axc are only used in the accordingly OmemoHandler implementation.
The following diagram is a decomposition of the 'Client' implementation.
The GUI part consists of several QML files, one for each page. It uses a classic Model-View-Controler pattern and will not be discussed in more detail here.
- Motivation
-
The overall client part is seperated in functional parts as well as in implementation of different XEP’s which are not proviced by the swiften library.
- Contained Building Blocks
-
-
base: Implementation of basic functionality like advertising client capabilities or message handling
-
persistence: Implementations to store send and received data
-
xep: Different implementations for missing functionality in the used xmpp library
-
networkconnection: SFOS specific implementation for handling (re)connections on a mobile device
-
contacts: Handling of xmpp contacts (aka roster)
-
room: Implementation for handling and joining groups
-
5.1.1. <Name black box 1>
<Purpose/Responsibility>
<Interface(s)>
<(Optional) Quality/Performance Characteristics>
<(Optional) Directory/File Location>
<(Optional) Fulfilled Requirements>
<(optional) Open Issues/Problems/Risks>
6. Runtime View
6.1. <Runtime Scenario 1>
-
<insert runtime diagram or textual description of the scenario>
-
<insert description of the notable aspects of the interactions between the building block instances depicted in this diagram.>
7. Deployment View
7.1. Production
- Motivation
-
The production deployment is straight forward. All the building blocks compile to one unix elf executable. As a matter of fact, the GUI part will be deployed as plain text QML description files. Shmoose runs direct on the Sailfish OS Smart-phone and has to connect to an external XMPP Server.
7.2. Development and testing
- Motivation
-
With a runnable executable on a desktop environment, one is able to use all the fancy develop and debugging tools. Shmoose is structured in a way that a deployment on any Linux OS is possible.
- Quality and/or Performance Features
-
To be able to use a full featured desktop development system is quit useful to reduce the round trips of coding, building and deploying to the target systems. This also allows to setup a testing system which tests Shmoose on the outer interfaces.
- Mapping of Building Blocks to Infrastructure
-
Two instances of Shmoose are running on the Linux System. On both clients, the GUI part is dropped in favour of a dbus interface. Almost all functionality which was accessible through the GUI is now reachable through the dbus interface. Each clients announce his interface on the dbus session bus. The Testrunner connects to each of the clients interfaces. After that, the Testrunner calls both clients through dbus to connect to the XMPP Server, which also runs on the same Linux System. With this setup, any functionality in a Shmoose client can be triggered and checked for reaction on the other hand side Shmoose client.
8. (Cross-cutting) Concepts
8.1. Dependencies and Modularisation
Each XEP functionality should be implemented in one module. If there are dependencies to other modules, they should be resolved by 'dependency injection'. Instantiation of a class has to be done as deep as possible in the dependency path. The integration of all modules has to be done in one central integration class.
8.2. Persistence
There a different types of persistence data:
-
Configuration
All configuration items are stored in standard unix ini files, abstracted by the Qt system.
-
Messages with meta data
Messages and their meta data are stored in a sqlite3 file. For convenience, a persistence wrapper with a clean C++ interface should be implemented which provides easy access to all necessary functionality.
-
Shared files
Shared media files through the XMPP protocol are stored as received in the file system and folder of the client instance.
8.4. Logging
tbd
8.5. Tests
Each class should have a separat Unit-Test using the Qt test system. Some tests are only meaningful in a combination of more classes or even during message exchange with an other client. To reflect this, integration tests must be applied to cover all the critical parts and functions in an automated way.
10. Quality Requirements and Quality Tree
Refer to 1.2. Quality Goals. This goals will not be detailed any more.
10.1. Quality Scenarios
Pre-Condition: If not otherwise stated, all the described scenarios are online-scenarios.
- Reliability
-
A user wants to send a message to one of his contacts. After composing and sending the message, the status of that message is displayed within 5 seconds.
- Security
-
A user wants to send a message to an other client, which also implements OMEMO E2E Security. After detecting that the other client also supports OMEMO, the client switches automatically to the use of OMEMO Security. This security feature is shown to the user within 2 Seconds.
A user receives an OMEMO encrypted message from an other client. If that messages was altered in any way, which breaks the integrity of that message, a security alterd must be shown to the user within 1 second.
- Modularity
-
A developer wants to add additional functionality to the client. The developer is able to implement the majority of the code in a separate module. The amount of changes to other code parts of the client is limited to instantiation of that module with the needed dependencies achieved by injection.
- Portability
-
A developer wants to port the client to an other operating system. The additional effort is limited to the GUI part with some needed adaptions for the system integration.
11. Risks and Technical Debts
The amount of work to be done is dependent on the right components and library’s which are chosen. There are some technical requirements to be met for each library:
11.1. XMPP Library
Technical requirements:
-
Majority of XEP’s available for a modern XMPP client
-
Actively developed and maintained
-
High qualtity
-
Library authors well known in the XMPP community
-
Modern C++ interface
-
Security features available
-
Open Source
There are a number of xmpp libraries available which are commonly used, such as:
-
libpurple
-
QXmpp
-
Swiften
-
…
After validating some of them, the Swiften library was chosen because it fulfills most requirements. The only thing missing is modern E2E security (OMEMO).
Nevertheless, the risk of a dropped maintenance of this library exists. Even though it is an open source library, there is no guarantee that the authors of that library or someone else from the XMPP community will continue to actively develop it in the future.
11.2. E2E Security Library
Technical requirements:
-
Implementation of OMEMO
-
Actively developed and maintained
-
High qualtity
-
Open Source
Today only a few C libraries exist which match some of these requirements. As for now, the best choice appears to be libomemo. The author develops this library as a base for the lurch plugin, which adds OMEMO support to libpurple.
The integration of this library does not seem to be difficult, but for sure requires some time to get to know all its functions well in order to implement XEP-0384 (OMEMO) in a correct way. Due to the lack of real alternatives, this library was chosen while hoping for sustained and active development and maintenance of it.
12. Glossary
| Term | Definition |
|---|---|
Jabber |
Old name for XMPP |
XMPP |
Extensible Messaging and Presence Protocol |
XEP |
XMPP Extension Protocols / XMPP Extension Proposal Often appended with a specific XEP number by a hyphen, e.g., XEP-0384 for OMEMO. |