r14596@catbus: nickm | 2007-08-16 12:56:18 -0400

 Patches to proposal 119 as described on or-dev.  Mark 119 as "Accepted"


svn:r11137

doc/spec/proposals/000-index.txt

@@ -37,5 +37,5 @@ Proposals by number:
 116  Two hop paths from entry guards [OPEN]
 117  IPv6 exits [OPEN]
 118  Advertising multiple ORPorts at once [RESEARCH]
-119  New PROTOCOLINFO command for controllers [OPEN]
+119  New PROTOCOLINFO command for controllers [ACCEPTED]
 120  Suicide descriptors when Tor servers stop [OPEN]

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

@@ -4,14 +4,16 @@ Version: $Revision$
 Last-Modified: $Date$
 Author: Roger Dingledine
 Created: 14-Aug-2007
-Status: Open
+Status: Accepted
 
 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.
+  things usable.  Also, we propose an extensible, general-purpose mechanism
+  for controllers to learn about a Tor instance's protocol and
+  authentication requirements before authenticating.
 
 The Problem:
 
@@ -43,7 +45,7 @@ The Problem:
   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?
+  without first knowing what DataDirectory Tor is using?
 
 Design:
 
@@ -52,47 +54,62 @@ Design:
   PROTOCOLINFO is sent as the first command, the second command must be
   either a successful AUTHENTICATE or a QUIT.
 
+  If the initial command sequence is not valid, Tor closes the connection.
 
 
 Spec:
 
+  C:  "PROTOCOLINFO" *(SP PIVERSION) CRLF
+  S:  "250+PROTOCOLINFO" SP PIVERSION CRLF *InfoLine "250 OK" CRLF
+
+    InfoLine = AuthLine / VersionLine / OtherLine
+
+     AuthLine = "250-AUTH" SP "METHODS=" AuthMethod *(",")AuthMethod
+                       *(SP "COOKIEFILE=" AuthCookieFile) CRLF
+     VersionLine = "250-VERSION" SP "Tor=" TorVersion [SP Arguments] CRLF
+
+     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
+     TorVersion = QuotedString
+
+     OtherLine = "250-" Keyword [SP Arguments] CRLF
+
+  For example:
+
   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"
+  S: "250+PROTOCOLINFO 1" CRLF
+  S: "250-AUTH Methods=HASHEDPASSWORD,COOKIE COOKIEFILE="/tor/cookie"" CRLF
+  S: "250-VERSION Tor=0.2.0.5-alpha" CRLF
+  S: "250 OK" CRLF
 
-  PIVERSION is there in case we drastically change the syntax one day. For
-  now it should always be "1".
+  Tor MAY give its InfoLines in any order; controllers MUST ignore InfoLines
+  with keywords it does not recognize.  Controllers MUST ignore extraneous
+  data on any InfoLine.
 
-  [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]
+  PIVERSION is there in case we drastically change the syntax one day. For
+  now it should always be "1", for the controller protocol.  Controllers MAY
+  provide a list of the protocol versions they support; Tor MAY select a
+  version that the controller does not support.
 
   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.
+  authentication cookie that Tor is expecting and is provided iff
+  the METHODS field contains the method "COOKIE".  Controllers MUST handle
+  escape sequences inside this string.
+
+  The VERSION line contains the Tor version.
 
   [What else might we want to include that could be useful? -RD]