doc/CLIENTS

   1
   2     Part one: Overview and explanation
   3
   4 Because tor is an application-level proxy, it needs client-side support
   5 from every client program that wants to use it. (This is different from
   6 systems like Freedom, which used a single client-side program to capture
   7 all packets and redirect them to the Freedom network.) Client applications
   8 need two general classes of modifications to be compatible with tor:
   9
  10 1) Whenever they call connect(), they instead should connect() to the
  11 local onion proxy and tell it "address and port". The onion proxy will
  12 itself make a connection to "address and port", and then the client
  13 application can talk through that socket as if it's directly connected. To
  14 support as many applications as possible, tor uses the common "socks"
  15 protocol which does exactly the above. So applications with socks support
  16 will support tor without needing any modifications.
  17
  18 2) Applications must not call gethostbyname() to resolve an address
  19 they intend to later connect() to via onion routing. gethostbyname()
  20 contacts the dns server of the target machine -- thus giving away the
  21 fact that you intend to make an anonymous connection to it.
  22
  23 To clarify, I need to explain more about the socks protocol. Socks
  24 comes in three flavors: 4, 4a, and 5. The socks4 protocol basically
  25 uses IP and port -- so it is unsuitable because of the gethostbyname()
  26 issue above. Socks4a is a slight modification to the socks4 protocol,
  27 whereby you can specify an IP of 0.0.0.x to signal the socks server
  28 that you will instead be sending a hostname (fqdn). So applications with
  29 socks4a support are all set. Socks5, on the other hand, allows the client
  30 to specify "address type" and then an address -- so some applications
  31 choose to supply an IP and others choose to supply a hostname. If the
  32 application uses socks5 you must investigate further to decide whether
  33 it's leaking anonymity.
  34
  35
  36     Part two: using tsocks to transparently replace library calls
  37
  38 tsocks (available from http://tsocks.sourceforge.net/ or from your
  39 favorite apt-get equivalent) allows you to run a program as normal,
  40 but it replaces the system calls for connect() to connect to the socks
  41 server first and then pass it your destination info. In our case the
  42 socks server is a tor process (running either locally or elsewhere).
  43 In general this works quite well for command-line processes like finger,
  44 ssh, etc. But there are a couple of catches: A) tsocks doesn't intercept
  45 calls to gethostbyname. So unless you specify an IP rather than hostname,
  46 you'll be giving yourself away. B) Programs which are suid don't let you
  47 intercept the system calls -- ssh falls into this category. But you can
  48 make a local copy of ssh and use that. C) Probably tsocks doesn't behave
  49 well for behemoths like Mozilla.
  50
  51
  52     Part three: applications which support tor correctly
  53
  54 [this section is outdated and wrong. we should tie it into the main
  55 tor-doc.html one day.]
  56
  57 http: Mozilla: set your socks4 proxy to be the onion proxy (but see above)
  58       privoxy: set your socks4a proxy to be the onion proxy
  59       wget: run privoxy, and then add the line
  60         "http_proxy=http://localhost:8118" to your ~/.wgetrc.
  61 ssh: tsocks ssh arma@18.244.0.188
  62 ftp: tsocks wget ftp://18.244.0.188/quux.tar --passive
  63      Mozilla: set your socks4 proxy to be the onion proxy
  64
  65
  66