[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[or-cvs] r17918: {torflow} Update README for new directory structure. (in torflow/trunk: . CircuitAnalysis/OPAddon)
Author: mikeperry
Date: 2009-01-05 12:14:51 -0500 (Mon, 05 Jan 2009)
New Revision: 17918
Added:
torflow/trunk/CircuitAnalysis/OPAddon/README
torflow/trunk/CircuitAnalysis/OPAddon/TODO
Removed:
torflow/trunk/CircuitAnalysis/OPAddon/README-op-addon
torflow/trunk/CircuitAnalysis/OPAddon/TODO-op-addon
Modified:
torflow/trunk/README
Log:
Update README for new directory structure.
Copied: torflow/trunk/CircuitAnalysis/OPAddon/README (from rev 17914, torflow/trunk/CircuitAnalysis/OPAddon/README-op-addon)
===================================================================
--- torflow/trunk/CircuitAnalysis/OPAddon/README (rev 0)
+++ torflow/trunk/CircuitAnalysis/OPAddon/README 2009-01-05 17:14:51 UTC (rev 17918)
@@ -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)
Deleted: torflow/trunk/CircuitAnalysis/OPAddon/README-op-addon
===================================================================
--- torflow/trunk/CircuitAnalysis/OPAddon/README-op-addon 2009-01-05 16:56:11 UTC (rev 17917)
+++ torflow/trunk/CircuitAnalysis/OPAddon/README-op-addon 2009-01-05 17:14:51 UTC (rev 17918)
@@ -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)
Copied: torflow/trunk/CircuitAnalysis/OPAddon/TODO (from rev 17914, torflow/trunk/CircuitAnalysis/OPAddon/TODO-op-addon)
===================================================================
--- torflow/trunk/CircuitAnalysis/OPAddon/TODO (rev 0)
+++ torflow/trunk/CircuitAnalysis/OPAddon/TODO 2009-01-05 17:14:51 UTC (rev 17918)
@@ -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/CircuitAnalysis/OPAddon/TODO-op-addon
===================================================================
--- torflow/trunk/CircuitAnalysis/OPAddon/TODO-op-addon 2009-01-05 16:56:11 UTC (rev 17917)
+++ torflow/trunk/CircuitAnalysis/OPAddon/TODO-op-addon 2009-01-05 17:14:51 UTC (rev 17918)
@@ -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!
Modified: torflow/trunk/README
===================================================================
--- torflow/trunk/README 2009-01-05 16:56:11 UTC (rev 17917)
+++ torflow/trunk/README 2009-01-05 17:14:51 UTC (rev 17918)
@@ -24,7 +24,8 @@
Tor controller events packaged into python classes. PathSupport.py
provides a PathBuilder class that extends from EventHandler that handles
circuit construction and stream attachment subject to policies defined
-by NodeRestrictor and PathRestrictor implementations.
+by NodeRestrictor and PathRestrictor implementations. StatsSupport.py
+gathers statistics on the circuits and streams built by PathSupport.
The TorCtl package is now fully pydoced. From this directory, you can
do:
@@ -32,27 +33,29 @@
# pydoc TorCtl.TorCtl
and
# pydoc TorCtl.PathSupport
+and
+# pydoc TorCtl.StatsSupport
2. metatroller.py
-Metatroller observes the paths created by PathSupport and gathers
-statistics on stream bandwidth, circuit construction time, circuit
-failures and stream failures. It also provides a meta control port for
-use by Tor scanners.
+Metatroller is a wrapper around StatsSupport that provides a
+meta-control port for use by Tor scanners.
The metatroller is also pydoced. To view the documentation, you can do:
# pydoc metatroller
-3. soat.py
+3. Network Scanners
+3a. NetworkScanners/soat.py
+
SoaT provides tests for ensuring the honesty of exit nodes. It can check for
invalid exit policies and perform tests to see whether nodes are changing
the requested content for several protocols. See pydoc for details:
-# pydoc soat
+# cd NetworkScanners ; pydoc soat
Important note: soat requires the pyopenssl python module to run.
You can check if pyopenssl package is available for your distribution
@@ -60,7 +63,7 @@
or get it from http://pyopenssl.sourceforge.net/
-4. speedracer.pl
+3b. NetworkScanners/speedracer.pl
SpeedRacer fetches a file repeatedly through circuits built by
metatroller. It divides the Tor network into tiers based on percentiles
@@ -68,12 +71,37 @@
these tiers itself and via metatroller.
-5. nodemon.py
+4. Node Monitors
+4a. NodeMonitors/nodemon.py
+
Nodemon uses TorCtl to monitor ORCONN events on a Tor node to measure
how much bandwidth is going to each peer node. It also measures how many
circuits are killed by OR connections being shut down prematurely.
+4b. NodeMonitors/moniTor.py
+This is a "top-like" interface for Tor information It's goal at the
+start is to just tell you basic information In the future, you may be
+able to control Tor with it.
+
+
+5. Circuit Analysis
+
+5a. Build Time Anlysis
+
+The set of scripts under CircuitAnalysis/BuildTimes gathers and plots
+circuit construction times and fits a pareto curve to the results.
+
+
+5b. OP Addon
+
+In CircuitAnalysis/OPAddon is a utility designed to run along side a Tor
+client to build a map of latencies between nodes on the network, and to
+then use this map for future routing decisions. See
+CircuitAnalysis/OPAddon/README for more info.
+
+
+
Each of these components has a lot of room for improvement. Please see
the TODO file for more information.