mirrors/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2024-11-20 10:12:15 +01:00
Code Issues Projects Releases Wiki Activity

Spec cleanups: improved accuracy and detail of description of

Browse Source 
directory formats, added ipv6 exit spec.

(The IPv6 stuff is only for exiting connections: ORs still need IPv4 addrs)


svn:r2204
This commit is contained in:
Nick Mathewson 2004-08-09 04:23:15 +00:00
parent 70778dc7a8
commit 6ebdc21e51
1 changed files with 159 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

190
doc/tor-spec.txt
View File

@ -2,8 +2,12 @@ $Id$
Tor Spec
Roger Dingledine
Nick Mathewson
(who else wrote this?)
Note: This is an attempt to specify Tor as it exists as implemented in
early March, 2004. It is not recommended that others implement this
mid-August, 2004. It is not recommended that others implement this
design as it stands; future versions of Tor will implement improved
protocols.
@ -14,7 +18,6 @@ TODO: (very soon)
- REASON_CONNECTFAILED should include an IP.
- Copy prose from tor-design to make everything more readable.
0. Notation:
PK -- a public key.
@ -39,6 +42,11 @@ TODO: (very soon)
"A637ED6B0BFF5CB6F406B7EDEE386BFB5A899FA5AE9F24117C4B1FE6"
"49286651ECE65381FFFFFFFFFFFFFFFF"
All "hashes" are 20-byte SHA1 cryptographic digests.
When we refer to "the hash of a public key", we mean the SHA1 hash of the
ASN.1 encoding of an RSA public key (as specified in PKCS.1).
1. System overview
Onion Routing is a distributed overlay network designed to anonymize
@ -403,7 +411,8 @@ TODO: (very soon)
ADDRESS | ':' | PORT | [00]
where ADDRESS is be a DNS hostname, or an IPv4 address in
dotted-quad format; and where PORT is encoded in decimal.
dotted-quad format, or an IPv6 address surrounded by square brackets;
and where PORT is encoded in decimal.
[What is the [00] for? -NM]
[It's so the payload is easy to parse out with string funcs -RD]
@ -413,7 +422,8 @@ TODO: (very soon)
address cannot be resolved, or a connection can't be established, the
exit node replies with a RELAY_END cell. (See 5.4 below.)
Otherwise, the exit node replies with a RELAY_CONNECTED cell, whose
payload is the 4-byte IP address to which the connection was made.
payload is the 4-byte IPv4 address or the 16-byte IPv6 address to which
the connection was made.
The OP waits for a RELAY_CONNECTED cell before sending any data.
Once a connection has been established, the OP and exit node
@ -445,9 +455,8 @@ TODO: (very soon)
6 -- REASON_DONE (anonymized TCP connection was closed)
7 -- REASON_TIMEOUT (OR timed out while connecting [???-NM])
(With REASON_EXITPOLICY, the 4-byte IP address forms the optional
data; no other reason currently has extra data.)
(With REASON_EXITPOLICY, the 4-byte IPv4 address or 16-byte IPv6 address
forms the optional data; no other reason currently has extra data.)
*** [The rest of this section describes unimplemented functionality.]
@ -584,40 +593,106 @@ More formally:
When interpreting a Document, software MUST reject any document containing a
KeywordLine that starts with a keyword it doesn't recognize.
The "opt" keyword is reserved for non-critical future extensions. All
implementations MUST ignore any item of the form "opt keyword ....." when
they would not recognize "keyword ....."; and MUST treat "opt keyword ....."
as synonymous with "keyword ......" when keyword is recognized.
7.1. Router descriptor format.
Every router descriptor MUST start with a "router" Item; MUST end with a
"router-signature" Item and an extra NL; and MUST contain exactly one
instance of each of the following Items: "published" "onion-key" "link-key"
"signing-key". Additionally, a router descriptor MAY contain any number of
"accept", "reject", and "opt" Items. Other than "router" and
"router-signature", the items may appear in any order.
"signing-key" "bandwidth". Additionally, a router descriptor MAY contain any
number of "accept", "reject", "fingerprint", "uptime", and "opt" Items.
Other than "router" and "router-signature", the items may appear in any
order.
The items' formats are as follows:
"router" nickname address (ORPort SocksPort DirPort)?
"ports" ORPort SocksPort DirPort
"bandwidth" bandwidth-avg bandwidth-burst
"platform" string
"published" YYYY-MM-DD HH:MM:SS
"onion-key" NL a public key in PEM format
"signing-key" NL a public key in PEM format
"accept" string
"reject" string
"router-signature" NL "-----BEGIN SIGNATURE-----" NL Signature NL
"-----END SIGNATURE-----"
"opt" SP keyword string? NL,Object?
ORport ::= port where the router listens for routers/proxies (speaking cells)
SocksPort ::= where the router listens for applications (speaking socks)
DirPort ::= where the router listens for directory download requests
bandwidth-avg ::= maximum average bandwidth, in bytes/s
bandwidth-burst ::= maximum bandwidth spike, in bytes/s
Indicates the beginning of a router descriptor. "address" must be an
IPv4 address in dotted-quad format. The Port values will soon be
deprecated; using them here is equivalent to using them in a "ports"
item.
"ports" ORPort SocksPort DirPort
Indicates the TCP ports at which this OR exposes functionality.
ORPort is a port at which this OR accepts TLS connections for the main
OR protocol; SocksPort is the port at which this OR accepts SOCKS
connections; and DirPort is the port at which this OR accepts
directory-related HTTP connections. If any port is not supported, the
value 0 is given instead of a port number.
"bandwidth" bandwidth-avg bandwidth-burst
Estimated bandwidth for this router, in bytes per second. The
"average" bandwidth is the volume per second that the OR is willing to
sustain over long periods; the "burst" bandwidth is the volume that
the OR is willing to sustain in very short intervals.
"platform" string
A human-readable string describing the system on which this OR is
running. This MAY include the operating system, and SHOULD include
the name and version of the software implementing the Tor protocol.
"published" YYYY-MM-DD HH:MM:SS
The time, in GMT, when this descriptor was generated.
"fingerprint"
A fingerprint (20 byte SHA1 hash of asn1 encoded public key, encoded
in hex, with spaces after every 4 characters) for this router's
identity key.
"uptime"
The number of seconds that this OR has been running.
"onion-key" NL a public key in PEM format
This key is used to encrypt EXTEND cells for this OR. The key MUST
be accepted for at least XXXX hours after any new key is published in
a subsequent descriptor.
"signing-key" NL a public key in PEM format
The OR's long-term identity key.
"accept" exitpattern
"reject" exitpattern
These lines, in order, describe the rules that an OR follows when
deciding whether to allow a new stream to a given address. The
'exitpattern' syntax is described below.
"router-signature" NL Signature NL
The "SIGNATURE" object contains a signature of the PKCS1-padded SHA1
hash of the entire router descriptor, taken from the beginning of the
"router" line, through the newline after the "router-signature" line.
The router descriptor is invalid unless the signature is performed
with the router's identity key.
nickname ::= between 1 and 19 alphanumeric characters, case-insensitive.
Bandwidth and ports are required; if they are not included in the router
line, they must appear in "bandwidth" and "ports" lines.
exitpattern ::= addrspec ":" portspec
portspec ::= "*" | port | port "-" port
port ::= an integer between 1 and 65535, inclusive.
addrspec ::= "*" | ip4spec | ip6spec
ipv4spec ::= ip4 | ip4 "/" num_ip4_bits | ip4 "/" ip4mask
ip4 ::= an IPv4 address in dotted-quad format
ip4mask ::= an IPv4 mask in dotted-quad format
num_ip4_bits ::= an integer between 0 and 32
ip6spec ::= ip6 | ip6 "/" num_ip6_bits
ip6 ::= an IPv6 address, surrounded by square brackets.
num_ip6_bits ::= an integer between 0 and 128
"opt" is reserved for non-critical future extensions.
Ports are required; if they are not included in the router
line, they must appear in the "ports" lines.
7.2. Directory format
@ -628,12 +703,33 @@ items, a directory includes any number of router descriptors, and a single
"directory-signature" item.
"signed-directory"
Indicates the start of a
"published" YYYY-MM-DD HH:MM:SS
The time at which this directory was generated and signed, in GMT.
"recommended-software" comma-separated-version-list
"running-routers" comma-separated-nickname-list
A list of which versions of which implementations are currently
believed to be secure and compatible with the network.
"running-routers" comma-separated-list
A description of which routers are currently believed to be up or
down. Every entry consists of an optional "!", followed by either an
OR's nickname, or "$" followed by a hexadecimal encoding of the hash
of an OR's identity key. If the "!" is included, the router is
believed to be running; otherwise, it is believed not to be running.
If a router's nickname is given, exactly one router of that nickname
will appear in the directory, and that router is "approved" by the
directory server. If a hashed identity key is given, that OR is not
"approved".
"directory-signature" nickname-of-dirserver NL Signature
Note: The router descriptor for the directory server must appear first.
Note: The router descriptor for the directory server MUST appear first.
The signature is computed by computing the SHA-1 hash of the
directory, from the characters "signed-directory", through the newline
after "directory-signature". This digest is then padded with PKCS.1,
@ -644,11 +740,41 @@ it should reject only that router descriptor, and continue using the
others. If it encounters an unrecognized keyword in the directory header,
it should reject the entire directory.
7.3. Behavior of a directory server
7.3. Network-status descriptor
A "network-status" (a.k.a "running-routers") document is a truncated
directory that contains only the current status of a list of nodes, not
their actual descriptors. It contains exactly one of each of the following
entries.
"network-status"
Must appear first.
"published" YYYY-MM-DD HH:MM:SS
(see 7.2 above)
"running-routers" list
(see 7.2 above)
"directory-signature" NL signature
(see 7.2 above)
7.4. Behavior of a directory server
lists nodes that are connected currently
speaks http on a socket, spits out directory on request
A.1. Differences between spec and implementation
- The current specification requires all ORs to have IPv4 addresses, but
allows servers to exit and resolve to IPv6 addresses, and to declare IPv6
addresses in their exit policies. The current codebase has no IPv6
support at all.
-----------
(for emacs)
Local Variables: