[tor-commits] [torspec/master] Edit the xxx-pluggable-transports-through-proxy.txt proposal a bit

[nickm at torproject.org]

commit 1648ca676aa2ae251b6d751fb826470eadc699f3
Author: George Kadianakis <desnacked at riseup.net>
Date:   Thu Mar 14 12:26:32 2013 -0400

    Edit the xxx-pluggable-transports-through-proxy.txt proposal a bit
---
 .../xxx-pluggable-transports-through-proxy.txt     |   73 ++++++++++----------
 1 files changed, 36 insertions(+), 37 deletions(-)

diff --git a/proposals/ideas/xxx-pluggable-transports-through-proxy.txt b/proposals/ideas/xxx-pluggable-transports-through-proxy.txt
index 221c0d1..3fc7754 100644
--- a/proposals/ideas/xxx-pluggable-transports-through-proxy.txt
+++ b/proposals/ideas/xxx-pluggable-transports-through-proxy.txt
@@ -6,14 +6,14 @@ Status: Draft
 
 Overview
 
-  Tor introduced Pluggable Transports in proposal 180 Pluggable Transports
-  for circumvention.
-
-  The problem is that Tor currently cannot use a Pluggable Transport proxy
-  and a SOCKS proxy at the same time. This has been noticed by users in
-  #5195, where Tor would be failing saying "Unacceptable option value:
-  You have configured more than one proxy type".
+  Tor introduced Pluggable Transports in proposal "180 Pluggable
+  Transports for circumvention".
 
+  The problem is that Tor currently cannot use a pluggable transport
+  proxy and a normal (SOCKS/HTTP) proxy at the same time. This has
+  been noticed by users in #5195, where Tor would be failing saying
+  "Unacceptable option value: You have configured more than one proxy
+  type".
 
 Trivia
 
@@ -21,7 +21,7 @@ Trivia
   to write a proposal for it if I wanted to hear what he had to say.
   Nick spoke and I am writing this proposal.
 
-Acknowledgements
+Acknowledgments
 
   Most of the credit goes to Nick Mathewson for the main idea and
   the rest of it goes to George Kadianakis for helping me out in writing
@@ -29,51 +29,50 @@ Acknowledgements
 
 Motivation
 
-  After looking at some options we decided to go for this solution solution
+  After looking at some options we decided to go for this solution
   since it guarantees backwards compatibility and is not particularly
   costly to implement.
 
 Design overview
 
-  When Tor is configured to use both a Pluggable Transport proxy and SOCKS
-  proxy it should delegate the proxying to the pluggable transport proxy.
-
-  This can be achieved by setting the environment variables for the SOCKS
-  proxy to that specified inside of the torrc.
+  When Tor is configured to use both a pluggable transport proxy and a
+  normal proxy it should delegate the proxying to the pluggable
+  transport proxy.
 
-  When the pluggable transport proxy starts it will first read the environment
-  variables and if it detects that it should be using a SOCKS proxy make
-  all it's traffic go through it. Once the pluggable transport proxy has successfully
-  established a connection to the SOCKS proxy it should notify Tor of it's
-  success or failure.
-  When both the SOCKS and the PluggableTransport directives are set Tor
-  should set the environemnt variable start the pluggabletransport proxy and wait
-  for it to report back on the SOCKS proxy status. If the pluggable transport
-  reports back a failure or it does not report back at all (maybe because
-  it is an outdated version), Tor should notify the user of the failure
-  and exit with an error.
+  This can be achieved by specifying the address and port of the normal
+  proxy to the pluggable transport proxy using environment variables:
+  When both a normal proxy and the ClientTransportPlugin directives
+  are set in the torrc, Tor should put the address of the normal proxy
+  in an environment variable and start the pluggable transport
+  proxy. When the pluggable transport proxy starts, it should read the
+  address of the normal proxy and route all its traffic through it.
 
+  After connecting to the normal proxy, the pluggable transport proxy
+  notifies Tor whether it managed to connect or not.
 
-  The environment variables can also contain the credentials for accessing
-  the proxy.
+  The environment variables also contain the authentication
+  credentials for accessing the proxy.
 
 Specifications: Tor Pluggable Transport communication
 
-  When Tor detects a SOCKS proxy directive and a Pluggable Transport
-  proxy directive it sets the environment variable:
+  When Tor detects a normal proxy directive and a pluggable transport
+  proxy directive, it sets the environment variable:
 
     "TOR_PT_PROXY" -- This is the address of the proxy to be used by
     the pluggable transport proxy. It is in the format:
-    <proxy_type>://<user_name?>:<password?>@<ip>:<port>
+    <proxy_type>://[<user_name>][:<password>][@]<ip>:<port>
     ex. socks5://tor:test1234 at 198.51.100.1:8000
         socks4a://198.51.100.2:8001
 
+  Acceptable values for <proxy_type> are: 'socks5', 'socks4a' and 'http'.
+  If no <password> can be specified (e.g. in 'socks4a'), it is left out.
+
+  If the pluggable transport proxy detects that the TOR_PT_PROXY
+  environment variable is set, it attempts connecting to it. On
+  success it writes to stdout: "PROXY true".
+  On failure it writes: "PROXY-ERROR <errormessage>".
 
-  If the pluggable transport proxy detects that the TOR_PT_PROXY environment
-  variable is set it attempts connecting to it. On successs it will
-  write to stdout (as specified in 180-pluggable-transport.txt)
-  PROXY true. On failure it should write PROXY-ERROR <errormessage>.
+  If Tor does not read a PROXY line or it reads a PROXY-ERROR line
+  from its stdout and it is configured to use both a normal proxy and
+  a pluggable transport it should kill the transport proxy.
 
-  If Tor does not read any PROXY line or it reads a PROXY-ERROR line
-  and it is configured to use both SOCKS and PluggableTransport it should
-  exit with error.