[tor-commits] [spec/master] Initial import of taw TCP and UDP echo helpers

[art at torproject.org]

commit d04ab0477ae4feb9e038f99661b677f3d01c1289
Author: Iain R. Learmonth <irl at fsfe.org>
Date:   Mon Dec 8 15:45:21 2014 +0000

    Initial import of taw TCP and UDP echo helpers
---
 test-helpers/th-004-raw-tcp-echo.md |   67 +++++++++++++++++++++++++++++++++++
 test-helpers/th-005-raw-udp-echo.md |   54 ++++++++++++++++++++++++++++
 2 files changed, 121 insertions(+)

diff --git a/test-helpers/th-004-raw-tcp-echo.md b/test-helpers/th-004-raw-tcp-echo.md
new file mode 100644
index 0000000..8b9cd54
--- /dev/null
+++ b/test-helpers/th-004-raw-tcp-echo.md
@@ -0,0 +1,67 @@
+# Specification version number
+
+2014-12-08-000
+
+# Specification name
+
+Raw TCP Echo Test Helper
+
+# Helper description
+
+The Raw TCPEcho Test Helper listens on a TCP port for incoming connections.
+When a connection is initiated, it accepts the connection, reads a dummy HTTP
+request and sends an HTTP reply containing an encoding of the IP packets that
+made up the TCP 3 way handshake [[Wikipedia-3WHS][]] which can be compared
+against the packets sent by an ooniprobe test.
+
+# Helper preconditions
+
+ * An Internet connection
+ * An Internet-Reachable TCP Port (preferably port 80)
+ * No known middleboxes rewriting IP or TCP headers in unexpected ways between
+   the helper and the transit ISP
+
+# Expected impact
+
+Ability to help an ooni-probe client determine if the IP or TCP headers have
+been modified in transit, possibly indicating that the connection is being
+transparently proxied.
+
+# Expected inputs
+
+ * An HTTP 1.1 [[RFC2616][]] request that should not include any "dubious" Host:
+   header or keywords that might attract special treatment
+
+By emulating an HTTP session, a protocol known to censorship systems and
+protocol-enhancing proxies, it will increase the chances to see intereference
+occuring over using another protocol that may simply be passed through.
+
+# Expected output
+
+ * An HTTP 1.1 [[RFC2616][]] reply that includes as its body an encoding of the
+   packets that made up the TCP 3 way handshake [[Wikipedia-3WHS][]] from the
+   vantage point of the helper
+
+The encoding chosen could be simply a binary PCAP trace, a base64 encoded PCAP
+trace or even a JSON encoding of a dissector output as long as the dissector is
+sufficiently verbose to maximise the usefulness of the helper.
+
+MIME types like text/html should be avoided as these have a stronger potential
+for being rewritten on the wire.
+
+# Possible conclusions
+
+Possible conclusions that could be drawn from tests using this helper are:
+
+ * The presence of a transparent proxy
+ * The presence of network address translation
+ * The bleaching of bits in the IP and TCP header by badly implemented middleboxes
+
+# Notes
+
+An implementation of this test helper is currently being worked on by Iain R.
+Learmonth <<irl at fsfe.org>> using Scapy.
+
+[RFC2616]: http://tools.ietf.org/html/rfc2616
+[Wikipedia-3WHS]: http://en.wikipedia.org/wiki/Transmission_Control_Protocol#Connection_establishment
+
diff --git a/test-helpers/th-005-raw-udp-echo.md b/test-helpers/th-005-raw-udp-echo.md
new file mode 100644
index 0000000..3414076
--- /dev/null
+++ b/test-helpers/th-005-raw-udp-echo.md
@@ -0,0 +1,54 @@
+# Specification version number
+
+2014-12-08-000
+
+# Specification name
+
+Raw UDP Echo Test Helper
+
+# Helper description
+
+The Raw UDP Echo Test Helper listens on a UDP port for incoming packets. When a
+packet is recieved, it sends a UDP packet in reply with the original packet's
+header as its payload.
+
+# Helper preconditions
+
+ * An Internet connection
+ * An Internet-Reachable UDP Port
+ * No known middleboxes rewriting UDP headers in unexpected ways between
+   the helper and the transit ISP
+
+# Expected impact
+
+Ability to help an ooni-probe client determine if the UDP header is being
+rewritten and if packets are being truncated when UDP-lite is used with a
+shorter checksum coverage than the full length of the packet using the UDP
+protocol number in the IP header.
+
+# Expected inputs
+
+ * A UDP packet addressed to the helper
+ * The destination port should not be one that might attract special treatment
+ * The payload should not contain keywords that might attract special treatment
+
+# Expected output
+
+ * A UDP packet with the original incoming packet as its payload addressed to
+   return to the ooniprobe client
+
+# Possible conclusions
+
+Possible conclusions that could be drawn from tests using this helper are:
+
+ * Middleboxes are truncating UDP-lite packets when the UDP protocol number is
+   used
+ * Middleboxes are discarding UDP-lite packets with the checksum does not match
+   for the full length of the packet
+ * Source and destination ports are being rewritten
+
+# Notes
+
+An implementation of this test helper is currently being worked on by Iain R.
+Learmonth <<irl at fsfe.org>> using Scapy.
+