Bless two proposals from Damian Johnson as 172 and 173.

(Leaving a gap for the proposal Jake blessed as 171.)

1 files changed, 138 insertions, 0 deletions

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/<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.
+