proposals/119-controlport-auth.txt

   1 Filename: 119-controlport-auth.txt
   2 Title: New PROTOCOLINFO command for controllers
   3 Author: Roger Dingledine
   4 Created: 14-Aug-2007
   5 Status: Closed
   6 Implemented-In: 0.2.0.x
   7
   8 Overview:
   9
  10   Here we describe how to help controllers locate the cookie
  11   authentication file when authenticating to Tor, so we can a) require
  12   authentication by default for Tor controllers and b) still keep
  13   things usable.  Also, we propose an extensible, general-purpose mechanism
  14   for controllers to learn about a Tor instance's protocol and
  15   authentication requirements before authenticating.
  16
  17 The Problem:
  18
  19   When we first added the controller protocol, we wanted to make it
  20   easy for people to play with it, so by default we didn't require any
  21   authentication from controller programs. We allowed requests only from
  22   localhost as a stopgap measure for security.
  23
  24   Due to an increasing number of vulnerabilities based on this approach,
  25   it's time to add authentication in default configurations.
  26
  27   We have a number of goals:
  28   - We want the default Vidalia bundles to transparently work. That
  29     means we don't want the users to have to type in or know a password.
  30   - We want to allow multiple controller applications to connect to the
  31     control port. So if Vidalia is launching Tor, it can't just keep the
  32     secrets to itself.
  33
  34   Right now there are three authentication approaches supported
  35   by the control protocol: NULL, CookieAuthentication, and
  36   HashedControlPassword. See Sec 5.1 in control-spec.txt for details.
  37
  38   There are a couple of challenges here. The first is: if the controller
  39   launches Tor, how should we teach Tor what authentication approach
  40   it should require, and the secret that goes along with it? Next is:
  41   how should this work when the controller attaches to an existing Tor,
  42   rather than launching Tor itself?
  43
  44   Cookie authentication seems most amenable to letting multiple controller
  45   applications interact with Tor. But that brings in yet another question:
  46   how does the controller guess where to look for the cookie file,
  47   without first knowing what DataDirectory Tor is using?
  48
  49 Design:
  50
  51   We should add a new controller command PROTOCOLINFO that can be sent
  52   as a valid first command (the others being AUTHENTICATE and QUIT). If
  53   PROTOCOLINFO is sent as the first command, the second command must be
  54   either a successful AUTHENTICATE or a QUIT.
  55
  56   If the initial command sequence is not valid, Tor closes the connection.
  57
  58
  59 Spec:
  60
  61   C:  "PROTOCOLINFO" *(SP PIVERSION) CRLF
  62   S:  "250+PROTOCOLINFO" SP PIVERSION CRLF *InfoLine "250 OK" CRLF
  63
  64     InfoLine = AuthLine / VersionLine / OtherLine
  65
  66      AuthLine = "250-AUTH" SP "METHODS=" AuthMethod *(",")AuthMethod
  67                        *(SP "COOKIEFILE=" AuthCookieFile) CRLF
  68      VersionLine = "250-VERSION" SP "Tor=" TorVersion [SP Arguments] CRLF
  69
  70      AuthMethod =
  71       "NULL"           / ; No authentication is required
  72       "HASHEDPASSWORD" / ; A controller must supply the original password
  73       "COOKIE"         / ; A controller must supply the contents of a cookie
  74
  75      AuthCookieFile = QuotedString
  76      TorVersion = QuotedString
  77
  78      OtherLine = "250-" Keyword [SP Arguments] CRLF
  79
  80   For example:
  81
  82   C: PROTOCOLINFO CRLF
  83   S: "250+PROTOCOLINFO 1" CRLF
  84   S: "250-AUTH Methods=HASHEDPASSWORD,COOKIE COOKIEFILE="/tor/cookie"" CRLF
  85   S: "250-VERSION Tor=0.2.0.5-alpha" CRLF
  86   S: "250 OK" CRLF
  87
  88   Tor MAY give its InfoLines in any order; controllers MUST ignore InfoLines
  89   with keywords it does not recognize.  Controllers MUST ignore extraneous
  90   data on any InfoLine.
  91
  92   PIVERSION is there in case we drastically change the syntax one day. For
  93   now it should always be "1", for the controller protocol.  Controllers MAY
  94   provide a list of the protocol versions they support; Tor MAY select a
  95   version that the controller does not support.
  96
  97   Right now only two "topics" (AUTH and VERSION) are included, but more
  98   may be included in the future. Controllers must accept lines with
  99   unexpected topics.
 100
 101   AuthCookieFile = QuotedString
 102
 103   AuthMethod is used to specify one or more control authentication
 104   methods that Tor currently accepts.
 105
 106   AuthCookieFile specifies the absolute path and filename of the
 107   authentication cookie that Tor is expecting and is provided iff
 108   the METHODS field contains the method "COOKIE".  Controllers MUST handle
 109   escape sequences inside this string.
 110
 111   The VERSION line contains the Tor version.
 112
 113   [What else might we want to include that could be useful? -RD]
 114
 115 Compatibility:
 116
 117   Tor 0.1.2.16 and 0.2.0.4-alpha hang up after the first failed
 118   command. Earlier Tors don't know about this command but don't hang
 119   up. That means controllers will need a mechanism for distinguishing
 120   whether they're talking to a Tor that speaks PROTOCOLINFO or not.
 121
 122   I suggest that the controllers attempt a PROTOCOLINFO. Then:
 123     - If it works, great. Authenticate as required.
 124     - If they get hung up on, reconnect and do a NULL AUTHENTICATE.
 125     - If it's unrecognized but they're not hung up on, do a NULL
 126       AUTHENTICATE.
 127
 128 Unsolved problems:
 129
 130   If Torbutton wants to be a Tor controller one day... talking TCP is
 131   bad enough, but reading from the filesystem is even harder. Is there
 132   a way to let simple programs work with the controller port without
 133   needing all the auth infrastructure?
 134
 135   Once we put this approach in place, the next vulnerability we see will
 136   involve an attacker somehow getting read access to the victim's files
 137   --- and then we're back where we started. This means we still need
 138   to think about how to demand password-based authentication without
 139   bothering the user about it.
 140