|
@@ -4,6 +4,83 @@
|
|
|
/**
|
|
|
* \file transports.c
|
|
|
* \brief Pluggable Transports related code.
|
|
|
+ *
|
|
|
+ * \details
|
|
|
+ * Each managed proxy is represented by a <b>managed_proxy_t</b>.
|
|
|
+ * Each managed proxy can support multiple transports.
|
|
|
+ * Each managed proxy gets configured through a multistep process.
|
|
|
+ *
|
|
|
+ * ::managed_proxy_list contains all the managed proxies this tor
|
|
|
+ * instance is supporting.
|
|
|
+ * In the ::managed_proxy_list there are ::unconfigured_proxies_n
|
|
|
+ * managed proxies that are still unconfigured.
|
|
|
+ *
|
|
|
+ * In every run_scheduled_event() tick, we attempt to launch and then
|
|
|
+ * configure the unconfiged managed proxies, using the configuration
|
|
|
+ * protocol defined in the 180_pluggable_transport.txt proposal. A
|
|
|
+ * managed proxy might need several ticks to get fully configured.
|
|
|
+ *
|
|
|
+ * When a managed proxy is fully configured, we register all its
|
|
|
+ * transports to the circuitbuild.c subsystem. At that point the
|
|
|
+ * transports are owned by the circuitbuild.c subsystem.
|
|
|
+ *
|
|
|
+ * When a managed proxy fails to follow the 180 configuration
|
|
|
+ * protocol, it gets marked as broken and gets destroyed.
|
|
|
+ *
|
|
|
+ * <b>In a little more detail:</b>
|
|
|
+ *
|
|
|
+ * While we are serially parsing torrc, we store all the transports
|
|
|
+ * that a proxy should spawn in its <em>transports_to_launch</em>
|
|
|
+ * element.
|
|
|
+ *
|
|
|
+ * When we finish reading the torrc, we spawn the managed proxy and
|
|
|
+ * expect {S,C}METHOD lines from its output. We add transports
|
|
|
+ * described by METHOD lines to its <em>transports</em> element, as
|
|
|
+ * transport_t structs.
|
|
|
+ *
|
|
|
+ * When the managed proxy stops spitting METHOD lines (signified by a
|
|
|
+ * '{S,C}METHODS DONE' message) we register all the transports
|
|
|
+ * collected to the circuitbuild.c subsystem. At this point, the
|
|
|
+ * pointers to transport_t can be transformed into dangling pointers
|
|
|
+ * at any point by the circuitbuild.c subsystem, and so we replace all
|
|
|
+ * transport_t pointers with strings describing the transport names.
|
|
|
+ * We can still go from a transport name to a transport_t using the
|
|
|
+ * fact that each transport name uniquely identifies a transport_t.
|
|
|
+ *
|
|
|
+ * <b>In even more detail, this is what happens when a SIGHUP
|
|
|
+ * occurs:</b>
|
|
|
+ *
|
|
|
+ * We immediately destroy all unconfigured proxies (We shouldn't have
|
|
|
+ * unconfigured proxies in the first place, except when SIGHUP rings
|
|
|
+ * immediately after tor is launched.).
|
|
|
+ *
|
|
|
+ * We mark all managed proxies and transports to signify that they
|
|
|
+ * must be removed if they don't contribute by the new torrc
|
|
|
+ * (we mark using the <b>marked_for_removal</b> element).
|
|
|
+ * We also mark all managed proxies to signify that they might need to
|
|
|
+ * be restarted so that they end up supporting all the transports the
|
|
|
+ * new torrc wants them to support (using the <b>got_hup</b> element).
|
|
|
+ * We also clear their <b>transports_to_launch</b> list so that we can
|
|
|
+ * put there the transports we need to launch according to the new
|
|
|
+ * torrc.
|
|
|
+ *
|
|
|
+ * We then start parsing torrc again.
|
|
|
+ *
|
|
|
+ * Everytime we encounter a transport line using a known pre-SIGHUP
|
|
|
+ * managed proxy, we cleanse that proxy from the removal mark.
|
|
|
+ * We also mark it as unconfigured so that on the next scheduled
|
|
|
+ * events tick, we investigate whether we need to restart the proxy
|
|
|
+ * so that it also spawns the new transports.
|
|
|
+ * If the post-SIGHUP <b>transports_to_launch</b> list is identical to
|
|
|
+ * the pre-SIGHUP one, it means that no changes were introduced to
|
|
|
+ * this proxy during the SIGHUP and no restart has to take place.
|
|
|
+ *
|
|
|
+ * During the post-SIGHUP torrc parsing, we unmark all transports
|
|
|
+ * spawned by managed proxies that we find in our torrc.
|
|
|
+ * We do that so that if we don't need to restart a managed proxy, we
|
|
|
+ * can continue using its old transports normally.
|
|
|
+ * If we end up restarting the proxy, we destroy and unregister all
|
|
|
+ * old transports from the circuitbuild.c subsystem.
|
|
|
**/
|
|
|
|
|
|
#define PT_PRIVATE
|
|
@@ -64,84 +141,6 @@ static smartlist_t *managed_proxy_list = NULL;
|
|
|
/** Number of still unconfigured proxies. */
|
|
|
static int unconfigured_proxies_n = 0;
|
|
|
|
|
|
-/** "The main idea is:"
|
|
|
-
|
|
|
- Each managed proxy is represented by a 'managed_proxy_t'.
|
|
|
- Each managed proxy can support multiple transports.
|
|
|
- Each managed proxy gets configured through a multistep process.
|
|
|
-
|
|
|
- 'managed_proxy_list' contains all the managed proxies this tor
|
|
|
- instance is supporting.
|
|
|
- In the 'managed_proxy_list' there are 'unconfigured_proxies_n'
|
|
|
- managed proxies that are still unconfigured.
|
|
|
-
|
|
|
- In every run_scheduled_event() tick, we attempt to launch and then
|
|
|
- configure the unconfiged managed proxies, using the configuration
|
|
|
- protocol defined in the 180_pluggable_transport.txt proposal. A
|
|
|
- managed proxy might need several ticks to get fully configured.
|
|
|
-
|
|
|
- When a managed proxy is fully configured, we register all its
|
|
|
- transports to the circuitbuild.c subsystem. At that point the
|
|
|
- transports are owned by the circuitbuild.c subsystem.
|
|
|
-
|
|
|
- When a managed proxy fails to follow the 180 configuration
|
|
|
- protocol, it gets marked as broken and gets destroyed.
|
|
|
-
|
|
|
- "In a little more technical detail:"
|
|
|
-
|
|
|
- While we are serially parsing torrc, we store all the transports
|
|
|
- that a proxy should spawn in its 'transports_to_launch' element.
|
|
|
-
|
|
|
- When we finish reading the torrc, we spawn the managed proxy and
|
|
|
- expect {S,C}METHOD lines from its output. We add transports
|
|
|
- described by METHOD lines to its 'transports' element, as
|
|
|
- 'transport_t' structs.
|
|
|
-
|
|
|
- When the managed proxy stops spitting METHOD lines (signified by a
|
|
|
- '{S,C}METHODS DONE' message) we register all the transports
|
|
|
- collected to the circuitbuild.c subsystem. At this point, the
|
|
|
- 'transport_t's can be transformed into dangling pointers at any
|
|
|
- point by the circuitbuild.c subsystem, and so we replace all
|
|
|
- 'transport_t's with strings describing the transport names. We
|
|
|
- can still go from a transport name to a 'transport_t' using the
|
|
|
- fact that transport names uniquely identify 'transport_t's.
|
|
|
-
|
|
|
- "In even more technical detail I shall describe what happens when
|
|
|
- the SIGHUP bell tolls:"
|
|
|
-
|
|
|
- We immediately destroy all unconfigured proxies (We shouldn't have
|
|
|
- unconfigured proxies in the first place, except when SIGHUP rings
|
|
|
- immediately after tor is launched.).
|
|
|
-
|
|
|
- We mark all managed proxies and transports to signify that they
|
|
|
- must be removed if they don't contribute by the new torrc
|
|
|
- (marked_for_removal).
|
|
|
- We also mark all managed proxies to signify that they might need
|
|
|
- to be restarted so that they end up supporting all the transports
|
|
|
- the new torrc wants them to support (got_hup).
|
|
|
- We also clear their 'transports_to_launch' list so that we can put
|
|
|
- there the transports we need to launch according to the new torrc.
|
|
|
-
|
|
|
- We then start parsing torrc again.
|
|
|
-
|
|
|
- Everytime we encounter a transport line using a known pre-SIGHUP
|
|
|
- managed proxy, we cleanse that proxy from the removal mark.
|
|
|
-
|
|
|
- We also mark it as unconfigured so that on the next scheduled
|
|
|
- events tick, we investigate whether we need to restart the proxy
|
|
|
- so that it also spawns the new transports.
|
|
|
- If the post-SIGHUP 'transports_to_launch' list is identical to the
|
|
|
- pre-SIGHUP one, it means that no changes were introduced to this
|
|
|
- proxy during the SIGHUP and no restart has to take place.
|
|
|
-
|
|
|
- During the post-SIGHUP torrc parsing, we unmark all transports
|
|
|
- spawned by managed proxies that we find in our torrc.
|
|
|
- We do that so that if we don't need to restart a managed proxy, we
|
|
|
- can continue using its old transports normally.
|
|
|
- If we end up restarting the proxy, we destroy and unregister all
|
|
|
- old transports from the circuitbuild.c subsystem.
|
|
|
-*/
|
|
|
-
|
|
|
/** Return true if there are still unconfigured managed proxies. */
|
|
|
int
|
|
|
pt_proxies_configuration_pending(void)
|