From 1ef32c82453066d192b5ce19e9a0a9b1f7255520 Mon Sep 17 00:00:00 2001 From: Roger Dingledine Date: Mon, 28 Jun 2004 06:47:07 +0000 Subject: put tor-doc.html under revision control packagers should consider including it in /usr/...doc/ svn:r1987 --- doc/tor-doc.html | 337 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 doc/tor-doc.html (limited to 'doc/tor-doc.html') diff --git a/doc/tor-doc.html b/doc/tor-doc.html new file mode 100644 index 000000000..ebeb22d7e --- /dev/null +++ b/doc/tor-doc.html @@ -0,0 +1,337 @@ + + +Tor: an anonymizing overlay network for TCP + + + + + + + + +

Tor documentation

+ +

The simple version: Tor provides a distributed network of servers +("onion routers"). Users bounce their TCP streams (web traffic, FTP, SSH, +etc.) around the routers. This makes it hard for recipients, observers, and +even the onion routers themselves to track the source of the stream.

+ +

The complex version: Onion Routing is a connection-oriented anonymizing +communication service. Users choose a source-routed path through a set of +nodes, and negotiate a "virtual circuit" through the network, in which +each node knows its predecessor and successor, but no others. Traffic +flowing down the circuit is unwrapped by a symmetric key at each node, +which reveals the downstream node.

+ + +

Why should I use Tor?

+ +

Individuals need Tor for privacy: +

Privacy in web browsing -- both from the remote website (so it can't +track and sell your behavior), and similarly from your local ISP. +
Safety in web browsing: if your local government doesn't approve +of its citizens visiting certain websites, they may monitor the sites +and put readers on a list of suspicious persons. +
Circumvention of local censorship: connect to resources (news +sites, instant messaging, etc) that are restricted from your +ISP/school/company/government. +
Socially sensitive communication: chat rooms and web forums for +rape and abuse survivors, or people with illnesses. +

+ +

Journalists and NGOs need Tor for safety: +

Allowing dissidents and whistleblowers to communicate more safely. +
Censorship-resistant publication and reading, e.g. of news sites +not permitted in some countries. +
Allowing their agents to check back with their home website while +they're in a foreign country, without notifying everybody nearby that +they're working with that organization. +

+ +

Companies need Tor for business security: +

Competitive analysis: browse the competition's website safely. +
Protecting collaborations of sensitive business units or partners. +
Protecting procurement suppliers or patterns. +
Putting the "P" back in "VPN": traditional VPNs reveal the exact +amount and frequency of communication. Which locations have employees +working late? Which locations have employees consulting job-hunting +websites? Which research groups are communicating with your company's +patent lawyers? +

+ +

Governments need Tor for traffic-analysis-resistant communication: +

Open source intelligence gathering (hiding individual analysts is +not enough -- the organization itself may be sensitive). +
Defense in depth on open and classified networks -- networks +with a million users (even if they're all cleared) can't be made safe just +by hardening them to external threat. +
Dynamic and semi-trusted international coalitions: the network can +be shared without revealing the existence or amount of communication +between all parties. +
Networks partially under known hostile control: to block +communications, the enemy must take down the whole network. +
Politically sensitive negotations. +
Road warriors. +
Protecting procurement patterns. +
Anonymous tips. +

+ +

Law enforcement needs Tor for safety: +

Allowing anonymous tips or crime reporting +
Allowing agents to observe websites without notifying them that +they're being observed (or, more broadly, without having it be an +official visit from law enforcement). +
Surveillance and honeypots (sting operations) +

+ +

Does the idea of sharing the Tor network with +all of these groups bother you? It shouldn't -- you need them for +your security.

+ + +

Should I run a client or a server?

+ +

You can run Tor in either client mode or server mode. By default, +everybody is a client. This means you don't relay traffic for +anybody but yourself.

+ +

If you have less than 768kbit in both directions, you should stay +a client. Otherwise, please consider being a server, to help out the +network. (Currently each server uses 20-30 gigabytes of traffic +per month; but that may go up.)

+ +

Note that you can be a server without allowing users to make +connections from your computer to the outside world. This is called being +a middleman server.

+ +

Benefits of running a server include: +

Clients are generally limited to 100KB/s, whereas servers can inject +or receive as much traffic as they want. +
You may get stronger anonymity, since your destination can't know +whether connections relayed through your computer originated at your +computer or not. +
You can also get stronger anonymity by configuring your Tor clients +to use your Tor server for entry or for exit. +
You're helping me with development and scalability testing. +
You're helping your fellow Internet users by providing a larger +network. Also, having servers in many different pieces of the Internet +gives users more robustness against curious telcos and brute force +attacks. +

+ +

You can read more about setting up Tor as a +server below.

+ + +

Installing Tor

+ +

You can get the latest releases here.

+ +

If you got Tor from a tarball, unpack it: tar xzf +tor-0.0.7.tar.gz; cd tor-0.0.7. Run ./configure, then +make, and then make install (as root if necessary). Then +you can launch tor from the command-line by running tor.

+ +

If you got Tor from the Win32 .exe file, you +can just click-click it (you may need to install OpenSSL +0.9.7 first, if you get an error about missing +libeay32.dll.) You might also want to run Tor in a dos window, +so you can see its logs, and see its error messages if it +crashes. If you don't want the default configuration, fetch the torrc, edit it, +and use tor.exe -f torrc.

+ +

Otherwise, if you got it prepackaged (e.g. in the Debian package or Gentoo +package), these steps are already done for you, and you may +even already have Tor started in the background (logging to +/var/log/something).

+ +

In any case, see the next section for what to do with it now that +you've got it running.

+ + +

Configuring a client

+ +

Tor comes configured as a client by default. It uses a built-in +default configuration file, and most people won't need to change any of +the settings.

+ +

The only setting you might need to change is "SocksAddress". +By default, your Tor client only listens for applications that connect +from localhost. Connections from other computers are refused. If you +want to torify applications on different computers than the Tor client, +you should copy torrc.sample to torrc (it's installed by default +to /usr/local/etc/tor/), change the SocksAddress line to +0.0.0.0, and then restart Tor.

+ +

To test if it's working, point your browser +to socks4 or socks5 proxy at localhost port 9050. In +Mozilla, this is in edit|preferences|advanced|proxies. Go to http://www.junkbusters.com/cgi-bin/privacy +and see what IP it says you're coming from. (If you have a personal +firewall, be sure to allow local connections to port 9050. If your +firewall blocks outgoing connections, punch a hole so it can connect to +TCP *:9001-9004 and *:9030-9033. If you're using Safari as your browser, +keep in mind that OS X before 10.3 claims to support socks but does +not.)

+ +

Once you've tested that it works, you should install privoxy, which is a filtering web +proxy that integrates well with Tor. Add the line
+forward-socks4a / localhost:9050 .
+(don't forget the dot) to its +config file. Then change your mozilla to http proxy at localhost port 8118 +(and no socks proxy). This step will give you good html scrubbing as well. +(See this explanation +for why direct socks gives you less anonymity.)

+ +

You might want to use Tor with an application that doesn't +support socks directly. In this case, you should look at +using tsocks +to dynamically replace the system calls in your program to +route through Tor. If you want to use socks4a, consider using socat (specific instructions +are on this hidden +service url).

+ + +

Configuring a server

+ +

We're looking for people with reasonably reliable Internet connections, +that have at least 768kbit each way. Currently we don't use all of that, +but we want it available for burst traffic.

+ +

The Tor server doesn't need to be run as root, and doesn't +need any special system permissions or kernel mods. If you're +the paranoid sort, feel free to put it into a chroot jail (some +hints), etc.

+ +

First, copy torrc.sample to torrc (by default it's in +/usr/local/etc/tor/), and edit the middle part. Create the DataDirectory, +and make sure it's owned by whoever will be running tor. Fix your system +clock so it's not too far off. Make sure name resolution works. Open a +hole in your firewall so outsiders can connect to your ORPort.

+ +

Then run tor to generate keys: tor. One of the files generated +in your DataDirectory is your 'fingerprint' file. Mail it to +tor-ops@freehaven.net.

+ +

In that mail, be sure to tell us who you are, so we know whom to contact +if there's any problem. Also describe what kind of connectivity the new +server will have. If possible, PGP sign your mail.

+ +

NOTE: You won't be able to use tor as a client or server +in this configuration until you've been added to the directory +and can authenticate to the other nodes.

+ +

Once your fingerprint has been approved, you can click here or here and look at the +running-routers line to see if your server is part of the network.

+ + +

Configuring a hidden service

+ +

Tor allows clients and servers to offer hidden services. That +is, you can offer an apache, sshd, etc, without revealing your IP to its +users. This works via Tor's rendezvous point design: both sides build +a Tor circuit out, and they meet in the middle.

+ +

If you're using Tor and Privoxy, +you can go to the hidden wiki +to see hidden services in action.

+ +

To set up a hidden service, copy torrc.sample to torrc (by default it's +in /usr/local/etc/tor/), and edit the bottom part. Then run Tor. It will +create each HiddenServiceDir you have configured, and it will create a +'hostname' file which specifies the url (xyz.onion) for that service. You +can tell people the url, and they can connect to it via their Tor client, +assuming they're using a proxy (such as Privoxy) that speaks socks4a.

+ + +

Setting up your own network

+ +

+If you want to experiment locally with your own network, or you're cut +off from the Internet and want to be able to mess with Tor still, then +you may want to set up your own separate Tor network. + +

+To set up your own Tor network, you need to run your own directory +servers, and you need to change the tarball so it points to your directory +servers rather than the default ones. + +

1: Grab the latest release. +
2: For each directory server you want, +
- 2a: Set it up as a server (see "setting up a +server" above), with a least ORPort, DataDirectory, and Nickname +defined. +
- 2b: Set "DirPort" to the intended port for serving directories. +
- 2c: Set "RecommendedVersions" to a comma-separated list of acceptable +versions of the code for clients and servers to be running (see step +4c below). + +
- 2d: Create an empty dirservers file (touch dirservers). Point +RouterFile at it in your torrc. +
- 2e: Run it: tor -f torrc. This will generate your keys and a +router.desc (router descriptor) file. It will then exit with a complaint +that it can't open the fingerprint file; that's fine. +
+
3: Create the new dirservers file. You do this by concatenating the +"router.desc" files from each dirserver's DataDirectory: cat router1.desc +router2.desc ... > dirservers +
4: Now you need to teach clients and servers to use the new +dirservers file. First, check out the tor cvs repository (instructions here -- be sure to check out the +tag that matches the version of the code you intend to use; and note that +the latest cvs version may not compile or work right). Then: +
- 4a: Edit src/or/config.c and change the default_dirservers_string array +so that it reflects the contents of the new dirservers file instead +of the old one. Be sure to get the quotes and newlines and semicolons +right. (This step sucks. Please suggest a better way to handle this +step. ;) +
- 4b: Replace the dirservers file in your sandbox (in src/config/) +with the one from step 3. +
- 4c: edit configure.in, change the AM_INIT_AUTOMAKE(tor, 0.0.6) +line so that it specifies a version that is specific to you, such as +0.0.6-arma. This will help you keep from being confused later. Be sure +to update the RecommendedVersions lines to include this version. +
- 4d: run ./autogen.sh (you'll need a new enough set of auto* tools), +then make dist. +
+
5: Create a file called approved-routers in the DataDirectory +of each directory server. Collect the 'fingerprint' lines from the +DataDirectory of each server (including directory servers), and include +them (one per line) in each approved-routers file. You can hup the tor +process for each directory server to reload the approved-routers file +(so you don't have to restart the process). +

+ +

Other doc resources

+ +

Design paper +
Spec and rend-spec +
others +

+ + + + -- cgit v1.2.3