Skip to content
This repository has been archived by the owner on Jan 2, 2020. It is now read-only.

Pixelated Component Architecture

Jump to bottom
Sriram Viswanathan edited this page Apr 27, 2017 · 9 revisions

Main Components

There are two sides to Pixelated -

  • 'Provider'
  • 'User-Agent'

These two sides work together to give the user a seamless mail experience that always holds any mails (at rest or in transit) in encrypted form. The fundamental rule that is followed is that, without the user logging in with their password, no one else (including the server) can read the emails.

Provider

The 'Provider' is based on the Leap platform. The Provider consists of the following components -

  • 'Postfix' mail receiver - receive email from external provider and store it on disk
  • 'Leap MX' - watch for incoming mails in local directory & encrypt using public key of the user -> store in couchdb in encrypted form - public key is fetched with the 'keymanager' using 'Nickserver' to map user to their keys
  • 'Soledad' - this is the main server component thats responsible for synchronization of encrypted documents between server and client(s)
    • There are two parts - client & server.
    • Both client & server have the common responsibility of storing & retrieving locally stored docs.
    • U1db is the protocol that is used to synchronize documents between the server & the client(s)
    • The client is tied to a SQLCipher database which is a flavor of SQLite providing encryption capabilities.
    • The server is tied to a CouchDB database.

Client

The Client consists of the following components -

  • 'Pixelated User-Agent' - this is the webapp component that is written in Python and FlightJS. However, newer components are being written in ReactJS, as FlightJS is now deprecated.
  • 'Bitmask Client' - this is mainly responsible for mediating between the user-agent & the 'server' and as such responsible for handling requests from the user-agent, including in sending and reading emails, as well as dealing with authentication. It is essentially stateless in nature and doesn't maintain anything like a user 'session'.

In terms of dependencies, the user-agent is dependent on the bitmask-client and in-turn on the soledad-client library for its operation. This dependency on the soledad-client is for interactions with the local SQLCipher storage and also the interactions with the soledad-server.

Who maintains the user's session and user details?

This part is handled by the webapp or the leap_web part of the code base, who's basic goal is to offer a stateful-session based HTTP interface for update of the user details including account details (password, recovery-code) and basically account management as a responsibility.

Component Diagram

Component Diagram

The flow of an incoming email in this diagram is from left to right. The only time when the email remains 'unencrypted' briefly is when its received from the external service by Postfix and put on the disk. The LeapMX service is responsible for polling the disk and immediately encrypt the user's email using the user's public key thats fetched from the Nickserver.

From this point onwards, the email remains encrypted. It can only be decrypted once the user authenticates by logging in and allowing the on-the-fly decryption in-memory and inside the user's authenticated session of the emails that are either present in the local SQLCipher database i.e. they have already been downloaded to the local storage or are fetched from the soledad-server to be stored locally for fast access.

Concept of Secrets

Every user has a file called a secrets file that is basically a CouchDB document, that contains the private key of the user which has been encrypted with the user's password or the recovery-code. This is so that only the user, after authenticating, can unlock their private key, which then allows the user to fetch and view the emails.

For more information on how this works, 'Soledad' documentation explains it thoroughly.

Flow of control when logging in and reading the email

  1. User arrives at the Pixelated user-agent website's login page.
  2. Enter the username/password -
    1. This username/password combination is then subject to a Secure Remote Password based handshake and authentication mechanism. This involves the bitmask-client talking to the leap_web component and negotiating the user's credentials and finally coming up with a token and salt that is used to validate each HTTP request.
    2. Depending the request, we now delegate the request to bitmask-client (and to soledad-client) or to leap_web.
  3. Every request from now on is subject to the user's SRP session being valid (valid token & salt).

__

Clone this wiki locally