[or-cvs] r11137: Patches to proposal 119 as described on or-dev. Mark 119 as (in tor/trunk: . doc/spec/proposals)

Thu Aug 16 16:57:19 UTC 2007

Author: nickm
Date: 2007-08-16 12:57:19 -0400 (Thu, 16 Aug 2007)
New Revision: 11137

Modified:
   tor/trunk/
   tor/trunk/doc/spec/proposals/000-index.txt
   tor/trunk/doc/spec/proposals/119-controlport-auth.txt
Log:
 r14596 at catbus:  nickm | 2007-08-16 12:56:18 -0400
 Patches to proposal 119 as described on or-dev.  Mark 119 as "Accepted"



Property changes on: tor/trunk
___________________________________________________________________
 svk:merge ticket from /tor/trunk [r14596] on 8246c3cf-6607-4228-993b-4d95d33730f1

Modified: tor/trunk/doc/spec/proposals/000-index.txt
===================================================================

--- tor/trunk/doc/spec/proposals/000-index.txt	2007-08-16 16:53:15 UTC (rev 11136)
+++ tor/trunk/doc/spec/proposals/000-index.txt	2007-08-16 16:57:19 UTC (rev 11137)
@@ -37,5 +37,5 @@
 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]

Modified: tor/trunk/doc/spec/proposals/119-controlport-auth.txt
===================================================================
--- tor/trunk/doc/spec/proposals/119-controlport-auth.txt	2007-08-16 16:53:15 UTC (rev 11136)
+++ tor/trunk/doc/spec/proposals/119-controlport-auth.txt	2007-08-16 16:57:19 UTC (rev 11137)
@@ -4,14 +4,16 @@
 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 @@
   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 @@
   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
 
+  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.
+
   PIVERSION is there in case we drastically change the syntax one day. For
-  now it should always be "1".
+  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.
 
-  [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.
+  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, in DQUOTES. In the future
-  it might also contain Link versions, Circuit versions, or others as
-  described in proposal 105.
+  The VERSION line contains the Tor version.
 
   [What else might we want to include that could be useful? -RD]
 

