[or-cvs] r7001: Begin committing violence against the spec; add some TODO it (in tor/trunk: . doc)
nickm at seul.org
nickm at seul.org
Wed Aug 9 21:42:38 UTC 2006
Author: nickm
Date: 2006-08-09 17:42:38 -0400 (Wed, 09 Aug 2006)
New Revision: 7001
Modified:
tor/trunk/
tor/trunk/doc/tor-spec.txt
Log:
r7005 at totoro: nickm | 2006-08-09 17:42:18 -0400
Begin committing violence against the spec; add some TODO items at the top. Arma, if you disagree, better say so.
Property changes on: tor/trunk
___________________________________________________________________
Name: svk:merge
- 17f730b7-d419-0410-b50f-85ee4b70197a:/local/or/tor/trunk:8245
1f724f9b-111a-0410-b636-93f1a77c1813:/local/or/tor/trunk:8207
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/eventdns:7014
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/mmap:7030
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/oo-connections:6950
+ 17f730b7-d419-0410-b50f-85ee4b70197a:/local/or/tor/trunk:8245
1f724f9b-111a-0410-b636-93f1a77c1813:/local/or/tor/trunk:8207
96637b51-b116-0410-a10e-9941ebb49b64:/tor/branches/spec:7005
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/eventdns:7014
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/mmap:7030
c95137ef-5f19-0410-b913-86e773d04f59:/tor/branches/oo-connections:6950
Modified: tor/trunk/doc/tor-spec.txt
===================================================================
--- tor/trunk/doc/tor-spec.txt 2006-08-09 10:25:01 UTC (rev 7000)
+++ tor/trunk/doc/tor-spec.txt 2006-08-09 21:42:38 UTC (rev 7001)
@@ -17,7 +17,16 @@
are not examined. For more information on why Tor acts as it does,
see tor-design.pdf.
-TODO: (very soon)
+TODO for v1 revision:
+ - Fix onionskin handshake scheme to be more mainstream, less nutty.
+ Can we just do
+ E(HMAC(g^x), g^x) rather than just E(g^x) ?
+ Better ask Ian; probably Stephen too.
+ - Versioned CREATE and friends
+ - Length on CREATE and friends
+ - Versioning on circuits
+
+TODO:
- REASON_CONNECTFAILED should include an IP.
- Copy prose from tor-design to make everything more readable.
when do we rotate which keys (tls, link, etc)?
@@ -57,6 +66,8 @@
HASH_LEN -- the length of the hash function's output, in bytes.
+ PAYLOAD_LEN -- The longest allowable cell payload, in bytes. (509)
+
CELL_LEN -- The length of a Tor cell, in bytes.
0.3. Ciphers
@@ -135,8 +146,8 @@
Version numbers are incremented for backward-incompatible protocol changes
only. Backward-compatible changes are generally implemented by adding
- additional fields to existing structures; implementations are constrained
- to ignore fields they do not expect.
+ additional fields to existing structures; implementations MUST ignore
+ fields they do not expect.
Parties negotiate OR connection versions as described below in sections
4.1 and 4.2.
@@ -162,6 +173,11 @@
certificate is the OR's nickname, followed by a space and the string
"<identity>".
+ Implementations running 0.1.2.0-alpha and earlier used an organizationName
+ of Tor. Current implementations (which support the version negotiation
+ protocol in section 4.1) MUST NOT have this value for their
+ organizationName.
+
All parties receiving certificates must confirm that the identity key is
as expected. (When initiating a connection, the expected identity key is
the one given in the directory; when creating a connection because of an
@@ -190,14 +206,24 @@
3. Cell Packet format
The basic unit of communication for onion routers and onion
- proxies is a fixed-width "cell". Each cell contains the following
+ proxies is a fixed-width "cell".
+
+ On a version 0 connection, each cell contains the following
fields:
CircID [2 bytes]
Command [1 byte]
- Payload (padded with 0 bytes) [CELL_LEN-3 bytes]
- [Total size: CELL_LEN bytes]
+ Payload (padded with 0 bytes) [PAYLOAD_LEN bytes]
+ [Total size: bytes]
+ On a version 1 connection, each cell contains the following fields:
+
+
+ CircID [3 bytes]
+ Command [1 byte]
+ Payload (padded with 0 bytes) [PAYLOAD_LEN bytes]
+ [Total size: bytes]
+
The CircID field determines which circuit, if any, the cell is
associated with.
@@ -209,7 +235,8 @@
4 -- DESTROY (Stop using a circuit) (See Sec 5.4)
5 -- CREATE_FAST (Create a circuit, no PK) (See Sec 5.1)
6 -- CREATED_FAST (Circuit created, no PK) (See Sec 5.1)
- 7 -- HELLO (Establish a connection) (See Sec 4.1)
+ 7 -- HELLO (Negotiate versions) (See Sec 4.1)
+ 8 -- NETINFO (Time and MITM-prevention) (See Sec 4.2)
The interpretation of 'Payload' depends on the type of the cell.
PADDING: Payload is unused.
@@ -244,90 +271,61 @@
4.1. HELLO cells
- When a Tor connection is established, the client must send a HELLO
- cell before sending any other cells. When the server receives a HELLO
- cell, it responds with a HELLO cell of its own. See 4.2. below for
- details on the protocol negotiation and fallback strategy.
+ When a Tor connection is established, both parties normally send a HELLO
+ cell before sending any other cells. (But see below.)
NumVersions [1 byte]
Versions [NumVersions bytes]
-[
- Probably we break the following into a NETINFO cell type:
- Timestamp [4 bytes]
- This OR's address [variable]
- Other OR's address [variable]
-]
-
"Versions" is a sequence of NumVersions link connection protocol versions,
each one byte long. Parties should list all of the versions which they
are able and willing to support. Parties can only communicate if they
have some connection protocol version in common.
-[
- Timestamp is the OR's current Unix time (GMT).
-
- Each address contains Type/Length/Value as used in Section 6.4. The first
- address is the address of the interface the party sending the HELLO cell
- used to connect to or accept connections from the other -- we include it
- to block a man-in-the-middle attack on TLS that lets an attacker bounce
- traffic through his own computers to enable timing and packet-counting
- attacks.
-
- The second address is the one that the party sending the HELLO cell
- believes the other has -- it can be used to learn what your IP address
- is if you have no other hints.
-]
-
-4.2. Protocol negotiation
-
- Version 0.1.2.1-alpha and earlier don't understand HELLO cells, and
+ Version 0.1.2.0-alpha and earlier don't understand HELLO cells, and
therefore don't support version negotiation. Thus, waiting until
the other side has sent a HELLO cell won't work for these servers: if they
send no cells back, it is impossible to tell whether they have sent a
HELLO cell that has been stalled, or whether they have dropped our own
HELLO cell as unrecognized. Thus, immediately after a TLS connection has
- been established, the client (initiating party) behaves as follows:
+ been established, the parties check whether the other side has an obsolete
+ certificate (organizationName equal to "Tor" or "TOR"). If the other party
+ presented an obsolete certificate, we assume a v0 connection. Otherwise,
+ both parties send HELLO cells listing all their supported versions. Upon
+ receiving the other party's HELLO cell, the implementation begins using
+ the highest-valued version common to both cells. If the first cell from
+ the other party is _not_ a HELLO cell, we assume a v0 protocol.
- 1. Send a CREATE cell with an appropriate circuit id,
- containing an "onion skin" of [00] bytes.
+ Implementations MUST discard cells that are not the first cells sent on a
+ connection.
- 2. Send a HELLO cell listing all its versions.
+4.2. MITM-prevention and time checking
- 3. If a DESTROY cell is received before a HELLO cell, the server
- does not support HELLO cells, and therefore we can
- only use protocol version 0.
+ If we negotiate a v1 connection or higher, the first cell we send SHOULD
+ be a NETINFO cell. Implementations SHOULD NOT send NETINFO cells at other
+ times.
- 4. If a HELLO cell is received, we use the highest numbered version
- listed by both HELLO cells.
+ A NETINFO cell contains:
+ Timestamp [4 bytes]
+ This OR's address [variable]
+ Other OR's address [variable]
- As an optimization, implementations SHOULD simply use protocol version
- 0 when the other side is recognized as a router running version
- 0.1.2.??-alpha or earlier.
+ Timestamp is the OR's current Unix time, in seconds since the epoch. If
+ an implementation receives time values from many validated ORs that
+ indicate that its clock is skewed, it SHOULD try to warn the
+ administrator.
- [If a server finds that it wants to send a cell (for example because a
- circuit wants to extend to that client, and the TLS connection
- is already established) yet no cell has arrived yet, we can't
- distinguish between a version 0 client and a slow network. We can't
- assume that the other side approves of version 0, so we can't just
- start using version 0. Perhaps the right answer is to then launch a
- new TLS connection because you don't have a usable one after all? -RD]
+ Each address contains Type/Length/Value as used in Section 6.4. The first
+ address is the address of the interface the party sending the HELLO cell
+ used to connect to or accept connections from the other -- we include it
+ to block a man-in-the-middle attack on TLS that lets an attacker bounce
+ traffic through his own computers to enable timing and packet-counting
+ attacks.
- [That would seem to be thrashy. Let's see if we can do better. Remember,
- normal v0 clients always send something after connecting, so if we have
- had a connection for a while and gotten nothing over it, we could get away
- with assuming it's bad. Alternatively, we could identify V0 clients by
- the OU=Tor field in the certificates: we don't check for it, and we never
- documented it. We might break other people's clients by sending them
- hello cells, but only if those clients are nonconformant. Am I right?
- In any case, this seems way more reliable. -NM]
+ The second address is the one that the party sending the HELLO cell
+ believes the other has -- it can be used to learn what your IP address
+ is if you have no other hints.
- [IOW, the proposal would be: if the other side has a cert without OU=Tor,
- send a HELLO cell. Otherwise, assume v0 unless they send a HELLO
- cell. Way simpler, right? If we're dealing with something proxylike or
- old, we might send an unexpected HELLO cell. If they die, they were badly
- written. -NM]
-
5. Circuit management
5.1. CREATE and CREATED cells
@@ -382,8 +380,10 @@
As usual with DH, x and y MUST be generated randomly.
+[
To implement backwar-compatible version negotiation, parties MUST
drop CREATE cells with all-[00] onion-skins.
+]
5.1.1. CREATE_FAST/CREATED_FAST cells
More information about the tor-commits
mailing list