[or-cvs] [tor/master] Bless two proposals from Damian Johnson as 172 and 173.
nickm at torproject.org
nickm at torproject.org
Tue Aug 3 17:51:29 UTC 2010
Author: Nick Mathewson <nickm at torproject.org>
Date: Tue, 3 Aug 2010 13:22:34 -0400
Subject: Bless two proposals from Damian Johnson as 172 and 173.
Commit: 9d317e9bb44bc6b458c96da20e691e630fab7acd
(Leaving a gap for the proposal Jake blessed as 171.)
---
doc/spec/proposals/000-index.txt | 4 +
doc/spec/proposals/172-circ-getinfo-option.txt | 138 ++++++++++++++++++++
.../proposals/173-getinfo-option-expansion.txt | 101 ++++++++++++++
3 files changed, 243 insertions(+), 0 deletions(-)
create mode 100644 doc/spec/proposals/172-circ-getinfo-option.txt
create mode 100644 doc/spec/proposals/173-getinfo-option-expansion.txt
diff --git a/doc/spec/proposals/000-index.txt b/doc/spec/proposals/000-index.txt
index 62327a1..a53c7a1 100644
--- a/doc/spec/proposals/000-index.txt
+++ b/doc/spec/proposals/000-index.txt
@@ -91,6 +91,8 @@ Proposals by number:
168 Reduce default circuit window [OPEN]
169 Eliminate TLS renegotiation for the Tor connection handshake [DRAFT]
170 Configuration options regarding circuit building [DRAFT]
+172 GETINFO controller option for circuit information [ACCEPTED]
+173 GETINFO Option Expansion [ACCEPTED]
Proposals by status:
@@ -126,6 +128,8 @@ Proposals by status:
147 Eliminate the need for v2 directories in generating v3 directories [for 0.2.1.x]
157 Make certificate downloads specific [for 0.2.1.x]
166 Including Network Statistics in Extra-Info Documents [for 0.2.2]
+ 172 GETINFO controller option for circuit information
+ 173 GETINFO Option Expansion
META:
000 Index of Tor Proposals
001 The Tor Proposal Process
diff --git a/doc/spec/proposals/172-circ-getinfo-option.txt b/doc/spec/proposals/172-circ-getinfo-option.txt
new file mode 100644
index 0000000..b7fd79c
--- /dev/null
+++ b/doc/spec/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.
+
diff --git a/doc/spec/proposals/173-getinfo-option-expansion.txt b/doc/spec/proposals/173-getinfo-option-expansion.txt
new file mode 100644
index 0000000..03e18ef
--- /dev/null
+++ b/doc/spec/proposals/173-getinfo-option-expansion.txt
@@ -0,0 +1,101 @@
+Filename: 173-getinfo-option-expansion.txt
+Title: GETINFO Option Expansion
+Author: Damian Johnson
+Created: 02-June-2010
+Status: Accepted
+
+Overview:
+
+ Over the course of developing arm there's been numerous hacks and
+ workarounds to gleam pieces of basic, desirable information about the tor
+ process. As per Roger's request I've compiled a list of these pain points
+ to try and improve the control protocol interface.
+
+Motivation:
+
+ The purpose of this proposal is to expose additional process and relay
+ related information that is currently unavailable in a convenient,
+ dependable, and/or platform independent way. Examples of this are...
+
+ - The relay's total contributed bandwidth. This is a highly requested
+ piece of information and, based on the following patch from pipe, looks
+ trivial to include.
+ http://www.mail-archive.com/or-talk@freehaven.net/msg13085.html
+
+ - The process ID of the tor process. There is a high degree of guess work
+ in obtaining this. Arm for instance uses pidof, netstat, and ps yet
+ still fails on some platforms, and Orbot recently got a ticket about
+ its own attempt to fetch it with ps:
+ https://trac.torproject.org/projects/tor/ticket/1388
+
+ This just includes the pieces of missing information I've noticed
+ (suggestions or questions of their usefulness are welcome!).
+
+Security Implications:
+
+ None that I'm aware of. From a security standpoint this seems decently
+ innocuous.
+
+Specification:
+
+ The following addition would be made to the control-spec's GETINFO section:
+
+ "relay/bw-limit" -- Effective relayed bandwidth limit.
+
+ "relay/burst-limit" -- Effective relayed burst limit.
+
+ "relay/read-total" -- Total bytes relayed (download).
+
+ "relay/write-total" -- Total bytes relayed (upload).
+
+ "relay/flags" -- Space separated listing of flags currently held by the
+ relay as repored by the currently cached consensus.
+
+ "process/user" -- Username under which the tor process is running,
+ providing an empty string if none exists.
+
+ "process/pid" -- Process id belonging to the main tor process, -1 if none
+ exists for the platform.
+
+ "process/uptime" -- Total uptime of the tor process (in seconds).
+
+ "process/uptime-reset" -- Time since last reset (startup, sighup, or RELOAD
+ signal, in seconds).
+
+ "process/descriptors-used" -- Count of file descriptors used.
+
+ "process/descriptor-limit" -- File descriptor limit (getrlimit results).
+
+ "ns/authority" -- Router status info (v2 directory style) for all
+ recognized directory authorities, joined by newlines.
+
+ "state/names" -- A space-separated list of all the keys supported by this
+ version of Tor's state.
+
+ "state/val/<key>" -- Provides the current state value belonging to the
+ given key. If undefined, this provides the key's default value.
+
+ "status/ports-seen" -- A summary of which ports we've seen connections
+ circuits connect to recently, formatted the same as the EXITS_SEEN status
+ event described in Section 4.1.XX. This GETINFO option is currently
+ available only for exit relays.
+
+4.1.XX. Per-port exit stats
+
+ The syntax is:
+ "650" SP "EXITS_SEEN" SP TimeStarted SP PortSummary CRLF
+
+ We just generated a new summary of which ports we've seen exiting circuits
+ connecting to recently. The controller could display this for the user, e.g.
+ in their "relay" configuration window, to give them a sense of how they're
+ being used (popularity of the various ports they exit to). Currently only
+ exit relays will receive this event.
+
+ TimeStarted is a quoted string indicating when the reported summary
+ counts from (in GMT).
+
+ The PortSummary keyword has as its argument a comma-separated, possibly
+ empty set of "port=count" pairs. For example (without linebreak),
+ 650-EXITS_SEEN TimeStarted="2008-12-25 23:50:43"
+ PortSummary=80=16,443=8
+
--
1.7.1
More information about the tor-commits
mailing list