[tor-commits] [meek/master] Something of a README.

[dcf at torproject.org]

commit 16cef5eac497d722a353f86187f3d492bd78b9a5
Author: David Fifield <david at bamsoftware.com>
Date:   Wed May 7 22:19:53 2014 -0700

    Something of a README.
---
 README |   61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/README b/README
index 839fe41..34429f1 100644
--- a/README
+++ b/README
@@ -1,3 +1,64 @@
+meek is a blocking-resistant pluggable transport for Tor. It encodes a
+data stream as a sequence of HTTPS requests and responses. Requests are
+reflected through a hard-to-block third-party web server in order to
+avoid talking directly to a Tor bridge. HTTPS encryption hides
+fingerprintable byte patterns in Tor traffic.
+
+https://trac.torproject.org/projects/tor/wiki/doc/meek
+
+The key trick that makes the system work is "domain fronting":
+communicating with a forbidden domain in a way that makes it look like
+you are communicating with an allowed domain. It works by putting the
+allowed domain on the "outside" of a request: in the DNS query and the
+SNI TLS extension; and the forbidden domain on the "inside": in the Host
+header of the HTTP request. The trick works with web services that
+ignore the SNI and handle requests based on the Host header. Google,
+with its App Engine infrastructure at appspot.com, is one of these
+services. A client wanting to communicate with a forbidden subdomain of
+appspot.com while appearing to communicate with www.google.com can run
+the client plugin program like this:
+	meek-client --url=https://meek-reflect.appspot.com/ --front=www.google.com
+
+The meek-client program by itself has a fingerprintable TLS handshake.
+To disguise the TLS part of HTTPS connections, meek-client should be run
+with the --helper option pointing at a browser extension that has been
+set up separately. How it works is meek-client tells the browser what
+URL to request, the browser requests it and returns the payload to
+meek-client. The TLS implementation is that of the browser, so it better
+blends in with allowed traffic. Browser extensions for Chrome and
+Firefox are in the chrome and firefox directories.
+
+Here is a summary of the programs that appear in subdirectories.
+
+meek-client:
+The client transport plugin, run by a censored client.
+
+meek-server:
+The server transport plugin, run on a Tor relay. A public instance of
+meek-server runs at meek.bamsoftware.com:7002.
+
+appengine:
+Reflector web app that runs on Google App Engine. The reflector simply
+copies requests and responses to an instance of meek-server somewhere. A
+public instance of the App Engine web app is at
+https://meek-reflect.appspot.com/.
+
+chrome, firefox:
+Browser extensions for TLS camouflage.
+
+meek-client-torbrowser:
+An auxiliary program for the Tor Browser Bundle that runs a copy of
+Firefox with the browser extension and then configures meek-client to
+use it as a helper.
+
+terminateprocess-buffer:
+An auxiliary program used on Windows to assist with cleanup of
+subprocesses.
+
+latencytest:
+A test program for App Engine that measures roundtrip times to different
+destinations.
+
 To the extent possible under law, the authors have dedicated all
 copyright and related and neighboring rights to this software to the
 public domain worldwide. This software is distributed without any