172-circ-getinfo-option.txt 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138
  1. Filename: 172-circ-getinfo-option.txt
  2. Title: GETINFO controller option for circuit information
  3. Author: Damian Johnson
  4. Created: 03-June-2010
  5. Status: Accepted
  6. Overview:
  7. This details an additional GETINFO option that would provide information
  8. concerning a relay's current circuits.
  9. Motivation:
  10. The original proposal was for connection related information, but Jake make
  11. the excellent point that any information retrieved from the control port
  12. is...
  13. 1. completely ineffectual for auditing purposes since either (a) these
  14. results can be fetched from netstat already or (b) the information would
  15. only be provided via tor and can't be validated.
  16. 2. The more useful uses for connection information can be achieved with
  17. much less (and safer) information.
  18. Hence the proposal is now for circuit based rather than connection based
  19. information. This would strip the most controversial and sensitive data
  20. entirely (ip addresses, ports, and connection based bandwidth breakdowns)
  21. while still being useful for the following purposes:
  22. - Basic Relay Usage Questions
  23. How is the bandwidth I'm contributing broken down? Is it being evenly
  24. distributed or is someone hogging most of it? Do these circuits belong to
  25. the hidden service I'm running or something else? Now that I'm using exit
  26. policy X am I desirable as an exit, or are most people just using me as a
  27. relay?
  28. - Debugging
  29. Say a relay has a restrictive firewall policy for outbound connections,
  30. with the ORPort whitelisted but doesn't realize that tor needs random high
  31. ports. Tor would report success ("your orport is reachable - excellent")
  32. yet the relay would be nonfunctional. This proposed information would
  33. reveal numerous RELAY -> YOU -> UNESTABLISHED circuits, giving a good
  34. indicator of what's wrong.
  35. - Visualization
  36. A nice benefit of visualizing tor's behavior is that it becomes a helpful
  37. tool in puzzling out how tor works. For instance, tor spawns numerous
  38. client connections at startup (even if unused as a client). As a newcomer
  39. to tor these asymmetric (outbound only) connections mystified me for quite
  40. a while until until Roger explained their use to me. The proposed
  41. TYPE_FLAGS would let controllers clearly label them as being client
  42. related, making their purpose a bit clearer.
  43. At the moment connection data can only be retrieved via commands like
  44. netstat, ss, and lsof. However, providing an alternative via the control
  45. port provides several advantages:
  46. - scrubbing for private data
  47. Raw connection data has no notion of what's sensitive and what is
  48. not. The relay's flags and cached consensus can be used to take
  49. educated guesses concerning which connections could possibly belong
  50. to client or exit traffic, but this is both difficult and inaccurate.
  51. Anything provided via the control port can scrubbed to make sure we
  52. aren't providing anything we think relay operators should not see.
  53. - additional information
  54. All connection querying commands strictly provide the ip address and
  55. port of connections, and nothing else. However, for the uses listed
  56. above the far more interesting attributes are the circuit's type,
  57. bandwidth usage and uptime.
  58. - improved performance
  59. Querying connection data is an expensive activity, especially for
  60. busy relays or low end processors (such as mobile devices). Tor
  61. already internally knows its circuits, allowing for vastly quicker
  62. lookups.
  63. - cross platform capability
  64. The connection querying utilities mentioned above not only aren't
  65. available under Windows, but differ widely among different *nix
  66. platforms. FreeBSD in particular takes a very unique approach,
  67. dropping important options from netstat and assigning ss to a
  68. spreadsheet application instead. A controller interface, however,
  69. would provide a uniform means of retrieving this information.
  70. Security Implications:
  71. This is an open question. This proposal lacks the most controversial pieces
  72. of information (ip addresses and ports) and insight into potential threats
  73. this would pose would be very welcomed!
  74. Specification:
  75. The following addition would be made to the control-spec's GETINFO section:
  76. "rcirc/id/<Circuit identity>" -- Provides entry for the associated relay
  77. circuit, formatted as:
  78. CIRC_ID=<circuit ID> CREATED=<timestamp> UPDATED=<timestamp> TYPE=<flag>
  79. READ=<bytes> WRITE=<bytes>
  80. none of the parameters contain whitespace, and additional results must be
  81. ignored to allow for future expansion. Parameters are defined as follows:
  82. CIRC_ID - Unique numeric identifier for the circuit this belongs to.
  83. CREATED - Unix timestamp (as seconds since the Epoch) for when the
  84. circuit was created.
  85. UPDATED - Unix timestamp for when this information was last updated.
  86. TYPE - Single character flags indicating attributes in the circuit:
  87. (E)ntry : has a connection that doesn't belong to a known Tor server,
  88. indicating that this is either the first hop or bridged
  89. E(X)it : has been used for at least one exit stream
  90. (R)elay : has been extended
  91. Rende(Z)vous : is being used for a rendezvous point
  92. (I)ntroduction : is being used for a hidden service introduction
  93. (N)one of the above: none of the above have happened yet.
  94. READ - Total bytes transmitted toward the exit over the circuit.
  95. WRITE - Total bytes transmitted toward the client over the circuit.
  96. "rcirc/all" -- The 'rcirc/id/*' output for all current circuits, joined by
  97. newlines.
  98. The following would be included for circ info update events.
  99. 4.1.X. Relay circuit status changed
  100. The syntax is:
  101. "650" SP "RCIRC" SP CircID SP Notice [SP Created SP Updated SP Type SP
  102. Read SP Write] CRLF
  103. Notice =
  104. "NEW" / ; first information being provided for this circuit
  105. "UPDATE" / ; update for a previously reported circuit
  106. "CLOSED" ; notice that the circuit no longer exists
  107. Notice indicating that queryable information on a relay related circuit has
  108. changed. If the Notice parameter is either "NEW" or "UPDATE" then this
  109. provides the same fields that would be given by calling "GETINFO rcirc/id/"
  110. with the CircID.