add draft 119-controlport-auth proposal

svn:r11106

doc/spec/proposals/119-controlport-auth.txt

@@ -0,0 +1,124 @@
+Filename: 119-protocolinfo-on-controlport.txt
+Title: New PROTOCOLINFO command for controllers
+Version: $Revision$
+Last-Modified: $Date$
+Author: Roger Dingledine
+Created: 14-Aug-2007
+Status: Open
+
+Overview:
+
+  Here we describe how to help controllers locate the cookie
+  authentication file when authenticating to Tor, so we can a) require
+  authentication by default for Tor controllers and b) still keep
+  things usable.
+
+The Problem:
+
+  When we first added the controller protocol, we wanted to make it
+  easy for people to play with it, so by default we didn't require any
+  authentication from controller programs. We allowed requests only from
+  localhost as a stopgap measure for security.
+
+  Due to an increasing number of vulnerabilities based on this approach,
+  it's time to add authentication in default configurations.
+
+  We have a number of goals:
+  - We want the default Vidalia bundles to transparently work. That
+    means we don't want the users to have to type in or know a password.
+  - We want to allow multiple controller applications to connect to the
+    control port. So if Vidalia is launching Tor, it can't just keep the
+    secrets to itself.
+
+  Right now there are three authentication approaches supported
+  by the control protocol: NULL, CookieAuthentication, and
+  HashedControlPassword. See Sec 5.1 in control-spec.txt for details.
+
+  There are a couple of challenges here. The first is: if the controller
+  launches Tor, how should we teach Tor what authentication approach
+  it should require, and the secret that goes along with it? Next is:
+  how should this work when the controller attaches to an existing Tor,
+  rather than launching Tor itself?
+
+  Cookie authentication seems most amenable to letting multiple controller
+  applications interact with Tor. But that brings in yet another question:
+  how does the controller guess where to look for the cookie file,
+  without first knowing what DataDirectory Tor it using?
+
+Design:
+
+  We should add a new controller command PROTOCOLINFO that can be sent
+  as a valid first command (the others being AUTHENTICATE and QUIT). If
+  PROTOCOLINFO is sent as the first command, the second command must be
+  either a successful AUTHENTICATE or a QUIT.
+
+
+
+Spec:
+
+  C: PROTOCOLINFO CRLF
+  S: "250+PROTOCOLINFO" PIVERSION CRLF
+  S: "250-AUTH" SP "METHODS=" AuthMethod *("," AuthMethod)
+                 [SP "COOKIEFILE=" AuthCookieFile] CRLF
+  S: "250-VERSION" SP "Tor=" Version [...]
+  S: "250 OK"
+
+  PIVERSION is there in case we drastically change the syntax one day. For
+  now it should always be "1".
+
+  [XXX Is there a better way to do PIVERSION? The above way seems bad,
+  since what do controllers do if they hear a 2 but don't know what to
+  do with it? -RD]
+
+  Right now only two "topics" (AUTH and VERSION) are included, but more
+  may be included in the future. Controllers must accept lines with
+  unexpected topics.
+
+  AuthMethod =
+    "NULL"           / ; No authentication is required
+    "HASHEDPASSWORD" / ; A controller must supply the original password
+    "COOKIE"         / ; A controller must supply the contents of a cookie
+
+  AuthCookieFile = QuotedString
+
+  AuthMethod is used to specify one or more control authentication
+  methods that Tor currently accepts.
+
+  AuthCookieFile specifies the absolute path and filename of the
+  authentication cookie that Tor is expecting and is provided only if
+  the METHODS field contains the method "COOKIE". This field MUST be
+  enclosed in DQUOTEs, since the absolute path to the cookie file may
+  contain spaces on some platforms.
+
+  The VERSION line contains the Tor version, in DQUOTES. In the future
+  it might also contain Link versions, Circuit versions, or others as
+  described in proposal 105.
+
+  [What else might we want to include that could be useful? -RD]
+
+Compatibility:
+
+  Tor 0.1.2.16 and 0.2.0.4-alpha hang up after the first failed
+  command. Earlier Tors don't know about this command but don't hang
+  up. That means controllers will need a mechanism for distinguishing
+  whether they're talking to a Tor that speaks PROTOCOLINFO or not.
+
+  I suggest that the controllers attempt a PROTOCOLINFO. Then:
+    - If it works, great. Authenticate as required.
+    - If they get hung up on, reconnect and do a NULL AUTHENTICATE.
+    - If it's unrecognized but they're not hung up on, do a NULL
+      AUTHENTICATE.
+
+Unsolved problems:
+
+  If Torbutton wants to be a Tor controller one day... talking TCP is
+  bad enough, but reading from the filesystem is even harder. Is there
+  a way to let simple programs work with the controller port without
+  needing all the auth infrastructure?
+
+  Once we put this approach in place, the next vulnerability we see will
+  involve an attacker somehow getting read access to the victim's files
+  --- and then we're back where we started. This means we still need
+  to think about how to demand password-based authentication without
+  bothering the user about it.
+