mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-11-27 22:03:31 +01:00
Spec cleanups: improved accuracy and detail of description of
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
parent
70778dc7a8
commit
6ebdc21e51
192
doc/tor-spec.txt
192
doc/tor-spec.txt
@ -1,9 +1,13 @@
|
||||
$Id$
|
||||
|
||||
Tor Spec
|
||||
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:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user