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.

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.

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 u

Onionoo

Install / Use

README