diff options
| -rw-r--r-- | doc/spec/proposals/119-controlport-auth.txt | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/doc/spec/proposals/119-controlport-auth.txt b/doc/spec/proposals/119-controlport-auth.txt new file mode 100644 index 000000000..02fb5a13d --- /dev/null +++ b/doc/spec/proposals/119-controlport-auth.txt @@ -0,0 +1,124 @@ +Filename: 119-protocolinfo-on-controlport.txt +Title: New PROTOCOLINFO command for controllers +Version: $Revision$ +Last-Modified: $Date$ +Author: Roger Dingledine +Created: 14-Aug-2007 +Status: Open + +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. + +The Problem: + + When we first added the controller protocol, we wanted to make it + easy for people to play with it, so by default we didn't require any + authentication from controller programs. We allowed requests only from + localhost as a stopgap measure for security. + + Due to an increasing number of vulnerabilities based on this approach, + it's time to add authentication in default configurations. + + We have a number of goals: + - We want the default Vidalia bundles to transparently work. That + means we don't want the users to have to type in or know a password. + - We want to allow multiple controller applications to connect to the + control port. So if Vidalia is launching Tor, it can't just keep the + secrets to itself. + + Right now there are three authentication approaches supported + by the control protocol: NULL, CookieAuthentication, and + HashedControlPassword. See Sec 5.1 in control-spec.txt for details. + + 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? + +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. + + + +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" + + 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] + + 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. + + [What else might we want to include that could be useful? -RD] + +Compatibility: + + Tor 0.1.2.16 and 0.2.0.4-alpha hang up after the first failed + command. Earlier Tors don't know about this command but don't hang + up. That means controllers will need a mechanism for distinguishing + whether they're talking to a Tor that speaks PROTOCOLINFO or not. + + I suggest that the controllers attempt a PROTOCOLINFO. Then: + - If it works, great. Authenticate as required. + - If they get hung up on, reconnect and do a NULL AUTHENTICATE. + - If it's unrecognized but they're not hung up on, do a NULL + AUTHENTICATE. + +Unsolved problems: + + If Torbutton wants to be a Tor controller one day... talking TCP is + bad enough, but reading from the filesystem is even harder. Is there + a way to let simple programs work with the controller port without + needing all the auth infrastructure? + + Once we put this approach in place, the next vulnerability we see will + involve an attacker somehow getting read access to the victim's files + --- and then we're back where we started. This means we still need + to think about how to demand password-based authentication without + bothering the user about it. + |