Clarify that 0 is the only reserved circID value
[torspec.git] / address-spec.txt
1
2                           Special Hostnames in Tor
3                                Nick Mathewson
4
5 1. Overview
6
7   Most of the time, Tor treats user-specified hostnames as opaque:  When
8   the user connects to www.torproject.org, Tor picks an exit node and uses
9   that node to connect to "www.torproject.org".  Some hostnames, however,
10   can be used to override Tor's default behavior and circuit-building
11   rules.
12
13   These hostnames can be passed to Tor as the address part of a SOCKS4a or
14   SOCKS5 request.  If the application is connected to Tor using an IP-only
15   method (such as SOCKS4, TransPort, or NATDPort), these hostnames can be
16   substituted for certain IP addresses using the MapAddress configuration
17   option or the MAPADDRESS control command.
18
19 2. .exit
20
21   SYNTAX:  [hostname].[name-or-digest].exit
22            [name-or-digest].exit
23
24   Hostname is a valid hostname; [name-or-digest] is either the nickname of a
25   Tor node or the hex-encoded digest of that node's public key.
26
27   When Tor sees an address in this format, it uses the specified hostname as
28   the exit node.  If no "hostname" component is given, Tor defaults to the
29   published IPv4 address of the exit node.
30
31   It is valid to try to resolve hostnames, and in fact upon success Tor
32   will cache an internal mapaddress of the form
33   "www.google.com.foo.exit=64.233.161.99.foo.exit" to speed subsequent
34   lookups.
35
36   The .exit notation is disabled by default as of Tor 0.2.2.1-alpha, due
37   to potential application-level attacks.
38
39   EXAMPLES:
40      www.example.com.exampletornode.exit
41
42         Connect to www.example.com from the node called "exampletornode".
43
44      exampletornode.exit
45
46         Connect to the published IP address of "exampletornode" using
47         "exampletornode" as the exit.
48
49 3. .onion
50
51   SYNTAX:  [digest].onion
52
53   The digest is the first eighty bits of a SHA1 hash of the identity key for
54   a hidden service, encoded in base32.
55
56   When Tor sees an address in this format, it tries to look up and connect to
57   the specified hidden service.  See rend-spec.txt for full details.
58
59 4. .noconnect
60
61   SYNTAX:  [string].noconnect
62
63   When Tor sees an address in this format, it immediately closes the
64   connection without attaching it to any circuit. This is useful for
65   controllers that want to test whether a given application is indeed
66   using the same instance of Tor that they're controlling.
67
68   This feature was added in Tor 0.1.2.4-alpha, and taken out in Tor
69   0.2.2.1-alpha over fears that it provided another avenue for detecting
70   Tor users via application-level web tricks.
71