From Kolab Wiki

Conceptual description

Image #SSA_0a.jpeg shows an exemplary setup for a single-machine setup without persistent cache using a per-user SQLite in-memory cache within Akonadi. Image #SSA_0b.jpeg shows the next stage with a persistent cache that can handle multi-threading in the Akonadi infrastructure & allows distribution of IMAP & SQL over different machines.

All clients running on the same host allows them to access the Akonadi Control Server (ACS) directly through a local socket where the user id is mapped to an Akonadi Server of which there is one per user regardless of the number of clients connected by the user, so the clients share the cache & connections.

The ACS is responsible for executing an Akonadi Server along with all its agents per user. Afterwards it proxies the client connections through to the local socket with the respective Akonadi Servers. All other communication with the Akonadi Servers and the Agents, as well as between the Akonadi Server and its Agents, is limited to command, control & notification messages sent via dbus. This dbus is shared between all Akonadi components on the host, and is also where Akonadi Agents request their passwords from the Akonadi Control Server.

Why is match & proxy required?
For most web clients, the connections are non-persistent between user interactions. E.g. an operation by the user causes Roundcube to be started fresh, get all data it needs for the operation, and then shut down with the Apache web server re-using this thread for another purpose. So without user id / session matching, an ongoing Roundcube session would be unable to find the correct Akonadi Server again.

Implementation of the Akonadi Control Server
The Akonadi Control Server will be the only part of the caching nodes exposed to the network, and thus would be the first and obvious vector of attack against these nodes. Also, it will be managing passwords & keys for communication (see below). So it must be written with great care and attention to security. All code must be thoroughly written knowing that this will be attacked at some point.

Because dbus itself is not cryptographically secured, the Akonadi Control Server creates public/private key pairs for itself and each Akonadi component it launches. The private and public key of the child process and the public key of the ACS are handed over during launch, the private key of the child process is then forgotten by the ACS, while the public key is stored for future communication with this particular instance of the agent. All messages to the ACS should at least be signed for verification by the ACS, all messages by the ACS to the child processes, especially passwords and other confidential data, should be encrypted.

Why is cryptography required on dbus?
While dbus allows direct process to process communication, much of the communication in Akonadi is of broadcast type. Encryption serves the purpose of securing the message in transport, especially where it contains passwords, and to ensure that only the intended recipient can decrypt the message. That said, it could become part of a later milestone, depending on the timeline.

An open question for dbus
Since dbus was written as desktop technology, it's ability to deal with thousands of processes and large number of messages per second has never been tested. Questions are: What are its limits? How does it fail? The reason it makes sense to try whether dbus will be capable of handling this scenario is that usage of dbus is considered an explicit Akonadi design decision and would require a substantial amount of change on the servers and each agent to change. Also, we'd prefer not to require AMQP for the simplest of setups. That said, if we find dbus is insufficient, we may have to move to AMQP from the start and modify more Akonadi code than initially hoped for.

In order to be able to provide the IMAP password to the agent, the password is stored encrypted to the key of the ACS itself, all password, key and uid to Akonadi instance mapping databases are exclusively kept in memory.

Why are passwords stored in ACS?
Some Akonadi agents needs access to passwords occasionally, e.g. when there was a disconnect, or when the agent had died and gets restarted, at which point in time it is not guaranteed that a client will be connected to supply the credentials. This is also the reason why the password cannot be stored in the agent. In fact the agent should not store the password so it needs authorization from the ACS to reconnect to the server, which can also help with process control to ensure an agent becomes inactive and dies when required.

This requires two modifications in the Agents & Akonadi Server Code:

Password handling: Currently done through kconfig, which will not be available on server, needs to be made to work with dbus + crypto setup.
Multi-user setup: dbus communication currently assumes single user situation, so must receive additional instance/session information.

These can be done in ways that a single source code repository can be used to compile server side and client side Akonadi server and agents, but for the Akonadi Control Server the situation is a bit more complex because it needs to do various things that are unnecessary on the desktop, such as:

Map between different client sessions of a single user and the corresponding Akonadi Server and proxy the payload connection based on the Akonadi Server Access Protocol (ASAP) language based on a socket connection;
Do the same based on a network connection listening on a network port (see picture #SSA_1a.jpeg). In this scenario, like in all others, the ACS is still proxying the ASAP protocol access to the right Akonadi Server over a local socket;
Listen and respond on an AMQP message bus for requests to provide the right host & Akonadi Agent for multi-server Akonadi setups (see picture #SSA_2a.jpeg);
Handle key & password storage;
Handle termination of Akonadi Servers & Agents after a timeout period.

Some security considerations
The connections between IMAP & Akonadi IMAP agent are secured by TLS & fully authenticated. The connection between the server side client and the Akonadi Control Server is either through a local socket, or secured by TLS/SSL. The connection between Akonadi Control Server, of which there is one per Akonadi Host, and Akonadi Servers is always through local sockets, as is the connection between an Akonadi Server and its Agents. The messaging buses are either cryptographically secured by protocol (AMQP), or strictly local without outside connection and cryptographically secured in the payload (dbus). All passwords are kept encrypted in memory only.

Naturally, once an AMQP message bus is deployed as part of the setup, it might also be used to have true real-time updates & push based upon notifications from the Cyrus IMAP Daemon (see picture #SSA_2b.jpeg).

On the client side, this complexity is abstracted from the client through the libacsclient, which primarily acts as a brokering library for the clients, written in C++ and wrapped in SWIG for various language bindings. This library is configured to (a) connect to a local socket, (b) connect to a remote port, or (c) request existing/new sessions from an AMQP message bus, depending on the scenario and setup. The client does not need to know which is the setup in place, as it is interfacing only with an API that allows it to request a new session or re-open an existing session, providing it with a command interface that will allow it access to the Akonadi Server regardless of where that server is.

Later this brokering library can also be performance tuned to pull data out of IMAP directly instead of going through Akonadi for some requests, e.g. fetching an email with a large attachment, so it does not have to be pulled through the entire Akonadi stack (see picture #SSA_2c.jpeg).