Proposal: New PROTOCOLINFO command for controllers

[Nick Mathewson]

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

Also, this is an extensible, general-purpose mechanism that
controllers use to learn what kind of authentication is
needed/protocol is spoken before authenticating.

 [...]
>   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?

"it" should be "is"

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

What happens if the second command is _not_ authenticate or quit?  I'd
suggest, "Tor closes the connection."

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

May Tor give its reply items in any order?  I'd suggest "yes, except
that the 250+PROTOCOLINFO line comes first, and the 250 OK line comes last."

Must controllers ignore lines with keywords they don't recognize?  I'd
again suggest "yes".

The first reply line should probably have an SP between
"250+PROTOCOLINFO" and PIVERSION.

When we merge this into control-spec.txt, we need to say something
about the actual syntax of the reply, rather than just giving an
example.  I'd suggest:

  "250+PROTOCOLVERSION" SP PIVERSION CRLF *InfoLine "250 OK" CRLF
  InfoLine = "250-" Keyword SP Arguments CRLF


>   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]

Previously, when v0 and v1 were both supported, we used a stupid
double-jointed approach to auto-detect the protocol version.  I'd
suggest that PROTOCOLINFO should take an (optional) space-separated
list of preferred protocols, so that controller that want "v2" can ask
for it later.

>   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

We should explicitly say that controllers should accept and handle
replies with more than one AUTH line.   This way, Tor can support more
than one authentication method, and can tell controllers about more
than one of them.

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

By "enclosed in dquotes" I think you mean "quoted string." ;)

Also, "Controllers MUST (as usual) handle escape sequences inside the
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.

This isn't part of the spec; for the spec we just want to say
"controller MUST ignore unrecognized items"

We _don't_ want to include Link or Circuit versions in the
PROTOCOLINFO reply; that stuff belongs in some GETINFO response.
PROTOCOLINFO should only be for things that the controller needs to
know to talk to Tor.

-- 
Nick Mathewson
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 652 bytes
Desc: not available
URL: <http://lists.torproject.org/pipermail/tor-dev/attachments/20070814/3a6eda50/attachment.pgp>