[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[or-cvs] r12281: Moved status to TODO and renamed README (torflow/trunk)
Author: renner
Date: 2007-10-30 06:48:44 -0400 (Tue, 30 Oct 2007)
New Revision: 12281
Added:
torflow/trunk/README-op-addon
torflow/trunk/TODO-op-addon
Removed:
torflow/trunk/GSoC-status
torflow/trunk/op-addon-README
Log:
Moved status to TODO and renamed README
Deleted: torflow/trunk/GSoC-status
===================================================================
--- torflow/trunk/GSoC-status 2007-10-30 10:46:11 UTC (rev 12280)
+++ torflow/trunk/GSoC-status 2007-10-30 10:48:44 UTC (rev 12281)
@@ -1,25 +0,0 @@
-TODO-lists regarding OP-Addon:
-
-Implementation tasks:
- - Perform DNS requests within OP-Addon to make 'echelon' possible for given
- URLs. Currently 'echelon' is working for given IPs only.
- - This needs also integration into circuit management: If there is currently
- a circuit available fulfilling the echelon-property regarding the current
- request, then use this circuit and do not create a new one. Else create a
- new circuit in the echelon-style.
- - Add port-history learning to StreamHandler or CircuitHandler and/or
- port-preconfiguring to be able to configure which ports will be needed.
- - Validate any given configurations.
- - Add a convenient method of control port authentication.
- - Modify OP-Addon to _not_ measure latencies to the first hop, to make
- one-hop.diff obsolete (would it still be useful?).
- - Modify OP-Addon to make it possible to connect to hidden services?
- - Implement new events in TorCtl.py (GUARD, DESCCHANGED, STATUS_*, ...)?
-
-Research tasks:
- - What is a beneficial network-model and how long does it take to learn it?
- - What is a reasonable method of analyzing big amounts of generated paths to
- empirically determine a degree of anonymity 'd' of the used method of path
- selection?
- - Ideally this method would consider _all_ aspects that somehow influence
- anonymity of users. Collect these!
Copied: torflow/trunk/README-op-addon (from rev 12280, torflow/trunk/op-addon-README)
===================================================================
--- torflow/trunk/README-op-addon (rev 0)
+++ torflow/trunk/README-op-addon 2007-10-30 10:48:44 UTC (rev 12281)
@@ -0,0 +1,290 @@
+* For instructions on how to get OP-Addon, see section 9
+* Installation instructions and prerequisites can be found in section 10
+
+###############################################################################
+
+1. Introduction to OP-Addon:
+
+ This software is intended for anybody who is researching or experimenting
+ with the circuit creation mechanisms and path selection in Tor, as well as
+ for ambitious Tor users, who want to optimize their performance in user-tasks
+ or otherwise customize Tor's method of path selection at their own risk.
+
+ The OP-Addon is a controller for Tor (clients) that is written in Python and
+ can be applied to any locally running onion proxy that has a control port
+ configured. By making use of the Tor control protocol, it replaces Tor's
+ default path selection and circuit management by highly configurable and
+ customizable mechanisms. Users can freely configure the method of path
+ selection that is to be used, while the created circuits can either be
+ evaluated regarding their performance, or specifically be used to handle user
+ streams, e.g. for browsing the web. Additionally, the add-on can be used to
+ run simulations that can be useful to determine a degree of anonymity a
+ certain method of path selection can provide, when using the current
+ network status (see section 7.).
+
+ Currently implemented performance tests include a method of measuring Tor
+ latencies that is based on violating the exit policy of the last hop in a
+ path. Using this method, it is possible to measure latencies of complete
+ n-hop circuits, as well as of single links between Tor routers (see sections
+ 5. & 6.). Further, OP-Addon can actively measure the throughput of created
+ circuits by explicitly requesting a number of bytes from a stream-server that
+ needs to be listening on the same host as OP-Addon. Such latency- and
+ throughput-tests can be used to compare the performance of circuits that were
+ created using different methods of path selection.
+
+ If you do not know what this is all about and plan to implement your own
+ application that creates circuits in a customized way or new measurings and
+ tests, please refer to section 8. The following sections will explain the
+ available features of OP-Addon that can be enabled and configured using
+ configuration options that are grouped into several sections (The file
+ 'pathrc.example' contains a commented example configuration).
+
+2. General configurations (sections HOST_PORT and CIRC_MANAGEMENT):
+
+ Since OP-Addon is a Tor controller, you will in any case need to provide the
+ host and port, where Tor is listening for control connections (defaults are
+ 127.0.0.1 and 9051). OP-Addon will make use of control port authentication,
+ as soon as a convenient way for doing this is found. The configuration option
+ 'idle_circuits' lets the user specify a number of circuits that shall be
+ created preemptively. OP-Addon will try to keep this amount of general
+ purpose circuits (allowing exit to port 80) available in the background at
+ every time. 'idle_circuits' can be set to any integer number between 0 and n.
+ If it is set to 0, OP-Addon will create the first circuit with regard to the
+ destination of the first incoming application stream.
+
+3. Evaluations and user mode (section EVALUATE):
+
+ In the most basic configuration, OP-Addon will create the configured amount
+ of circuits, and wait for incoming streams from applications to attach them.
+ If any user wants to specifically evaluate the performance of circuits, where
+ the paths were created using an arbitrary configuration, she can make use of
+ the option 'evaluate'.
+
+ If 'evaluate' is set to 'yes', one additionally needs to specify the options
+ 'num_rtt_tests' (int) and 'num_bw_tests' (int). These specify the number of
+ tests to perform on each successfully created circuit, before actively
+ closing it down again. The mean value of the results from the RTT-tests is
+ written to a file, together with the setup duration of the specific circuit
+ and the (optionally) actively measured throughput. Every single line of the
+ results-file contains values received from a circuit in the following order:
+
+ setup_duration throughput average_RTT
+
+ Note that there will be at most one bandwidth-test, even if 'num_bw_tests' is
+ set to a number greater than 1 and the script 'stream-server.pl' needs to be
+ run on the _same_ host as OP-Addon for measuring a circuit's throughput. The
+ add-on will then connect to this server, using the circuit that is to be
+ tested, and request a number of bytes that is then actively transferred. This
+ is implemented using a simple protocol, where the server parses its input and
+ uses the first occuring integer on a line as the amount of bytes to send to
+ the client (see 'stream-server.pl').
+
+ Further, the option 'num_records' is used to specify the total amount of
+ circuits that is to be tested, before terminating the actual evaluation.
+
+ Note that 'evaluate' is NOT useful for transporting user traffic at all,
+ since every circuit will be closed, as soon as all the tests have completed.
+ If 'evaluate' is set to 'no', OP-Addon is running in user mode. In user mode,
+ the script simply maintains the specified amount of circuits created with the
+ configured method of path selection at every time, waiting to handle incoming
+ user streams. One can optionally specify that circuits shall be 'pinged' with
+ any configurable frequency (see 5.), and hence a ranked list of the circuits
+ will be maintained. Incoming user streams are then attached to the first
+ suitable circuit on the sorted list. In both of the modes, OP-Addon will
+ record general circuit creation statistics about _all_ created circuits to a
+ file ('circ-setup-stats'), including the median and mean setup duration,
+ min/max values and the number of failures that occurred during circuit
+ setups, as well as on already established circuits.
+
+4. Basic path selection configuration (sections NODE_SELECTION and GEOIP):
+
+ ** NOTE THAT MAKING USE OF CUSTOMIZED METHODS OF PATH SELECTION FOR
+ ANONYMIZING TCP-TRAFFIC MAY WEAKEN YOUR ANONYMITY AND SECURITY
+ COMPARED TO THE METHODS USED IN THE DEFAULT IMPLEMENTATION! **
+
+ The method of path selection that shall be used can be freely configured
+ using configuration options from the sections NODE_SELECTION and GEOIP.
+ Internally this is done by combining arbitrary restrictions on the selection
+ of single nodes, as well as on complete paths. It is possible to choose from
+ different node generators and node/path restrictions by changing options in
+ the configuration. Some of the implemented restrictions make use of
+ geographical data (using the geoip library for Python from
+ http://www.maxmind.com) to consider the location of routers while choosing.
+ This can be used to ensure a specific geographic (non-)diversity of the
+ routers in a path, especially lower and upper bounds regarding the diversity
+ of routers in paths. But it is also possible to apply any non-geographic
+ restrictions, like explicitly specifying an exit node to be used, or the
+ length of the generated paths, as a basic example of a path restriction. The
+ following is a list of already implemented generators and restrictions that
+ can be configured using the following options from the config-file:
+
+ General:
+ * pathlen: specify the number of hops to be used in paths
+ * min_bw: specify a min-value for advertised bandwidth of routers
+ * exit_node: explicitly specify an exit node by its nickname or IDhex
+ * use_guards: choose guards on the entry positions (yes|no)
+
+ NodeGenerators:
+ * uniform: choose nodes uniformly (yes|no), can be combined with
+ * ordered_exits: choose exits from an ordered list
+ * uniform=no --> weighted selection regarding advertised bandwidths
+
+ GeoIP:
+ * unique_country:
+ - 'yes' will enforce distinct countries for all hops in a path
+ - 'no' will put all hops in the same country,
+ - comment out means do not care about countries
+ * entry_, middle_, exit_country: specify countries for positions
+ * continent_crossings:
+ - 0-n specifies the max number of continent hops in a single path
+ - comment this out to choose all hops on different continents
+ * ocean_crossings:
+ - 0-n specifies the max number of ocean crossings in a single path.
+ This is done by grouping the continents in three groups and
+ considerating crossings between these groups:
+ 1. North and South America
+ 2. Europe, Africa and Asia
+ 3. Oceania
+ - comment out to not care about ocean crossings
+ * TODO: echelon (entry in the sender`s, exit in the destination`s country)
+ * TODO: excludes (list of countries to exclude from path selection)
+
+ To extend these path selection features or to add new restrictions to be
+ applied to single nodes or complete paths, one can easily design and
+ implement new Node or PathRestrictions using the existing interfaces from
+ TorFlow.
+
+5. Latency measurements (section RTT):
+
+ It is possible to use OP-Addon to measure latencies of complete circuits, as
+ well as of single links between routers. By setting 'ping_circs' to 'yes',
+ OP-Addon will ping the complete circuits that are currently available with a
+ frequency that is specified by 'frequency' (in seconds given as float).
+ Additionally an initial interval needs to be specified, that shall be waited,
+ before triggering the first ping. Since most of the circuit creations need
+ less then 6 seconds, something like 10 seconds will be a safe value. Further
+ OP-Addon can be configured to close a circuit after n timeouts experienced
+ during measurement, where n is configured using 'timeout_limit'.
+
+ Measurements of RTTs are done by sending a relay connect cell, heading to a
+ destination that the exit policy of last router in the path will surely deny.
+ This destination is set in 'ping_dummy_*' options and the values in
+ pathrc.example are working well (127.0.0.1 and port 100). Since OP-Addon will
+ try to connect somewhere over Tor, also the Tor SOCKS-host and -port need to
+ be specified (mostly 127.0.0.1 and 9050).
+
+6. Circuit creation based on measured latencies (section MODEL):
+
+ Because of the leaky-pipe circuit topology in Tor, it is possible to address
+ every hop in a created circuit as the exit node for a stream. OP-Addon
+ implements a technique to measure and store RTTs of single links between
+ routers, by using every hop in a path as the exit once. The subtracted
+ results of this measurements are stored in a graph model that represents the
+ currently known Tor subnet of a client. Setting 'network_model' to 'yes' will
+ enable this measurings, as well as circuit creation from the network model.
+ The 'max_rtt' option lets users specify a maximum RTT value to choose only
+ paths below this threshold (seconds given as float, e.g. 0.5). The actual
+ selection from all suitable paths, that are currently found in the model, is
+ done in a probabilistic way, weighting path proposals by their (summed up)
+ latencies, combined with the minimum advertised bandwidth of the routers in
+ the path. Using another option ('min_proposals'), OP-Addon will begin to
+ create circuits from the model only if there are 'min_proposals'
+ suitable path proposals found, satisfying the configured threshold on RTTs.
+
+ If the intension is to grow a network model only, without creating circuits
+ based on it, set 'min_ratio' to 1. 'min_ratio' defines the ratio of available
+ circuits that were *not* created based on measurings. Setting it to 0.5 will
+ enforce that at most 50% of the circuits in the pool were created from the
+ model at every time. This can ensure steady growing of the network model,
+ while already choosing paths from it for building circuits. Setting
+ 'min_ratio' to 0 will lead to circuits created from the model only. This
+ might be useful, if one wants to use a model, but not to extend or refresh it
+ anymore. The regular circuits are created using the parameters defined in
+ section 4.
+
+7. Using OP-Addon to run simulations:
+
+ Another feature of OP-Addon is to run simulations using any given method of
+ path selection, by specifying the argument '--simulate' plus a number 'n' to
+ specify the number of paths that shall be generated. When running a
+ simulation, OP-Addon simply generates n paths employing the method of path
+ selection that is given by the configuration file, without actually creating
+ any circuits. The control connection to the Tor process is therefore used
+ only for querying the list of all currently known routers. An example
+ simulation (generating 100000 paths) can be run by typing:
+
+ ./op-addon pathrc.example --simulate 100000
+
+ Any algorithm can be specified to be used in the simulation, even those that
+ choose paths from a given network model. Afterwards, the created paths are
+ evaluated with regard to the degree of anonymity they would provide, e.g.~the
+ anonymity would be poor, if the same path would be chosen 100000 times.
+ Since nodes are mostly not chosen uniformly, it is necessary to calculate
+ empirical probabilities, to determine the actual distribution of the nodes to
+ the positions in paths. If many paths are created, this makes it possible to
+ empirically measure the quality of protection certain methods of path
+ selection can provide. Much more work could be done here to introduce
+ additional methods for analyzing the generated paths regarding several
+ possible attacks.
+
+###############################################################################
+
+8. Implementing custom tests and measurings:
+
+ Anybody who wants/needs to implement his/her own custom measurings or
+ performance tests, probably will need to write an event handler that extends
+ from the existing classes in PathSupport.py, similar to the PingHandler
+ contained in OP-Addon. Therefore consider CircuitHandler, which is a class
+ that simply maintains a pool of circuits of configurable size, created with
+ any given method depending on the configuration. The StreamHandler class is
+ extending from the CircuitHandler and generally handles the attaching of
+ streams to circuits from the pool. You therefore might want to extend from
+ the StreamHandler for implementing your own tests.
+
+###############################################################################
+
+9. Instructions to get OP-Addon:
+
+ OP-Addon is part of the 'TorFlow' project that is hosted within the Tor
+ subversion. To check out the latest revision, 'cd' to the directory where
+ you want to install and type:
+
+ svn checkout https://tor-svn.freehaven.net/svn/torflow/trunk torflow
+
+###############################################################################
+
+10. Prerequisites and instructions to run OP-Addon:
+
+ Note that Linux is the only operating system, that OP-Addon was tested on
+ until now, but it might also run on other platforms. Let me know, if you
+ experimented with Windows or any other OS.
+
+ To run OP-Addon, you will need a Python interpreter and a running Tor client
+ with the ControlPort set (control port authentication is currently not yet
+ supported). Note that if you plan to measure latencies of single links
+ between routers, you need to compile the Tor client from source and to apply
+ a patch that allows to measure the latency from the proxy to the first hop
+ ('one-hop.diff' is included in the distribution in the '/tordiffs'-folder).
+
+ To make use of the complete functionalities, it is further necessary to
+ install the following Python libraries:
+
+ - GeoIP [http://www.maxmind.com/app/python]
+ - NetworkX [https://networkx.lanl.gov]
+ - SocksiPy [get it from http://socksipy.sourceforge.net/]
+
+ On Debian systems, the first two libraries can be installed by simply running:
+
+ apt-get install python-geoip networkx
+
+ To run OP-Addon, simply 'cd' to the installation directory and start the
+ script by calling:
+
+ ./op-addon.py [config-file]
+
+ If no config-file is given, OP-Addon will try to find 'pathrc.example',
+ which is included in the distribution. It is intended to be copied and
+ modified though.
+
+###############################################################################
+(c) 2007 Johannes Renner (renner <AT> i4.informatik.rwth-aachen.de)
Copied: torflow/trunk/TODO-op-addon (from rev 12280, torflow/trunk/GSoC-status)
===================================================================
--- torflow/trunk/TODO-op-addon (rev 0)
+++ torflow/trunk/TODO-op-addon 2007-10-30 10:48:44 UTC (rev 12281)
@@ -0,0 +1,25 @@
+TODO-lists regarding OP-Addon:
+
+Implementation tasks:
+ - Perform DNS requests within OP-Addon to make 'echelon' possible for given
+ URLs. Currently 'echelon' is working for given IPs only.
+ - This needs also integration into circuit management: If there is currently
+ a circuit available fulfilling the echelon-property regarding the current
+ request, then use this circuit and do not create a new one. Else create a
+ new circuit in the echelon-style.
+ - Add port-history learning to StreamHandler or CircuitHandler and/or
+ port-preconfiguring to be able to configure which ports will be needed.
+ - Validate any given configurations.
+ - Add a convenient method of control port authentication.
+ - Modify OP-Addon to _not_ measure latencies to the first hop, to make
+ one-hop.diff obsolete (would it still be useful?).
+ - Modify OP-Addon to make it possible to connect to hidden services?
+ - Implement new events in TorCtl.py (GUARD, DESCCHANGED, STATUS_*, ...)?
+
+Research tasks:
+ - What is a beneficial network-model and how long does it take to learn it?
+ - What is a reasonable method of analyzing big amounts of generated paths to
+ empirically determine a degree of anonymity 'd' of the used method of path
+ selection?
+ - Ideally this method would consider _all_ aspects that somehow influence
+ anonymity of users. Collect these!
Deleted: torflow/trunk/op-addon-README
===================================================================
--- torflow/trunk/op-addon-README 2007-10-30 10:46:11 UTC (rev 12280)
+++ torflow/trunk/op-addon-README 2007-10-30 10:48:44 UTC (rev 12281)
@@ -1,290 +0,0 @@
-* For instructions on how to get OP-Addon, see section 9
-* Installation instructions and prerequisites can be found in section 10
-
-###############################################################################
-
-1. Introduction to OP-Addon:
-
- This software is intended for anybody who is researching or experimenting
- with the circuit creation mechanisms and path selection in Tor, as well as
- for ambitious Tor users, who want to optimize their performance in user-tasks
- or otherwise customize Tor's method of path selection at their own risk.
-
- The OP-Addon is a controller for Tor (clients) that is written in Python and
- can be applied to any locally running onion proxy that has a control port
- configured. By making use of the Tor control protocol, it replaces Tor's
- default path selection and circuit management by highly configurable and
- customizable mechanisms. Users can freely configure the method of path
- selection that is to be used, while the created circuits can either be
- evaluated regarding their performance, or specifically be used to handle user
- streams, e.g. for browsing the web. Additionally, the add-on can be used to
- run simulations that can be useful to determine a degree of anonymity a
- certain method of path selection can provide, when using the current
- network status (see section 7.).
-
- Currently implemented performance tests include a method of measuring Tor
- latencies that is based on violating the exit policy of the last hop in a
- path. Using this method, it is possible to measure latencies of complete
- n-hop circuits, as well as of single links between Tor routers (see sections
- 5. & 6.). Further, OP-Addon can actively measure the throughput of created
- circuits by explicitly requesting a number of bytes from a stream-server that
- needs to be listening on the same host as OP-Addon. Such latency- and
- throughput-tests can be used to compare the performance of circuits that were
- created using different methods of path selection.
-
- If you do not know what this is all about and plan to implement your own
- application that creates circuits in a customized way or new measurings and
- tests, please refer to section 8. The following sections will explain the
- available features of OP-Addon that can be enabled and configured using
- configuration options that are grouped into several sections (The file
- 'pathrc.example' contains a commented example configuration).
-
-2. General configurations (sections HOST_PORT and CIRC_MANAGEMENT):
-
- Since OP-Addon is a Tor controller, you will in any case need to provide the
- host and port, where Tor is listening for control connections (defaults are
- 127.0.0.1 and 9051). OP-Addon will make use of control port authentication,
- as soon as a convenient way for doing this is found. The configuration option
- 'idle_circuits' lets the user specify a number of circuits that shall be
- created preemptively. OP-Addon will try to keep this amount of general
- purpose circuits (allowing exit to port 80) available in the background at
- every time. 'idle_circuits' can be set to any integer number between 0 and n.
- If it is set to 0, OP-Addon will create the first circuit with regard to the
- destination of the first incoming application stream.
-
-3. Evaluations and user mode (section EVALUATE):
-
- In the most basic configuration, OP-Addon will create the configured amount
- of circuits, and wait for incoming streams from applications to attach them.
- If any user wants to specifically evaluate the performance of circuits, where
- the paths were created using an arbitrary configuration, she can make use of
- the option 'evaluate'.
-
- If 'evaluate' is set to 'yes', one additionally needs to specify the options
- 'num_rtt_tests' (int) and 'num_bw_tests' (int). These specify the number of
- tests to perform on each successfully created circuit, before actively
- closing it down again. The mean value of the results from the RTT-tests is
- written to a file, together with the setup duration of the specific circuit
- and the (optionally) actively measured throughput. Every single line of the
- results-file contains values received from a circuit in the following order:
-
- setup_duration throughput average_RTT
-
- Note that there will be at most one bandwidth-test, even if 'num_bw_tests' is
- set to a number greater than 1 and the script 'stream-server.pl' needs to be
- run on the _same_ host as OP-Addon for measuring a circuit's throughput. The
- add-on will then connect to this server, using the circuit that is to be
- tested, and request a number of bytes that is then actively transferred. This
- is implemented using a simple protocol, where the server parses its input and
- uses the first occuring integer on a line as the amount of bytes to send to
- the client (see 'stream-server.pl').
-
- Further, the option 'num_records' is used to specify the total amount of
- circuits that is to be tested, before terminating the actual evaluation.
-
- Note that 'evaluate' is NOT useful for transporting user traffic at all,
- since every circuit will be closed, as soon as all the tests have completed.
- If 'evaluate' is set to 'no', OP-Addon is running in user mode. In user mode,
- the script simply maintains the specified amount of circuits created with the
- configured method of path selection at every time, waiting to handle incoming
- user streams. One can optionally specify that circuits shall be 'pinged' with
- any configurable frequency (see 5.), and hence a ranked list of the circuits
- will be maintained. Incoming user streams are then attached to the first
- suitable circuit on the sorted list. In both of the modes, OP-Addon will
- record general circuit creation statistics about _all_ created circuits to a
- file ('circ-setup-stats'), including the median and mean setup duration,
- min/max values and the number of failures that occurred during circuit
- setups, as well as on already established circuits.
-
-4. Basic path selection configuration (sections NODE_SELECTION and GEOIP):
-
- ** NOTE THAT MAKING USE OF CUSTOMIZED METHODS OF PATH SELECTION FOR
- ANONYMIZING TCP-TRAFFIC MAY WEAKEN YOUR ANONYMITY AND SECURITY
- COMPARED TO THE METHODS USED IN THE DEFAULT IMPLEMENTATION! **
-
- The method of path selection that shall be used can be freely configured
- using configuration options from the sections NODE_SELECTION and GEOIP.
- Internally this is done by combining arbitrary restrictions on the selection
- of single nodes, as well as on complete paths. It is possible to choose from
- different node generators and node/path restrictions by changing options in
- the configuration. Some of the implemented restrictions make use of
- geographical data (using the geoip library for Python from
- http://www.maxmind.com) to consider the location of routers while choosing.
- This can be used to ensure a specific geographic (non-)diversity of the
- routers in a path, especially lower and upper bounds regarding the diversity
- of routers in paths. But it is also possible to apply any non-geographic
- restrictions, like explicitly specifying an exit node to be used, or the
- length of the generated paths, as a basic example of a path restriction. The
- following is a list of already implemented generators and restrictions that
- can be configured using the following options from the config-file:
-
- General:
- * pathlen: specify the number of hops to be used in paths
- * min_bw: specify a min-value for advertised bandwidth of routers
- * exit_node: explicitly specify an exit node by its nickname or IDhex
- * use_guards: choose guards on the entry positions (yes|no)
-
- NodeGenerators:
- * uniform: choose nodes uniformly (yes|no), can be combined with
- * ordered_exits: choose exits from an ordered list
- * uniform=no --> weighted selection regarding advertised bandwidths
-
- GeoIP:
- * unique_country:
- - 'yes' will enforce distinct countries for all hops in a path
- - 'no' will put all hops in the same country,
- - comment out means do not care about countries
- * entry_, middle_, exit_country: specify countries for positions
- * continent_crossings:
- - 0-n specifies the max number of continent hops in a single path
- - comment this out to choose all hops on different continents
- * ocean_crossings:
- - 0-n specifies the max number of ocean crossings in a single path.
- This is done by grouping the continents in three groups and
- considerating crossings between these groups:
- 1. North and South America
- 2. Europe, Africa and Asia
- 3. Oceania
- - comment out to not care about ocean crossings
- * TODO: echelon (entry in the sender`s, exit in the destination`s country)
- * TODO: excludes (list of countries to exclude from path selection)
-
- To extend these path selection features or to add new restrictions to be
- applied to single nodes or complete paths, one can easily design and
- implement new Node or PathRestrictions using the existing interfaces from
- TorFlow.
-
-5. Latency measurements (section RTT):
-
- It is possible to use OP-Addon to measure latencies of complete circuits, as
- well as of single links between routers. By setting 'ping_circs' to 'yes',
- OP-Addon will ping the complete circuits that are currently available with a
- frequency that is specified by 'frequency' (in seconds given as float).
- Additionally an initial interval needs to be specified, that shall be waited,
- before triggering the first ping. Since most of the circuit creations need
- less then 6 seconds, something like 10 seconds will be a safe value. Further
- OP-Addon can be configured to close a circuit after n timeouts experienced
- during measurement, where n is configured using 'timeout_limit'.
-
- Measurements of RTTs are done by sending a relay connect cell, heading to a
- destination that the exit policy of last router in the path will surely deny.
- This destination is set in 'ping_dummy_*' options and the values in
- pathrc.example are working well (127.0.0.1 and port 100). Since OP-Addon will
- try to connect somewhere over Tor, also the Tor SOCKS-host and -port need to
- be specified (mostly 127.0.0.1 and 9050).
-
-6. Circuit creation based on measured latencies (section MODEL):
-
- Because of the leaky-pipe circuit topology in Tor, it is possible to address
- every hop in a created circuit as the exit node for a stream. OP-Addon
- implements a technique to measure and store RTTs of single links between
- routers, by using every hop in a path as the exit once. The subtracted
- results of this measurements are stored in a graph model that represents the
- currently known Tor subnet of a client. Setting 'network_model' to 'yes' will
- enable this measurings, as well as circuit creation from the network model.
- The 'max_rtt' option lets users specify a maximum RTT value to choose only
- paths below this threshold (seconds given as float, e.g. 0.5). The actual
- selection from all suitable paths, that are currently found in the model, is
- done in a probabilistic way, weighting path proposals by their (summed up)
- latencies, combined with the minimum advertised bandwidth of the routers in
- the path. Using another option ('min_proposals'), OP-Addon will begin to
- create circuits from the model only if there are 'min_proposals'
- suitable path proposals found, satisfying the configured threshold on RTTs.
-
- If the intension is to grow a network model only, without creating circuits
- based on it, set 'min_ratio' to 1. 'min_ratio' defines the ratio of available
- circuits that were *not* created based on measurings. Setting it to 0.5 will
- enforce that at most 50% of the circuits in the pool were created from the
- model at every time. This can ensure steady growing of the network model,
- while already choosing paths from it for building circuits. Setting
- 'min_ratio' to 0 will lead to circuits created from the model only. This
- might be useful, if one wants to use a model, but not to extend or refresh it
- anymore. The regular circuits are created using the parameters defined in
- section 4.
-
-7. Using OP-Addon to run simulations:
-
- Another feature of OP-Addon is to run simulations using any given method of
- path selection, by specifying the argument '--simulate' plus a number 'n' to
- specify the number of paths that shall be generated. When running a
- simulation, OP-Addon simply generates n paths employing the method of path
- selection that is given by the configuration file, without actually creating
- any circuits. The control connection to the Tor process is therefore used
- only for querying the list of all currently known routers. An example
- simulation (generating 100000 paths) can be run by typing:
-
- ./op-addon pathrc.example --simulate 100000
-
- Any algorithm can be specified to be used in the simulation, even those that
- choose paths from a given network model. Afterwards, the created paths are
- evaluated with regard to the degree of anonymity they would provide, e.g.~the
- anonymity would be poor, if the same path would be chosen 100000 times.
- Since nodes are mostly not chosen uniformly, it is necessary to calculate
- empirical probabilities, to determine the actual distribution of the nodes to
- the positions in paths. If many paths are created, this makes it possible to
- empirically measure the quality of protection certain methods of path
- selection can provide. Much more work could be done here to introduce
- additional methods for analyzing the generated paths regarding several
- possible attacks.
-
-###############################################################################
-
-8. Implementing custom tests and measurings:
-
- Anybody who wants/needs to implement his/her own custom measurings or
- performance tests, probably will need to write an event handler that extends
- from the existing classes in PathSupport.py, similar to the PingHandler
- contained in OP-Addon. Therefore consider CircuitHandler, which is a class
- that simply maintains a pool of circuits of configurable size, created with
- any given method depending on the configuration. The StreamHandler class is
- extending from the CircuitHandler and generally handles the attaching of
- streams to circuits from the pool. You therefore might want to extend from
- the StreamHandler for implementing your own tests.
-
-###############################################################################
-
-9. Instructions to get OP-Addon:
-
- OP-Addon is part of the 'TorFlow' project that is hosted within the Tor
- subversion. To check out the latest revision, 'cd' to the directory where
- you want to install and type:
-
- svn checkout https://tor-svn.freehaven.net/svn/torflow/trunk torflow
-
-###############################################################################
-
-10. Prerequisites and instructions to run OP-Addon:
-
- Note that Linux is the only operating system, that OP-Addon was tested on
- until now, but it might also run on other platforms. Let me know, if you
- experimented with Windows or any other OS.
-
- To run OP-Addon, you will need a Python interpreter and a running Tor client
- with the ControlPort set (control port authentication is currently not yet
- supported). Note that if you plan to measure latencies of single links
- between routers, you need to compile the Tor client from source and to apply
- a patch that allows to measure the latency from the proxy to the first hop
- ('one-hop.diff' is included in the distribution in the '/tordiffs'-folder).
-
- To make use of the complete functionalities, it is further necessary to
- install the following Python libraries:
-
- - GeoIP [http://www.maxmind.com/app/python]
- - NetworkX [https://networkx.lanl.gov]
- - SocksiPy [get it from http://socksipy.sourceforge.net/]
-
- On Debian systems, the first two libraries can be installed by simply running:
-
- apt-get install python-geoip networkx
-
- To run OP-Addon, simply 'cd' to the installation directory and start the
- script by calling:
-
- ./op-addon.py [config-file]
-
- If no config-file is given, OP-Addon will try to find 'pathrc.example',
- which is included in the distribution. It is intended to be copied and
- modified though.
-
-###############################################################################
-(c) 2007 Johannes Renner (renner <AT> i4.informatik.rwth-aachen.de)