Control Spec Addition First Draft

Hi Roger. Here's the first draft of the proposed additions to address the arm
wishlist. To start with:
- What more would be useful? I don't do core tor development nor analysis like
Karsten so I'm not sure what you'd like from a monitor for debugging or
network examination. One thought might be a GETINFO option for getting log
entries related to a given connection (would be especially interesting in
case investigating circuit extension failures and such). Probably not
possible since it would require tor to remember log data...

- Comments like "Wtf? That's utterly useless/wrong!" appreciated! I've naively
included included some things that might not be helpful (like the 'e/E' flag
to indicate if connections are encrypted), not to mention mistakes thanks to
a not-quite-so-perfect understanding of networking, tor, and writing specs.

- Anything dangerous? Doubt it, but the bandwidth measurements should probably
either be rounded or provided occasionally (say, every second) to address
correlation attacks. I'm sure Sebastian will enthusiastically sink some
paranoia into this later. ;)

- Should we document how frequently the connection data is updated or have some
'last updated time' parameter?

- When hosting hidden services I'd imagine some connections are dedicated to
them. If so, lets add a flag to indicate them.

Cheers! -Damian

-------------------------------------------------------------------------------

The following is a proposal for additions to the control-spec's GETINFO
parameters to reveal additional information related to tor connections and
circuits. The intention is to provide a viable alternative to netstat and lsof
for discovering these stats with the following benefits:

- Performance
Frequently querying this information via external tools has a significant
overhead (especially for busy relays). Tor already has this information cached
so being able to fetch it via the control port would introduce significant
performance benefits for monitoring tools like arm.

- Authoritative
How does tor view the world? An external perspective of how tor is utilizing
network resources is interesting, but from an auditing perspective it's even
more interesting if this can be used to validate tor's internal accounting.

- Additional Information
While we can infer some information like the connection type and corresponding
relay from raw connection data, it would be a lot nicer (and more accurate) to
not need to guess. Providing additional information (like per-connection
bandwidth or buffer usage) might also be interesting, assuming we can do so
safely.

Most of this information is already available to relays (both benign and
malicious), but if you spot some troubling privacy implication then please
speak up! Nothing here should end the world, but we certainly don't want to
make things easier for not-so-well-meaning people.

-------------------------------------------------------------------------------

"conn/<Connection identity>" -- Provides entry for the associated
connection, formatted as:
CONN_ID CIRC_ID OR_ID IP PORT TYPE_FLAGS READ WRITE UPTIME BUFF

none of the parameters contain whitespace, and additional results must be
ignored to allow for future expansion. Parameters are defined as follows:
CONN_ID - Unique identifier associated with this connection.
CIRC_ID - Unique identifier for the circuit this belongs to (0 if this
doesn't belong to any circuit). At most their may be two connections
(one inbound, one outbound) with any given CIRC_ID.
OR_ID - Relay fingerprint, 0 if connection doesn't belong to a relay.
IP/PORT - IP address and port used by the associated connection.
TYPE_FLAGS - Single character flags indicating directionality and type
of the connection (consists of one from each category, may become
longer for future expansion).
I: inbound, i: listening (unestablished inbound),
O: outbound, o: unestablished outbound
C: client related, R: relay related, X: control, D: directory
T: inter-tor connection, t: outside the tor network
E: encrypted traffic, e: unencrypted traffic
For instance, "IRtE" would indicate that this was an established
1st-hop (or bridged) relay connection.
READ/WRITE - Total bytes read/written over the life of this connection.
UPTIME - Time the connection's been established in seconds.
BUFF - Bytes of data buffered for this relay connection.

"conn/all" -- Newline separated listing of all current connections.

"info/relay/bw-limit" -- Effective relayed bandwidth limit (currently
RelayBandwidthRate if set, otherwise BandwidthRate).

"info/relay/burst-limit" -- Effective relayed burst limit.

"info/relay/read-total" -- Total bytes relayed (download).

"info/relay/write-total" -- Total bytes relayed (upload).

"info/relay/buffer-cap" -- Maximum buffer size for relay connections.

"info/uptime-process" -- Total uptime of the tor process (in seconds).

"info/uptime-reset" -- Time since last reset (startup or sighup signal, in
seconds).

"info/descriptor-used" -- Count of file descriptors used.

"info/descriptor-limit" -- File descriptor limit (getrlimit results).

"ns/authority" -- Router status info (v2 directory style) for all
recognized directory authorities, joined by newlines.