commit 210d5b2e98e3b6deff480310cd7e424c962fd928 Author: David Fifield david@bamsoftware.com Date: Wed Jul 4 06:09:13 2012 -0700

Move design.txt to doc. --- design.txt | 157 -------------------------------------------------------- doc/design.txt | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 157 insertions(+), 157 deletions(-)

diff --git a/design.txt b/design.txt deleted file mode 100644 index ecee83c..0000000 --- a/design.txt +++ /dev/null @@ -1,157 +0,0 @@ -Design of flash proxies - -0. Problem statement - - Provide access to the Tor network for users behind a restrictive - firewall that blocks direct access to all Tor relays and bridges. - -1. Overview and background - - We assume the existence of an adversary powerful enough to enumerate - and block all public and non-public (bridge) relays. For users facing - such an adversary, we assume there exists a subset of reachable hosts - that themselves can reach the Tor network. We call this subset the - unrestricted Internet. - - A browser-based proxy (flash proxy), running in a web page in the - unrestricted Internet, proxies connections between the restricted - Internet and the Tor network. These proxies are expected to be - temporary and short-lived, but their number will be great enough that - they can't all be blocked effectively. - - The implementation of a browser-based proxy using Adobe Flash or other - networking technologies is complicated by restrictions that prevent it - being a straightforward proxy. Chief among these is the lack of - listening sockets. Flash and, for example, WebSockets, can only - initiate outgoing connections, not receive incoming ones. The flash - proxy can only connect to external hosts by connecting directly to - them. The other significant restriction is that the proxy cannot - connect to just any destination. A third, but less important, - restriction is that browser-based networking does not provide - low-level socket access such as control of source address. - -2. Components - - Conceptually, each flash proxy is nothing more than a simple proxy, - which accepts connections from a client and forwards data to a server. - But because of the limited networking facilities available to an - in-browser application, several other pieces are needed. - - 1. Tor client: Is just ordinary Tor with a special configuration to - allow it to connect through a flash proxy. It advertises its need - for a connection the the facilitator, and communicates with the - flash proxy through the connector. - 2. Connector: Runs on the same computer as the Tor client. It opens - one socket to the Internet and another to localhost. It waits for a - connection on both sockets, then starts proxying data between them. - The connector speaks SOCKS on the localhost side so that Tor can - connect to it using the Socks4Proxy configuration option. On - startup, the connector informs the facilitator that it is waiting - for a connection. - 3. Flash proxy: Runs in someone's browser, in an uncensored region of - the Internet. The flash proxy first connects to the facilitator to - get a client registration. It then makes two outgoing connections, - one to a Tor relay and one to a waiting Tor client, and starts - proxying data between them. - 4. Facilitator: Keeps track of client registrations and hands them out - to clients. It is capable of receiving client registrations in a - variety of ways. It sends registrations to flash proxies over HTTP. - The facilitator is responsible for matching clients to proxies in a - reasonable manner. - 5. Tor relay: An ordinary Tor relay. - -4. Sample session - - 1. The restricted Tor user starts the connector program. - 2. The restricted user starts Tor, which makes a SOCKS connection to - the connector. - 3. The connector notifies the facilitator that it needs a connection. - 4. An unrestricted user opens the web page containing the flash proxy. - 5. The flash proxy connects to the facilitator and asks for a client. - 6. The facilitator sends one of its client registrations to the proxy. - 7. The flash proxy connects to a Tor relay and to the waiting client - connector. - 8. The connector receives the flash proxy's connection and begins - relaying data between it and the Tor relay. - - Later, the flash proxy may go offline. Assuming that another flash - proxy is available, it will receive the same client's address from the - facilitator, and the local Tor client will reconnect to the client - through it. - -5. Behavior of the Tor client - - The Tor client must be configured to make its connections through a - local proxy (the connector). This configuration is sufficient: - UseBridges 1 - Bridge 127.0.0.1:9001 - Socks4Proxy 127.0.0.1:9001 - The address given for the "Bridge" option is actually irrelevant. The - connector will ignore it and connect (through the flash proxy) to a - Tor relay. The Tor client does not have control of its first hop. - -6. Behavior of the connector - - The connector serves two purposes: It sends a registration message to - the facilitator and it carries data between a flash proxy and the - local Tor client. - - 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 the - form: - - POST / HTTP/1.0 - - client=[<address>]:<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 - client address, which means the connector doesn't have to know its - external address. - - The connector solves the impedance mismatch between the Tor client and - the flash proxy, both of which want to make outgoing connections to - the other. The connector sits in between, listens for connections from - both ends, and matches them together. The remote socket listens on - port 9000 and the local on port 9001. - - On the local side, it acts as a SOCKS proxy (albeit one that always - goes to the same destination). - -7. Behavior of the flash proxy - - The flash proxy polls the facilitator for client registrations. When - it receives a registration, it opens one connection to the given Tor - relay, one to the given client, and begin proxying data between them. - - The proxy asks the facilitator for a registration with an HTTP GET - request: - - GET / HTTP/1.0 - - - The response code is 200 and the body looks like this: - - client=[<address>:<port>]&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. - -8. Behavior of the facilitator - - The faciliator is a HTTP server that handles client POST registrations - and proxy GET requests according to the formats given above. The - facilitator listens on port 9002. - - In the current implementation, the facilitator forgets a client - registration after giving it to a flash proxy. The client must - re-register if it wants another connection later. - -9. Behavior of the Tor relay. - - The Tor relay requires no special configuration. diff --git a/doc/design.txt b/doc/design.txt new file mode 100644 index 0000000..ecee83c --- /dev/null +++ b/doc/design.txt @@ -0,0 +1,157 @@ +Design of flash proxies + +0. Problem statement + + Provide access to the Tor network for users behind a restrictive + firewall that blocks direct access to all Tor relays and bridges. + +1. Overview and background + + We assume the existence of an adversary powerful enough to enumerate + and block all public and non-public (bridge) relays. For users facing + such an adversary, we assume there exists a subset of reachable hosts + that themselves can reach the Tor network. We call this subset the + unrestricted Internet. + + A browser-based proxy (flash proxy), running in a web page in the + unrestricted Internet, proxies connections between the restricted + Internet and the Tor network. These proxies are expected to be + temporary and short-lived, but their number will be great enough that + they can't all be blocked effectively. + + The implementation of a browser-based proxy using Adobe Flash or other + networking technologies is complicated by restrictions that prevent it + being a straightforward proxy. Chief among these is the lack of + listening sockets. Flash and, for example, WebSockets, can only + initiate outgoing connections, not receive incoming ones. The flash + proxy can only connect to external hosts by connecting directly to + them. The other significant restriction is that the proxy cannot + connect to just any destination. A third, but less important, + restriction is that browser-based networking does not provide + low-level socket access such as control of source address. + +2. Components + + Conceptually, each flash proxy is nothing more than a simple proxy, + which accepts connections from a client and forwards data to a server. + But because of the limited networking facilities available to an + in-browser application, several other pieces are needed. + + 1. Tor client: Is just ordinary Tor with a special configuration to + allow it to connect through a flash proxy. It advertises its need + for a connection the the facilitator, and communicates with the + flash proxy through the connector. + 2. Connector: Runs on the same computer as the Tor client. It opens + one socket to the Internet and another to localhost. It waits for a + connection on both sockets, then starts proxying data between them. + The connector speaks SOCKS on the localhost side so that Tor can + connect to it using the Socks4Proxy configuration option. On + startup, the connector informs the facilitator that it is waiting + for a connection. + 3. Flash proxy: Runs in someone's browser, in an uncensored region of + the Internet. The flash proxy first connects to the facilitator to + get a client registration. It then makes two outgoing connections, + one to a Tor relay and one to a waiting Tor client, and starts + proxying data between them. + 4. Facilitator: Keeps track of client registrations and hands them out + to clients. It is capable of receiving client registrations in a + variety of ways. It sends registrations to flash proxies over HTTP. + The facilitator is responsible for matching clients to proxies in a + reasonable manner. + 5. Tor relay: An ordinary Tor relay. + +4. Sample session + + 1. The restricted Tor user starts the connector program. + 2. The restricted user starts Tor, which makes a SOCKS connection to + the connector. + 3. The connector notifies the facilitator that it needs a connection. + 4. An unrestricted user opens the web page containing the flash proxy. + 5. The flash proxy connects to the facilitator and asks for a client. + 6. The facilitator sends one of its client registrations to the proxy. + 7. The flash proxy connects to a Tor relay and to the waiting client + connector. + 8. The connector receives the flash proxy's connection and begins + relaying data between it and the Tor relay. + + Later, the flash proxy may go offline. Assuming that another flash + proxy is available, it will receive the same client's address from the + facilitator, and the local Tor client will reconnect to the client + through it. + +5. Behavior of the Tor client + + The Tor client must be configured to make its connections through a + local proxy (the connector). This configuration is sufficient: + UseBridges 1 + Bridge 127.0.0.1:9001 + Socks4Proxy 127.0.0.1:9001 + The address given for the "Bridge" option is actually irrelevant. The + connector will ignore it and connect (through the flash proxy) to a + Tor relay. The Tor client does not have control of its first hop. + +6. Behavior of the connector + + The connector serves two purposes: It sends a registration message to + the facilitator and it carries data between a flash proxy and the + local Tor client. + + 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 the + form: + + POST / HTTP/1.0 + + client=[<address>]:<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 + client address, which means the connector doesn't have to know its + external address. + + The connector solves the impedance mismatch between the Tor client and + the flash proxy, both of which want to make outgoing connections to + the other. The connector sits in between, listens for connections from + both ends, and matches them together. The remote socket listens on + port 9000 and the local on port 9001. + + On the local side, it acts as a SOCKS proxy (albeit one that always + goes to the same destination). + +7. Behavior of the flash proxy + + The flash proxy polls the facilitator for client registrations. When + it receives a registration, it opens one connection to the given Tor + relay, one to the given client, and begin proxying data between them. + + The proxy asks the facilitator for a registration with an HTTP GET + request: + + GET / HTTP/1.0 + + + The response code is 200 and the body looks like this: + + client=[<address>:<port>]&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. + +8. Behavior of the facilitator + + The faciliator is a HTTP server that handles client POST registrations + and proxy GET requests according to the formats given above. The + facilitator listens on port 9002. + + In the current implementation, the facilitator forgets a client + registration after giving it to a flash proxy. The client must + re-register if it wants another connection later. + +9. Behavior of the Tor relay. + + The Tor relay requires no special configuration.