[tor-commits] [spec/master] Add specification for bridge reachability test
art at torproject.org
art at torproject.org
Tue Aug 19 13:36:50 UTC 2014
commit f443707f3193c63003a0c32b75c560ec1fd2235d
Author: Arturo Filastò <art at fuffa.org>
Date: Thu Aug 7 16:15:02 2014 +0200
Add specification for bridge reachability test
---
test-specs/ts-011-bridge-reachability.md | 224 ++++++++++++++++++++++++++++++
1 file changed, 224 insertions(+)
diff --git a/test-specs/ts-011-bridge-reachability.md b/test-specs/ts-011-bridge-reachability.md
new file mode 100644
index 0000000..4e94907
--- /dev/null
+++ b/test-specs/ts-011-bridge-reachability.md
@@ -0,0 +1,224 @@
+# Specification version number
+
+2014-08-06-001
+
+# Specification name
+
+Bridge Reachability Test
+
+# Test preconditions
+
+* An internet connection
+
+# Expected impact
+
+Ability to detect which bridges are working from the given network vantage
+point.
+
+# Expected inputs
+
+A list of bridge IP addressed, port numbers and pluggable transport type (when
+applicable).
+
+## Semantics
+
+They should be in a flat text file one per line in the format:
+
+ IP:ORPort
+
+Example:
+
+ 203.0.113.27:1828
+ 198.51.100.45:9045
+
+For normal Tor bridges.
+
+For pluggable transport bridges the format is:
+
+ TransportType IP:ORPort
+
+Example:
+
+ obfs2 203.0.113.27:1828
+ obfs3 198.51.100.45:9045
+
+
+# Test description
+
+For every bridge specified as input a new tor instance is started and it is
+instructed to connect to Tor using that bridge. It will try to bootstrap to
+100% and either succeed or timeout after a default time of 120 seconds.
+
+# Expected output
+
+## Parent data format
+
+None.
+
+## Required output data
+
+* The bridge address used in the measurement (bridge_address).
+
+* Whether or not it succeeded in connecting to the Tor networking using the
+ specified bridge (success).
+
+* The bootstrap percentage at which the test timed out (tor_progress).
+
+* The name of the transport used (transport_name).
+
+## Semantics
+
+error:
+ **string** indicating that an error occurred when running the test on the
+ given input.
+
+ unsupported-tor-version: to indicate that the version of tor is too old to
+ connect to the specified bridge.
+
+ missing-pyobfsproxy: to indicate that obfsproxy is not installed.
+
+ missing-fteproxy: to indicate that fteproxy is not installed.
+
+ null: no error was detected.
+
+success:
+ **boolean** indiciating if whether or not we were able to establish a
+ connection to the Tor network with the supplied bridge.
+
+ True: indicates that we reached 100% bootstrap
+
+ False: indicates that we were unable to reach 100% bootstrap before the
+ timeout was reached.
+
+ null: indicates that tor exited before we were able to complete the test,
+ this can be due to some unhandled error.
+
+
+timeout:
+ **integer** indicating the timeout, in seconds, after which we should
+ consider the bridge non-functioning. By default it is set to 120 seconds.
+
+transport_name:
+ **string** indicating the name of transport name used by the bridge.
+
+ vanilla: a regular, non pluggable transport, bridge.
+
+ obfs2: for [obfs2 obfsproxy](https://gitweb.torproject.org/pluggable-transports/obfsproxy.git/blob/HEAD:/obfsproxy/transports/obfs2.py).
+
+ obfs3: for [obfs3 obfsproxy](https://gitweb.torproject.org/pluggable-transports/obfsproxy.git/blob/HEAD:/obfsproxy/transports/obfs3.py).
+
+ fte: for [fte-proxy](https://fteproxy.org/)
+
+ scramblesuit: for [ScrambleSuit](http://www.cs.kau.se/philwint/scramblesuit/)
+
+tor_version:
+ **string** indicating the version string of the tor client being used.
+
+tor_progress:
+ **integer** indicating the percentage of tor bootstrapping at which we
+ stopped.
+
+tor_progress_tag:
+ **string** a string giving a textual description of what the progress
+ percentage means.
+
+tor_progress_summary:
+ **string** a more verbose string giving a textual description of what the
+ progress percentage state is.
+
+tor_log:
+ **string** notice level log output of tor.
+
+bridge_address:
+ **string** the address of the bridge being used.
+
+## Possible conclusions
+
+Which bridges are functioning from the given network vantage point and which
+ones are not.
+
+## Example output sample
+
+```
+###########################################
+# OONI Probe Report for bridge_reachability (0.1)
+# Thu Aug 7 16:10:50 2014
+###########################################
+---
+input_hashes: [595c8ad9b63ff9f142eca6296021990df6367ab03b3c4eb1c69a8747f0cd41a1]
+options: [-f, bridges.txt]
+probe_asn: AS3269
+probe_cc: IT
+probe_city: null
+probe_ip: 127.0.0.1
+software_name: ooniprobe
+software_version: 1.0.2
+start_time: 1407420650.560137
+test_name: bridge_reachability
+test_version: '0.1'
+...
+---
+{bridge_address: '169.229.59.74:31493', error: null, input: 'obfs3 169.229.59.74:31493
+ AF9F66B7B04F8FF6F32D455F05135250A16543C9', success: true, timeout: 120, tor_log: null,
+ tor_progress: 100, tor_progress_summary: Done, tor_progress_tag: done, tor_version: 0.2.4.20,
+ transport_name: obfs3}
+...
+---
+{bridge_address: '169.229.59.75:46328', error: null, input: 'obfs3 169.229.59.75:46328
+ AF9F66B7B04F8FF6F32D455F05135250A16543C9', success: true, timeout: 120, tor_log: null,
+ tor_progress: 100, tor_progress_summary: Done, tor_progress_tag: done, tor_version: 0.2.4.20,
+ transport_name: obfs3}
+...
+---
+{bridge_address: '208.79.90.242:35658', error: null, input: 'obfs3 208.79.90.242:35658
+ BA61757846841D64A83EA2514C766CB92F1FB41F', success: true, timeout: 120, tor_log: null,
+ tor_progress: 100, tor_progress_summary: Done, tor_progress_tag: done, tor_version: 0.2.4.20,
+ transport_name: obfs3}
+...
+---
+{bridge_address: '83.212.100.216:47870', error: null, input: 'obfs2 83.212.100.216:47870
+ 1F01A7BB60F49FC96E0850A6BAD6D076DFEFAF80', success: false, timeout: 120, tor_log: '',
+ tor_progress: 0, tor_progress_summary: null, tor_progress_tag: null, tor_version: 0.2.4.20,
+ transport_name: obfs2}
+...
+---
+{bridge_address: '83.212.96.182:46602', error: null, input: 'obfs2 83.212.96.182:46602
+ 6F058CBEF888EB20D1DEB9886909F1E812245D41', success: false, timeout: 120, tor_log: '',
+ tor_progress: 0, tor_progress_summary: null, tor_progress_tag: null, tor_version: 0.2.4.20,
+ transport_name: obfs2}
+...
+---
+{bridge_address: '70.182.182.109:54542', error: null, input: 'obfs2 70.182.182.109:54542
+ 94C9E691688FAFDEC701A0788BD15BE8AD34ED35', success: false, timeout: 120, tor_log: '',
+ tor_progress: 0, tor_progress_summary: null, tor_progress_tag: null, tor_version: 0.2.4.20,
+ transport_name: obfs2}
+...
+---
+{bridge_address: '128.31.0.34:1051', error: null, input: 'obfs2 128.31.0.34:1051 CA7434F14A898C7D3427B8295A7F83446BC7F496',
+ success: false, timeout: 120, tor_log: '', tor_progress: 0, tor_progress_summary: null,
+ tor_progress_tag: null, tor_version: 0.2.4.20, transport_name: obfs2}
+...
+---
+{bridge_address: '83.212.101.2:45235', error: null, input: 'obfs2 83.212.101.2:45235
+ 2ADFE7AA8D272C520D1FBFBF4E413F3A1B26313D', success: false, timeout: 120, tor_log: '',
+ tor_progress: 0, tor_progress_summary: null, tor_progress_tag: null, tor_version: 0.2.4.20,
+ transport_name: obfs2}
+...
+---
+{bridge_address: '83.212.101.2:42782', error: null, input: 'obfs3 83.212.101.2:42782
+ 2ADFE7AA8D272C520D1FBFBF4E413F3A1B26313D', success: false, timeout: 120, tor_log: '',
+ tor_progress: 0, tor_progress_summary: null, tor_progress_tag: null, tor_version: 0.2.4.20,
+ transport_name: obfs3}
+...
+---
+{bridge_address: '83.212.101.2:443', error: null, input: 'obfs3 83.212.101.2:443 2ADFE7AA8D272C520D1FBFBF4E413F3A1B26313D',
+ success: false, timeout: 120, tor_log: '', tor_progress: 0, tor_progress_summary: null,
+ tor_progress_tag: null, tor_version: 0.2.4.20, transport_name: obfs3}
+...
+---
+{bridge_address: '209.141.36.236:45496', error: null, input: 'obfs3 209.141.36.236:45496
+ 58D91C3A631F910F32E18A55441D5A0463BA66E2', success: false, timeout: 120, tor_log: '',
+ tor_progress: 0, tor_progress_summary: null, tor_progress_tag: null, tor_version: 0.2.4.20,
+ transport_name: obfs3}
+...
+```
More information about the tor-commits
mailing list