Filename: 105-handshake-revision.txt
Title: Version negotiation for the Tor protocol.
Version: $Revision$
Last-Modified: $Date$
Author: Nick Mathewson, Roger Dingledine
Created:
Status: Open

Overview:

  This document was extracted from a modified version of tor-spec.txt that we
  had written before the proposal system went into place.  It adds two new
  cells types to the Tor link connection setup handshake: one used for
  version negotiation, and another to prevent MITM attacks.

  This is an open proposal.

Motivation:

   Our *current* approach to versioning the Tor protocol(s) has been as
   follows:
     - All changes must be backward compatible.
     - It's okay to add new cell types, if they would be ignored by previous
       versions of Tor.
     - It's okay to add new data elements to cells, if they would have been
       ignored by previous versions of Tor.
     - For forward compatibility, Tor must ignore cell types it doesn't
       recognize, and ignore data in those cells it doesn't expect.
     - Clients can inspect the version of Tor declared in the platform line
       of a router's descriptor, and use that to learn whether a server
       supports a given feature.  Servers, however, aren't assumed to all
       know about each other, and so don't know the version of who they're
       talking to.

   This system has these problems:
     - It's very hard to change fundamental aspects of the protocol, like the
       cell format, the link protocol, any of the various encryption schemes,
       and so on.
     - The router-to-router link protocol has remained more-or-less frozen
       for a long time, since we can't easily have an OR use new features
       unless it knows the other OR will understand them.

   We need to resolve these problems because:
     - Our cipher suite is showing its age: SHA1/AES128/RSA1024/DH1024 will
       not seem like the best idea for all time.
     - There are many ideas circulating for multiple cell sizes; while it's
       not obvious whether these are safe, we can't do them at all without a
       mechanism to permit them.
     - There are many ideas circulating for alternative cell relay rules:
       they don't work unless they can coexist in the current network.
     - If our protocol changes a lot, it's hard to describe any coherent
       version of it: we need to say "the version that Tor versions W through
       X use when talking to versions Y through Z".  This makes analysis
       harder.

Proposal:

1.0. Version numbers

   The node-to-node TLS-based "OR connection" protocol and the multi-hop
   "circuit" protocol are versioned quasi-independently.  (Certain versions
   of the circuit protocol may require a minimum version of the connection
   protocol to be used.)

   Version numbers are incremented for backward-incompatible protocol changes
   only.  Backward-compatible changes are generally implemented by adding
   additional fields to existing structures; implementations MUST ignore
   fields they do not expect.


2.1. VERSIONS cells

   When a Tor connection is established, both parties normally send a
   VERSIONS cell before sending any other cells.  (But see below.)

         NumVersions            [1 byte]
         Versions               [NumVersions bytes]

   "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.

   Version 0.1.x.y-alpha and earlier don't understand VERSIONS cells,
   and therefore don't support version negotiation.  Thus, waiting until
   the other side has sent a VERSIONS cell won't work for these servers:
   if they send no cells back, it is impossible to tell whether they
   have sent a VERSIONS cell that has been stalled, or whether they have
   dropped our own VERSIONS cell as unrecognized.  Thus, immediately after
   a TLS connection has 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 v1 connection.  Otherwise, both parties send VERSIONS
   cells listing all their supported versions.  Upon receiving the
   other party's VERSIONS cell, the implementation begins using the
   highest-valued version common to both cells.  If the first cell from
   the other party is _not_ a VERSIONS cell, we assume a v1 protocol.

   Implementations MUST discard cells that are not the first cells sent on a
   connection.

2.2. MITM-prevention and time checking

   If we negotiate a v2 connection or higher, the first cell we send SHOULD
   be a NETINFO cell.  Implementations SHOULD NOT send NETINFO cells at other
   times.

   A NETINFO cell contains:
         Timestamp              [4 bytes]
         This OR's address      [variable]
         Other OR's address     [variable]

   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.

   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 VERSIONS 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 VERSIONS cell
   believes the other has -- it can be used to learn what your IP address
   is if you have no other hints.