Please review new control-spec.txt

[Nick Mathewson <nickm@xxxxxxxxxxxxx>]

Hi, all.  At the recommendations of a Very Experienced Internet
Person, I've taken a hard look at the control protocol, and come to
agree with the V.E.I.P that the protocol that shipped with 0.1.0.10 is
a pain in the neck.  It is just binary enough to be hard to use, with
no real benefit.  The solution is to go with a nice text-based
protocol line SMTP and HTTP and everybody else use.

I've done one, currently located at:

   http://tor.eff.org/cvs/tor/doc/control-spec.txt

Was this more in line with what you were thinking of?

It's based more on SMTP than on anything else, but it isn't pure
SMTP.  Most trivially, it's 8-bit clean by fiat, has no line length
limits, and so on.  More significantly, I generalized the format used
by the DATA command so that other commands and replies could use it as
well.  Commands that take extra data start with "+"; reply lines that
are followed by extra data use "+" instead of "-".

Also, "6yz" replies can appear out-of-sequence, as you suggested.

Here's an example session:

    C: AUTHENTICATE "secret"
    S: 250 OK
    C: SETEVENTS CIRC
    S: 250 OK

 (now we'll be getting a bunch of '650 CIRC ...' replies.  Note that
 the
 first one we get is not responsive to the GETCONFIG reply.)

    C: GETCONFIG orport controlport
    S: 650 CIRC 1000 LAUNCHED
    S: 250-orport=9001
    S: 250 controlport=9050
    S: 650 CIRC 1000 EXTENDED moria1

 (the next line starts with +, so the server knows to expect a data
 block.)

    C: +POSTDESCRIPTOR
    C: router foobar 1.2.3.4 9001 0 9030
    C: [... a server descriptor goes here ...]
    C: .
    S: 250 OK
    S: 650 CIRC 1000 EXTENDED moria1,moria1
    S: 650 CIRC 1000 BUILT moria1,moria2,moria3

  (the client asks for two "info" values, one of which fits on a
  single line, and one of which doesn't.)

    C: GETINFO version addr-mappings/cache
    S: 250-version=Tor 0.1.1.0-alpha-cvs
    S: 250+addr-mappinggs/cache
    S: tor.eff.org=209.237.230.66
    S: .
    S: 250 OK

If you have the time to see what I've gotten wrong in *this* version
of the specification, that would be much appreciated.  (Even telling
me what is in bad taste would be helpful.)  I've already gotten a
start implementing it.

The old protocol will continue to work in 0.1.1.x, and will only be
disabled in 0.1.2.x or later.  New functionality will not be
backported to the old protocol.  The example controller libraries will
be forward-ported.

yrs,
-- 
Nick Mathewson

Attachment: pgpbINZsLuQae.pgp
Description: PGP signature