commit f6e2fb73a707c34760326fa760406a38f7144c35 Author: David Fifield <david@bamsoftware.com> Date: Sun Jun 12 01:40:11 2011 -0700 Update documentation for combined TCP/RTMFP proxy. --- README | 73 +++++++++++++++++++++++++++++++++++++----------------------- design.txt | 19 +++++++++++---- 2 files changed, 59 insertions(+), 33 deletions(-) diff --git a/README b/README index ff12174..4b6a2dc 100644 --- a/README +++ b/README @@ -16,6 +16,10 @@ There are five main parts. Our terminology for each part is in quotes. 5. A Tor "relay," which is just a normal Tor relay except that its host must also serve a Flash crossdomain policy. +A proxy is capable of connecting to a client in two ways: Using a normal +TCP connection, or over Adobe RTMFP, which involves a third party but is +capable of traversing NAT. + == Demonstration page https://crypto.stanford.edu/flashproxy/ @@ -28,42 +32,56 @@ Download the (free software) Flex SDK. http://opensource.adobe.com/wiki/display/flexsdk/Flex+SDK Put its bin directory in your PATH. The important executable is mxmlc. -You need a Cirrus developer key from Adobe. Put it in the environment -variable CIRRUS_KEY so it can be found by Makefile. +For RTMFP support, you need a Cirrus developer key from Adobe. Put it in +the environment variable CIRRUS_KEY so it can be found by Makefile. $ export CIRRUS_KEY=XXXXXXXXXXXXXXXXXXXXXXXX-YYYYYYYYYYYY To build, run $ make Copy the resulting swfcat.swf file to a web server. -On the computer that will be the facilitator, run +=== Connecting + +On the Tor relay, run sudo ./crossdomaind.py - ./facilitator.py -crossdomaind.py needs to be run on any server that will accept -connections from a Flash proxy. It serves a chunk of data on port 843. +In general, any computer that a proxy connects to needs to serve a +crossdomain policy, but the connector and facilitator have it built in. + +On the facilitator, run + ./facilitator.py -r <relay-ip> The facilitator runs on port 9002 by default. +In a browser somewhere, open swfcat.swf and pass it a parameters telling it +which facilitator to use, for example + http://www.example.com/swfcat.swf?facilitator=<facilitator-ip>:9002&debug=1 + +There are two ways in which the client can receive connections: over TCP +or RTMFP. TCP doesn't send traffic to anyone other than the facilitator +and the proxy, but it only works if you have a public IP address. RTMFP +coordinates connections using a server controlled by Adobe, but works +when the client is behind a NAT. + +To connect with TCP, run + ./connector.py -f <facilitator-ip> +(If you are running the facilitator locally, be sure to use an external +IP address, not 127.0.0.1.) The connector informs the facilitator that +it wants a connection, then listens on 0.0.0.0:9000 and 127.0.0.1:9001. +The proxy will connect on port 9000 and the local Tor will connect on +9001. + +To connect with RTMFP, run + ./connector.py 127.0.0.1:9001 127.0.0.1:9002 +and open in a browser + http://www.example.com/swfcat.swf?client=1&facilitator=<facilitator-ip>:9002 +In this case, it is swfcat running in client mode that registers with +the facilitator. The connector acts to join the local swfcat and the +local Tor client. + The client needs to be running a version of Tor that supports the Socks4Proxy configuration. This means version 0.2.2.1-alpha or later--not the current stable release. -On the client, run - ./connector.py 127.0.0.1:9001 127.0.0.1:9002 -Also on the client, open up the browser to swfcat.swf. Passing no -arguments should give you good defaults (expects the facilitator running -on Nate's server). swfcat will connect to the Cirrus server to -obtain a client ID which it then registers with the facilitator. - -In a browser somewhere, open swfcat.swf and pass parameters telling it -which facilitator to use and to operate in proxy mode. - http://www.example.com/swfcat.swf?proxy=true&facilitator=<FACILITATOR_IP>:9002&debug=1 -This swfcat will also connect to the Cirrus server to obtain a client ID, -and then it will ping the facilitator to check if there are any registered -client IDs. If there is one, it will open a RTMFP connection (coordinated -by the Cirrus server) to the client and an additional connection to a -Tor relay. - -Back on the client, start Tor with the following configuration: +Start Tor with the following configuration: UseBridges 1 Bridge 127.0.0.1:9001 Socks4Proxy 127.0.0.1:9001 @@ -73,8 +91,8 @@ If you see messages like [notice] no known bridge descriptors running yet; stalling try deleting the files in ~/.tor or /var/lib/tor. -You will be able to see byte counts flowing in both browsers displaying -swfcat.swf (client and proxy), and eventually be able to build a circuit. +You will be able to see byte counts flowing in the browser window, and +eventually be able to build a circuit. == Rationale @@ -92,16 +110,15 @@ policy. Clients register with the facilitator by sending an HTTP message: POST / HTTP/1.0\r\n \r\n - client=<CIRRUS-CLIENT-ID> + client=<ip-addr/rtmfp-id> The Flash proxy also gets a client address over HTTP: GET / HTTP/1.0\r\n \r\n The server sends back address specifications of a client and a relay in an HTTP respose. HTTP/1.0 200 OK\r\n - Server: BaseHTTP/0.3 Python/2.5.2\r\n \r\n - client=<CIRRUS-CLIENT-ID>&relay=9.9.9.9:9001 + client=<ip-addr/rtmfp-id>&relay=<relay-ip> == ActionScript programming diff --git a/design.txt b/design.txt index 27be8ab..2d5ad2b 100644 --- a/design.txt +++ b/design.txt @@ -101,13 +101,19 @@ Design of Flash proxies On startup, the connector sends a registration message to the facilitator, informing the facilitator that it is waiting for a connection. The facilitator will later hand this registration to a - Flash proxy. The registration message is an HTTP POST request of this + Flash proxy. The registration message is an HTTP POST request of the form: POST / HTTP/1.0 client=[<address>]:<port> + or the form: + + POST / HTTP/1.0 + + client=[<rtmfp-id>]:<port> + The facilitator sends a 200 reply if the registration was successful and an error status otherwise. If the connector omits the [<address>] part, the facilitator will automatically fill it in based on the HTTP @@ -141,11 +147,14 @@ Design of Flash proxies client=[<address>:<port>]&relay=<address>:<port> - If <address>:<port> is missing, it means that there are no client - registrations for this proxy. + or this: + + client=[<rtmfp-id>]&relay=<address>:<port> + + If the value for the client parameter is empty, it means that there are no + client registrations for this proxy. - The Flash proxy may serve more than one relay–client pair at once. It - limits its own bandwidth to 10 KB/s (combined upload/download). + The Flash proxy may serve more than one relay–client pair at once. 8. Behavior of the facilitator