sekift / onionoo Goto Github PK

Onionoo -- A Tor Status Protocol
================================

1  Onionoo overview
-------------------

Onionoo is designed to be easily extensible to other mobile and non-mobile
platforms.  Possible non-mobile platforms include: command-line interfaces
(e.g., arm) that can be extended to display bridge status information;
desktop tray applications or widget that allow monitoring a remote relay
without requiring opening a control port; plugins in social networking
platforms that may encourage friends to run relays or bridges.  These
extensions are out of scope for the initial Onionoo version.

This document describes the initial scope of a mobile application for iOS
and Android and the required Java-based server application.


2  Sample application: Android
------------------------------

2.1  Teaser
-----------

Are you running a Tor relay or bridge to support online privacy and fight
Internet censorship?  Want to check whether your Tor relay or bridge is
running and relaying traffic while you're underway?  Want to show your
friends that you're actively helping people worldwide to defend against
network surveillance and traffic analysis?

The Onionoo Android app enables you to watch any Tor relay or (known) Tor
bridge from your mobile phone.  Onionoo was written with privacy in mind
and only uses publicly available Tor directory data.  Onionoo does not
require access to your relay or bridge.


2.2  User interface
-------------------

The user interface of Onionoo is kept as simple as possible while
providing the relevant information to the user.  The interface consists of
a main screen (see 2.1), two dialogs to add relays (see 2.2) and bridges
(see 2.3), and a yet unspecified relay/bridge details page (see 2.4).


2.2.1  Main screen
------------------

The main screen of Onionoo consists of a list of relays and bridges that
the user selected to monitor.  Each list entry shows the nickname,
fingerprint, online status, uptime, and average bandwidth of a relay or
bridge.

The idea behind making the main screen a list is to encourage users to run
more than "just" a single relay or bridge.

The main screen has a "+" button to add a new relay (see 2.2) or bridge
(see 2.3) to the list.  When the list is empty, it contains a button "Add
new relay or bridge" to add the first relay or bridge to the list.

Every list entry can be annotated by the user, which may be important for
bridges which are otherwise hardly distinguishable.

Obviously, list entries can be deleted to stop monitoring a relay or
bridge.

The main screen uses cached Tor directory information to display the
status of relays and bridges.  This cached information can be updated when
the user chooses to update it and when new information is expected to be
available.  The main screen uses status data that is specifically
downloaded for the monitored relays and/or bridges.  These data need to be
updated once per hour at most, which is the interval of the Tor directory
authorities generating a new network status consensus.

Clicking on a list entry opens the detail page (see 2.4).

Example:
+------------------------------------------+
|                 Onionoo              [+] |
+------------------------------------------+
| gabelmoo                   (green light) |
| 1234 ABCD      3d 14h 22m     800 kbit/s |
+------------------------------------------+
| blutmagie                  ( red light ) |
| FEDC 9876                                |
+------------------------------------------+
| Cloud bridge 1             (green light) |
| ABCD 7667      9d 2h 15m       20 kbit/s |
+------------------------------------------+
|                                          |
                    ...
|                                          |
+------------------------------------------+


2.2.2  Add relay dialog
-----------------------

The add relay dialog is used to add a relay to the main screen.  Relays
can be searched by nickname, fingerprint, or IP address.  Partial input is
allowed for all fields.

Searches are supposed to be very fast and shall not require sending
requests over the network.  Clients shall download a complete list of
relays including their nicknames, fingerprints, and IP addresses when
first opening the add relay screen.  This list contains all relays that
have been running in the last 7 days.  A quick evaluation reveals that
this list would be roughly 200K in size as of October 2011.

+------------------------------------------+
| Add relay                                |
|                                          |
| nickname: ______________________________ |
|                                          |
| fingerprint: ____ ____ ____ ____ ____    |
|                                          |
|              ____ ____ ____ ____ ____    |
|                                          |
| IP address: ___.___.___.___              |
|                                          |
|                 [Search]                 |
|                                          |
| Results:                                 |
|                                          |
| gabelmoo   1234 ABCD   12.34.56.78  (gl) |  (gl) == (green light)
| blutmagie  FEDC 9876   34.56.78.90  (rl) |  (rl) == (red light)
                    ...
|                                          |
+------------------------------------------+


2.2.3  Add bridge dialog
------------------------

The add bridge dialog is used to add a bridge to the main screen.  Bridges
can only be searched by providing the full fingerprint.  The reason for
this requirement is that publicly available data only contain hashed
fingerprints to prevent censors from enumerating bridges.  The full
fingerprint is required to hash the input and look up the bridge.

Similar to relays, searches are supposed to be very fast and shall not
require sending requests over the network.  Clients shall download a
complete list of hashed bridge fingerprints when first opening the add
bridge screen.  This list contains all bridges that have been running in
the last 7 days.

+------------------------------------------+
| Add bridge                               |
|                                          |
| fingerprint: ____ ____ ____ ____ ____    |
|                                          |
|              ____ ____ ____ ____ ____    |
|              (must be specified in full) |
|                                          |
|                                          |
|                 [Search]                 |
|                                          |
| Results:                                 |
|                                          |
| 1234 ABCD    2011-10-19 12:11:15    (gl) |  (gl) == (green light)
|                                          |
+------------------------------------------+


2.2.4  Relay/bridge details page
--------------------------------

The relay or bridge details page lists properties of the relay or bridge
in more detail than the main screen can provide.

The details page displays the more static properties like IP address,
ports, contact information, or flags assigned by the directory authorities
(only for relays) as well as the more dynamic properties like uptime,
bandwidth, and daily connecting users by country (only for bridges).

The details pages may also include output from Tor-related services like
the bandwidth scanners, the exit address scanner, and bridge pool
assignments.

The more dynamic properties may also be visualized over time and in
comparison to other relays or bridges.  For example, the provided
bandwidth may be displayed as a time plot or in an empirical cumulative
distribution function in comparison to other relays or bridges.  Users by
country on the last day may be visualized in a pie plot.

The exact look of the relay or bridge details page is yet unspecified.


3  Sample application: TorStatus
--------------------------------


4  Server and protocol
----------------------

Onionoo consists of a server application that downloads status information
from the Tor servers and preprocesses them for transfer to the mobile
client applications.  The Onionoo protocol between client and server is
designed to save bandwidth and reduce roundtrips as much as possible.  The
server downloads new Tor directory information once every hour and
provides it in four data formats: relay search data (see 3.1), bridge
search data (see 3.2), relay status data (see 3.3), and bridge status data
(see 3.4).


4.1  Relay search data
----------------------

The relay search data format comprises all information about relays that
have been running in the past 7 days that is required to search for relays
and add them to the watch list.  Clients download the full list of relays
and cache them locally when searching for relays.  These data only change
once per hour when the directory authorities generate a new network status
consensus.  The relay search data format does not contain any status
detail information about relays which needs to be downloaded separately
(see 3.3).

The relay search data format is text-based.  Documents start with a
"relay-search-data" line, followed by zero or more "r" lines.  SP stands
for space, NL for newline.

"relay-search-data" SP version NL

version is a number starting at 1.  The server must support all
non-deprecated versions.  Clients provide the highest understood version
number and should understand all non-deprecated versions up to that
version.

"r" SP nickname SP fingerprint (SP last-restart)? (SP ip-address)+ NL

nickname is the relay nickname consisting of 1 to 19 characters or
numbers.

fingerprint is the relay fingerprint consisting of 40 upper-case hex
characters.

last-restart is the UTC timestamp when the relay was last restarted,
formatted as YYYY-MM-DD HH:MM:SS.  Omitted when the relay is currently not
running due to the directory authorities.

ip-address is an IPv4 address in dotted notation where the relay listens
for OR connections or that the relay uses for exiting to the Internet.
There can be one or more ip-address per relay.

An early calculation shows that a relay search data document in October
2011 would contain 5141 relays.  The uncompressed file size is 367K,
gzip-compressed 200K.

It is conceivable to move the search function to the server at the cost
of higher latency for single searches and higher server load.  However,
this extension is out of scope of this initial version.


4.2  Bridge search data
-----------------------

The bridge search data format comprises information about bridges that
have been running in the past 7 days that is required to search for
bridges by hashed fingerprint and add them to the watch list.  Clients
download the full list of bridges and cache them locally when searching
for bridges.  These data only change twice per hour when the bridge
authority writes a new bridge network status.  The bridge search data
format does not contain any status detail information about bridges which
needs to be downloaded separately (see 3.4).

The bridge search data format is text-based, too.  Documents start with a
"bridge-search-data" line, followed by zero or more "r" lines.

"bridge-search-data" SP version NL

version is a number starting at 1.  The server must support all
non-deprecated versions.  Clients provide the highest understood version
number and should understand all non-deprecated versions up to that
version.

"r" SP hashed-fingerprint (SP last-restart)? NL

hashed-fingerprint is the hashed bridge fingerprint consisting of 40
upper-case hex characters.

last-restart is the UTC timestamp when the bridge was last restarted,
formatted as YYYY-MM-DD HH:MM:SS.  Omitted when the bridge is currently
not running due to the bridge authority.


4.3  Relay status data
----------------------

The relay status data contains status information about a single relay
that a client selected to monitor.  Relay status data documents can be
downloaded from the server for one or more relays in a single request.

The relay status data format is yet unspecified.


4.4  Bridge status data
-----------------------

The bridge status data contains status information about a single bridge
that a client selected to monitor.  Bridge status data documents can be
downloaded from the server for one or more bridges in a single request.

The bridge status data format is yet unspecified.