[tor-commits] [torspec/master] Add SAFECOOKIE control-port authentication method

[nickm at torproject.org]

commit c264c80df1772979caaa29191c228087f2d84299
Author: Robert Ransom <rransom.8774 at gmail.com>
Date:   Sun Feb 5 04:02:23 2012 -0800

    Add SAFECOOKIE control-port authentication method
---
 control-spec.txt |   64 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 files changed, 56 insertions(+), 8 deletions(-)

diff --git a/control-spec.txt b/control-spec.txt
index 66088f7..ed5d2fe 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -323,11 +323,12 @@
   For information on how the implementation securely stores authentication
   information on disk, see section 5.1.
 
-  Before the client has authenticated, no command other than PROTOCOLINFO,
-  AUTHENTICATE, or QUIT is valid.  If the controller sends any other command,
-  or sends a malformed command, or sends an unsuccessful AUTHENTICATE
-  command, or sends PROTOCOLINFO more than once, Tor sends an error reply and
-  closes the connection.
+  Before the client has authenticated, no command other than
+  PROTOCOLINFO, AUTHCHALLENGE, AUTHENTICATE, or QUIT is valid.  If the
+  controller sends any other command, or sends a malformed command, or
+  sends an unsuccessful AUTHENTICATE command, or sends PROTOCOLINFO or
+  AUTHCHALLENGE more than once, Tor sends an error reply and closes
+  the connection.
 
   To prevent some cross-protocol attacks, the AUTHENTICATE command is still
   required even if all authentication methods in Tor are disabled.  In this
@@ -949,6 +950,7 @@
       "NULL"           / ; No authentication is required
       "HASHEDPASSWORD" / ; A controller must supply the original password
       "COOKIE"         / ; A controller must supply the contents of a cookie
+      "SAFECOOKIE"       ; A controller must prove knowledge of a cookie
 
      AuthCookieFile = QuotedString
      TorVersion = QuotedString
@@ -970,9 +972,16 @@
   methods that Tor currently accepts.
 
   AuthCookieFile specifies the absolute path and filename of the
-  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.
+  authentication cookie that Tor is expecting and is provided iff the
+  METHODS field contains the method "COOKIE" and/or "SAFECOOKIE".
+  Controllers MUST handle escape sequences inside this string.
+
+  All authentication cookies are 32 bytes long.  Controllers MUST NOT
+  use the contents of a non-32-byte-long file as an authentication
+  cookie.
+
+  If the METHODS field contains the method "SAFECOOKIE", every
+  AuthCookieFile must contain the same authentication cookie.
 
   The VERSION line contains the Tor version.
 
@@ -1033,6 +1042,45 @@
 
   [TAKEOWNERSHIP was added in Tor 0.2.2.28-beta.]
 
+3.24. AUTHCHALLENGE
+
+  The syntax is:
+    "AUTHCHALLENGE" SP "SAFECOOKIE"
+                    SP ClientNonce
+                    CRLF
+
+    ClientNonce = 2*HEXDIG / QuotedString
+
+  If the server accepts the command, the server reply format is:
+    "250 AUTHCHALLENGE"
+            SP "SERVERHASH=" ServerHash
+            SP "SERVERNONCE=" ServerNonce
+            CRLF
+
+    ServerHash = 64*64HEXDIG
+    ServerNonce = 64*64HEXDIG
+
+  The ClientNonce, ServerHash, and ServerNonce values are
+  encoded/decoded in the same way as the argument passed to the
+  AUTHENTICATE command.  ServerNonce MUST be 32 bytes long.
+
+  ServerHash is computed as:
+    HMAC-SHA256("Tor safe cookie authentication server-to-controller hash",
+                CookieString | ClientNonce | ServerNonce)
+  (with the HMAC key as its first argument)
+
+  After a controller sends a successful AUTHCHALLENGE command, the
+  next command sent on the connection must be an AUTHENTICATE command,
+  and the only authentication string which that AUTHENTICATE command
+  will accept is:
+    HMAC-SHA256("Tor safe cookie authentication controller-to-server hash",
+                CookieString | ClientNonce | ServerNonce)
+
+  [Unlike other commands besides AUTHENTICATE, AUTHCHALLENGE may be
+  used (but only once!) before AUTHENTICATE.]
+
+  [AUTHCHALLENGE was added in Tor FIXME.]
+
 4. Replies
 
   Reply codes follow the same 3-character format as used by SMTP, with the