diff options
Diffstat (limited to 'doc/spec/proposals/172-circ-getinfo-option.txt')
| -rw-r--r-- | doc/spec/proposals/172-circ-getinfo-option.txt | 138 |
1 files changed, 0 insertions, 138 deletions
diff --git a/doc/spec/proposals/172-circ-getinfo-option.txt b/doc/spec/proposals/172-circ-getinfo-option.txt deleted file mode 100644 index b7fd79c9a8..0000000000 --- a/doc/spec/proposals/172-circ-getinfo-option.txt +++ /dev/null @@ -1,138 +0,0 @@ -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/<Circuit identity>" -- Provides entry for the associated relay - circuit, formatted as: - CIRC_ID=<circuit ID> CREATED=<timestamp> UPDATED=<timestamp> TYPE=<flag> - READ=<bytes> WRITE=<bytes> - - 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. - |