Author: Geoff Goodell
Title: Allow controller to manage circuit extensions
Date: 12 March 2006

History:

  This was once bug 268.  Moving it into the proposal system for posterity.

Test:

Tor controllers should have a means of learning more about circuits built
through Tor routers.  Specifically, if a Tor controller is connected to a Tor
router, it should be able to subscribe to a new class of events, perhaps
"onion" or "router" events.  A Tor router SHOULD then ensure that the
controller is informed:

(a) (NEW) when it receives a connection from some other location, in which
case it SHOULD indicate (1) a unique identifier for the circuit, and (2) a
ServerID in the event of an OR connection from another Tor router, and
Hostname otherwise.

(b) (REQUEST) when it receives a request to extend an existing circuit to a
successive Tor router, in which case it SHOULD provide (1) the unique
identifier for the circuit, (2) a Hostname (or, if possible, ServerID) of the
previous Tor router in the circuit, and (3) a ServerID for the requested
successive Tor router in the circuit;

(c) (EXTEND) Tor will attempt to extend the circuit to some other router, in
which case it SHOULD provide the same fields as provided for REQUEST.

(d) (SUCCEEDED) The circuit has been successfully extended to some ther
router, in which case it SHOULD provide the same fields as provided for
REQUEST.

We also need a new configuration option analogous to _leavestreamsunattached,
specifying whether the controller is to manage circuit extensions or not.
Perhaps we can call it "_leavecircuitsunextended".  When set to 0, Tor
manages everything as usual.  When set to 1, a circuit received by the Tor
router cannot transition from "REQUEST" to "EXTEND" state without being
directed by a new controller command.  The controller command probably does
not need any arguments, since circuits are extended per client source
routing, and all that the controller does is accept or reject the extension.

This feature can be used as a basis for enforcing routing policy.