From 03ed3eef0bfa167a335ece190f89f227bfdd01ea Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Tue, 3 Aug 2010 13:22:34 -0400 Subject: Bless two proposals from Damian Johnson as 172 and 173. (Leaving a gap for the proposal Jake blessed as 171.) --- proposals/172-circ-getinfo-option.txt | 138 ++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 proposals/172-circ-getinfo-option.txt (limited to 'proposals/172-circ-getinfo-option.txt') diff --git a/proposals/172-circ-getinfo-option.txt b/proposals/172-circ-getinfo-option.txt new file mode 100644 index 0000000..b7fd79c --- /dev/null +++ b/proposals/172-circ-getinfo-option.txt @@ -0,0 +1,138 @@ +Filename: 172-circ-getinfo-option.txt +Title: GETINFO controller option for circuit information +Author: Damian Johnson +Created: 03-June-2010 +Status: Accepted + +Overview: + + This details an additional GETINFO option that would provide information + concerning a relay's current circuits. + +Motivation: + + The original proposal was for connection related information, but Jake make + the excellent point that any information retrieved from the control port + is... + + 1. completely ineffectual for auditing purposes since either (a) these + results can be fetched from netstat already or (b) the information would + only be provided via tor and can't be validated. + + 2. The more useful uses for connection information can be achieved with + much less (and safer) information. + + Hence the proposal is now for circuit based rather than connection based + information. This would strip the most controversial and sensitive data + entirely (ip addresses, ports, and connection based bandwidth breakdowns) + while still being useful for the following purposes: + + - Basic Relay Usage Questions + How is the bandwidth I'm contributing broken down? Is it being evenly + distributed or is someone hogging most of it? Do these circuits belong to + the hidden service I'm running or something else? Now that I'm using exit + policy X am I desirable as an exit, or are most people just using me as a + relay? + + - Debugging + Say a relay has a restrictive firewall policy for outbound connections, + with the ORPort whitelisted but doesn't realize that tor needs random high + ports. Tor would report success ("your orport is reachable - excellent") + yet the relay would be nonfunctional. This proposed information would + reveal numerous RELAY -> YOU -> UNESTABLISHED circuits, giving a good + indicator of what's wrong. + + - Visualization + A nice benefit of visualizing tor's behavior is that it becomes a helpful + tool in puzzling out how tor works. For instance, tor spawns numerous + client connections at startup (even if unused as a client). As a newcomer + to tor these asymmetric (outbound only) connections mystified me for quite + a while until until Roger explained their use to me. The proposed + TYPE_FLAGS would let controllers clearly label them as being client + related, making their purpose a bit clearer. + + At the moment connection data can only be retrieved via commands like + netstat, ss, and lsof. However, providing an alternative via the control + port provides several advantages: + + - scrubbing for private data + Raw connection data has no notion of what's sensitive and what is + not. The relay's flags and cached consensus can be used to take + educated guesses concerning which connections could possibly belong + to client or exit traffic, but this is both difficult and inaccurate. + Anything provided via the control port can scrubbed to make sure we + aren't providing anything we think relay operators should not see. + + - additional information + All connection querying commands strictly provide the ip address and + port of connections, and nothing else. However, for the uses listed + above the far more interesting attributes are the circuit's type, + bandwidth usage and uptime. + + - improved performance + Querying connection data is an expensive activity, especially for + busy relays or low end processors (such as mobile devices). Tor + already internally knows its circuits, allowing for vastly quicker + lookups. + + - cross platform capability + The connection querying utilities mentioned above not only aren't + available under Windows, but differ widely among different *nix + platforms. FreeBSD in particular takes a very unique approach, + dropping important options from netstat and assigning ss to a + spreadsheet application instead. A controller interface, however, + would provide a uniform means of retrieving this information. + +Security Implications: + + This is an open question. This proposal lacks the most controversial pieces + of information (ip addresses and ports) and insight into potential threats + this would pose would be very welcomed! + +Specification: + + The following addition would be made to the control-spec's GETINFO section: + + "rcirc/id/" -- Provides entry for the associated relay + circuit, formatted as: + CIRC_ID= CREATED= UPDATED= TYPE= + READ= WRITE= + + none of the parameters contain whitespace, and additional results must be + ignored to allow for future expansion. Parameters are defined as follows: + CIRC_ID - Unique numeric identifier for the circuit this belongs to. + CREATED - Unix timestamp (as seconds since the Epoch) for when the + circuit was created. + UPDATED - Unix timestamp for when this information was last updated. + TYPE - Single character flags indicating attributes in the circuit: + (E)ntry : has a connection that doesn't belong to a known Tor server, + indicating that this is either the first hop or bridged + E(X)it : has been used for at least one exit stream + (R)elay : has been extended + Rende(Z)vous : is being used for a rendezvous point + (I)ntroduction : is being used for a hidden service introduction + (N)one of the above: none of the above have happened yet. + READ - Total bytes transmitted toward the exit over the circuit. + WRITE - Total bytes transmitted toward the client over the circuit. + + "rcirc/all" -- The 'rcirc/id/*' output for all current circuits, joined by + newlines. + + The following would be included for circ info update events. + +4.1.X. Relay circuit status changed + + The syntax is: + "650" SP "RCIRC" SP CircID SP Notice [SP Created SP Updated SP Type SP + Read SP Write] CRLF + + Notice = + "NEW" / ; first information being provided for this circuit + "UPDATE" / ; update for a previously reported circuit + "CLOSED" ; notice that the circuit no longer exists + + Notice indicating that queryable information on a relay related circuit has + changed. If the Notice parameter is either "NEW" or "UPDATE" then this + provides the same fields that would be given by calling "GETINFO rcirc/id/" + with the CircID. + -- cgit v1.2.3-54-g00ecf