Architecture
For a glossary of terms refer to Glossary
Globaleaks is a project aimed at creating a technology that enables anyone, even not technically skilled, to setup a whistleblowing platform. GlobaLeaks, from now on GL, is built from the groud up with security and privacy by default.
The audience of this document is mainly of two kinds: the newcomer and the globaleaks developer (hopefully the first will become the second). For the newcomer this document will serve as an introduction to the concepts inside of globaleaks and help them understand how the system is structured and how the parts interact with one another. For the globaleaks developer this document servers as a guide when implementing as well as a means of splitting the task of writing globaleaks into implementation units.
In this section we will illustrate from a birds-view the main modules of GlobaLeaks and how they depend from each other.
The two main Modules are GLBackend and GLClient.
GLBackend will run on the machine hosting the GlobaLeaks service. GLClient is the client interface to the system. The goal of GLBackend is to securely and anonymously acquire submissions from whistleblowers and deliver them to knowledgable receivers. The goal of GLClient is that of allowing a whistleblower to notify the chosen set of receivers (groups) of some malpractice. They do so by filling out a form and uploading some files.
The backend exposes a REST API that allows the client Module to interact with the GlobaLeaks system. A detailed specification of the REST API is available here This is the only link that exists between GLBackend and GLClient, this is to allow changes in the client side to affect the backend as long as the REST API remains coherent.
The other reason for isolating the client logic from the backend logic is to have a well defined signaling system between client and server providing greater levels of security (more on this in the GLClient section).
The REST API dialogues with the Submission Module and the Administration module. The submission module is accessible by any client, even non authenticated, while the Administration module requires authentication.
The delivery and notification system are used to inform a receiver that new information is present on the globaleaks node and to deliver them the content of such information. They are meant to be extensible, this means that a third party developer should be able to develop their own custom delivery and/or notification system. The reason for grouping them into one module is that the requirements of delivery and notification and delivery are the same. A notification and delivery event needs to be created for every new submission. Mechanisms of retry need to be implemented for both and they are mapped 2-to-one with every receiver.
The Storage and Database system is used for keeping all the data models and files required for the running of the node. This system is configured through the administration module.
The Tip interface serves the purpose of providing a central place for allowing whistleblower-receiver meeting. If the receiver does not have a delivery method configured then this system will handle also the delivery of the data to the receiver.
This interface enables a client to load a submission onto the GL node. Through this component the client application learns what fields are supported by the globaleaks nodes and its properties.
The submission system has anti-spam features allowing to configure a captcha that is activated once a certain submission/time threshold is reached.
This is the contextual data associated with a submission. The fields are fetched though an API that tells the client what their names are and what is the description. The client will optionally send the submission identifier that has been generated in the material upload phase.
Though this interface material can be loaded on the Node and associated with a submission. If a submission id is not supplied the application will generate a submission identifier, that is then sent once the submission fields are sent. The data sent to the GL Node will be encrypted client side with an asymetric crypto system.
GlobaLeaks should support various different storage mechanisms The storage interface should be designed in a way that it is agnostic to the underlying system that will be used to save the information. If specified the node administrator should be able to configure that the infomration stored on the node is encrypted with his symetric key or the public keys of all the receivers.
Possible storage systems that should be implemented are: Locally to drive, SCP, online file storage services, tahoe-lafs.
This is the page that keeps track of a client submission. Is enables
both Receivers_ and WB to access a submission that is present on
a GL Node. This interface will return the list of fields with
their value. This page will also be called Tip.
Each Tip also has a comment board that allows secure communication
between the Receivers_ and the WB. The Receiver_ can use this to get
extra information on the submission and prompt the WB to upload new
material.
Every time a Receiver_ visits a Tip page and downloads some material
the view and download counters are incremented. It is possible to
interrogate to get a list of views for every Receiver_ from any
authenticated Receiver_ Tip page.
A Receiver_ is able to delete any Tip associated with his profile.
When all the Receivers_ have deleted there Tips or all of them have
expired the material is removed and the database in cleaned of the
submission entry.
TODO.
The notification and delivery system is built to be modular. Notification and delivery systems are configured and setup by the node administrator. Once the delivery of the submission is completed the notification of it is fired and put into the notification queue. The notification queue can either be flushes immediately (if the receiver is configured to receive real-time notifications) or after a certain threshold is reached (if the receiver has been configured to receive notification digests).
The UI should be a separated component that is able to hook up the GL backend. The main UI will be developed in JavaScript and it will allow for WB to securely submit data.
Note: this is just a copy in date 30-01-2012 of the document present on the etterpad https://piratenpad.de/p/AnonymousWebApplicationFramework. Look at the etterpad for the updated version of this doc.
The anonymous web application framework goal is to provide a web application environment that automatically publish itself to the Tor network as a Tor Hidden Service.
The framework allow to build Python Tornado-based Web Application deliverying the apps as a Desktop Application (Program.exe / Program.app) or as a Nix package, so that it would extremely reduce the complexity to "run a server anonymously", even on a PC at home.
That way it would be possible to easily build app web application that run on self-contained webserver that got automatically published anonymously as Tor Hidden Services, without the need to have a public ip address, buy a server or a domain.
The framework contain built-in and self-contained all the technologies required:
- Python
- Tor
- TornadoWeb
An ONG would like to easily setup a Whistleblowing site on it's own pc at office by using the framework integrated version of GlobaLeaks http://globaleaks.org . A private person in a sensitve environment may deploy a temporary web chat application running on it's Windows PC, exposed via Tor Hidden Service, to handle sensitive untraceable encrypted chat. A group of person would like to setup an email-server on Tor Hidden Service running the server at-home of one of the group on it's macintosh by using the framework integrated version of http://lamsonproject.org by developing also a simple tornadoweb based management application.
- First Startup Procedure
The first time the application starts it must uncompress itself and
create the directory structure it need to operate.
It may be required to execute specific scripts and/or other software
to adjust system config, so the startup procedure must allow to easily
add custom scripts.
The application automatically setup the appropriate configuration
files for the applications built-in (Tor, TornadoWeb, TornadoWeb
Applications).
- Splash Screen
```````````````
The application at startup display a splash screent hat contain a
progressbar with the startup information.
The image of the splash screen must be of ease modification (it
may be a PE32 resources on windows, or a file on MacOSX/Linux) or change.
- Database initialization
The first time the application start, it must initiatlize the database with the application schema and initialization data provided with the build-system.
Default Web Application The default web application built within the Anonymous Web Application framework include several functionalities available trough a minimalistic web interface:
- Tor Hidden Service Setup
GlobaLeaks relies on Tor Hidden Services for exposing itself to the internet.
Tor can be configured to automatically create a Tor Hidden Service at startup.
The web application automatically detect if Tor has properly setup a Tor Hidden
Service and read it's .onion domain name.
- Tor Startup
`````````````
The application let the user to see the status of Tor, to stop/start/restart it
- Tor Configuration
```````````````````
The application let the user edit the default Tor configuration file, save it.
- Tor Hidden Service reachability test
The application let the user check if the Tor Hidden Service is properly reachable by making a an outgoing connection and seeing as a Tor client that the Tor Hidden Service is working properly (make sure that the Tor HS is published to the DA, by default this is done every 10 minutes, but can be tweaked to be less).
- Tor2web publishing
Tor Hidden Services are automatically exposed trough the internet by the Tor2web project
(http://www.tor2web.org).
The node by default is automatically exposed to via Tor2web, must it must be possible to
disable inbound connection coming from Tor2web.
The web application let the user to disable/re-enable inbound connections via Tor2web.
Tech: This can be done by looking at the X-Tor2web: HTTP header
- Configure Bind Address
The application let the user define the bind address of the application. By default the application only bind to 127.0.0.1 but it may be possible to bind it also on other IP address or 0.0.0.0 .
- User interface
The status of the node and the setup procedure should be configurable from a user interface.
We should figure out the best way to present this, but at least insert into the application
logic the fact that the user will be guided through
a wizard to setup their node. They will also be shown the current status of the node.
- Browser Startup
The application when started and initiatlized must automatically open the system browser on http://localhost:8080 (or other port where the tornadoweb listen)
Outbound Connection Torrification
The framework must automatically provide support to make anonymous outbound connection via Tor.
The entire web application framework (Tornadoweb) should be forbidden to make any outbound
connections directly and have all connections automatically torrified.
A possible approach would be to directly override DNS Resolution and TCP outbound socks of
Python interpreter using torsocks on Linux/OSX and torcap/freecap on Win32.
Torcap: http://www.freehaven.net/~aphex/torcap/
Freecap: http://www.freecap.ru/eng/
TorSocks: http://code.google.com/p/torsocks/
note: It probably may require some specific win32 coding in order to make the Python32.exe
to have torrified dns-query/tcp-sockets automatically.
Reduced Privileges for Tornadoweb
The application should start TornadoWeb (it will be tornado based web app) with reduced priviledges using the native provided functionalities to restrict the application. Win32: TODO: what can we use??? OSX: Sandbox Linux: AppArmor profile?
The build system must be configurable and should allow easy configuration of the main behavior and:
- third party application dependancy (es: Tor, p7zip, gpg)
- python libraries application dependancy (es: socksify)
The build system must be as cross-platform as possible and must be able to deliver self-contained installable packages for:
-
Win32: MyApplication.exe
-
OSX: MyApplication.app (inside an Application.dmg container)
-
Linux: Deb build
-
Win32 Builder
Related links of possible base framework to use:
-
Mac OS X Builder
On OSX it should be a self contained MyApplication.app with inside the python interpreter. Possible projects to look at are: py2app - http://svn.pythonmac.org/py2app/py2app/trunk/doc/index.html
- Tor downloader The buildsystem should download latests release of Tor for the appropriate platform and extract the required files into the build structure, in order to be packaged within the application.
The Anonymous Web Application Framework must provide detailed documentation on:
- how to setup the build environment (eventually on multiple operating system)
- how to customize your own enviroment for your own anonymous web application
- any specific documentation on particular procedures and/or internal structure