119-controlport-auth.txt 5.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141
  1. Filename: 119-protocolinfo-on-controlport.txt
  2. Title: New PROTOCOLINFO command for controllers
  3. Version: $Revision$
  4. Last-Modified: $Date$
  5. Author: Roger Dingledine
  6. Created: 14-Aug-2007
  7. Status: Closd
  8. Overview:
  9. Here we describe how to help controllers locate the cookie
  10. authentication file when authenticating to Tor, so we can a) require
  11. authentication by default for Tor controllers and b) still keep
  12. things usable. Also, we propose an extensible, general-purpose mechanism
  13. for controllers to learn about a Tor instance's protocol and
  14. authentication requirements before authenticating.
  15. The Problem:
  16. When we first added the controller protocol, we wanted to make it
  17. easy for people to play with it, so by default we didn't require any
  18. authentication from controller programs. We allowed requests only from
  19. localhost as a stopgap measure for security.
  20. Due to an increasing number of vulnerabilities based on this approach,
  21. it's time to add authentication in default configurations.
  22. We have a number of goals:
  23. - We want the default Vidalia bundles to transparently work. That
  24. means we don't want the users to have to type in or know a password.
  25. - We want to allow multiple controller applications to connect to the
  26. control port. So if Vidalia is launching Tor, it can't just keep the
  27. secrets to itself.
  28. Right now there are three authentication approaches supported
  29. by the control protocol: NULL, CookieAuthentication, and
  30. HashedControlPassword. See Sec 5.1 in control-spec.txt for details.
  31. There are a couple of challenges here. The first is: if the controller
  32. launches Tor, how should we teach Tor what authentication approach
  33. it should require, and the secret that goes along with it? Next is:
  34. how should this work when the controller attaches to an existing Tor,
  35. rather than launching Tor itself?
  36. Cookie authentication seems most amenable to letting multiple controller
  37. applications interact with Tor. But that brings in yet another question:
  38. how does the controller guess where to look for the cookie file,
  39. without first knowing what DataDirectory Tor is using?
  40. Design:
  41. We should add a new controller command PROTOCOLINFO that can be sent
  42. as a valid first command (the others being AUTHENTICATE and QUIT). If
  43. PROTOCOLINFO is sent as the first command, the second command must be
  44. either a successful AUTHENTICATE or a QUIT.
  45. If the initial command sequence is not valid, Tor closes the connection.
  46. Spec:
  47. C: "PROTOCOLINFO" *(SP PIVERSION) CRLF
  48. S: "250+PROTOCOLINFO" SP PIVERSION CRLF *InfoLine "250 OK" CRLF
  49. InfoLine = AuthLine / VersionLine / OtherLine
  50. AuthLine = "250-AUTH" SP "METHODS=" AuthMethod *(",")AuthMethod
  51. *(SP "COOKIEFILE=" AuthCookieFile) CRLF
  52. VersionLine = "250-VERSION" SP "Tor=" TorVersion [SP Arguments] CRLF
  53. AuthMethod =
  54. "NULL" / ; No authentication is required
  55. "HASHEDPASSWORD" / ; A controller must supply the original password
  56. "COOKIE" / ; A controller must supply the contents of a cookie
  57. AuthCookieFile = QuotedString
  58. TorVersion = QuotedString
  59. OtherLine = "250-" Keyword [SP Arguments] CRLF
  60. For example:
  61. C: PROTOCOLINFO CRLF
  62. S: "250+PROTOCOLINFO 1" CRLF
  63. S: "250-AUTH Methods=HASHEDPASSWORD,COOKIE COOKIEFILE="/tor/cookie"" CRLF
  64. S: "250-VERSION Tor=0.2.0.5-alpha" CRLF
  65. S: "250 OK" CRLF
  66. Tor MAY give its InfoLines in any order; controllers MUST ignore InfoLines
  67. with keywords it does not recognize. Controllers MUST ignore extraneous
  68. data on any InfoLine.
  69. PIVERSION is there in case we drastically change the syntax one day. For
  70. now it should always be "1", for the controller protocol. Controllers MAY
  71. provide a list of the protocol versions they support; Tor MAY select a
  72. version that the controller does not support.
  73. Right now only two "topics" (AUTH and VERSION) are included, but more
  74. may be included in the future. Controllers must accept lines with
  75. unexpected topics.
  76. AuthCookieFile = QuotedString
  77. AuthMethod is used to specify one or more control authentication
  78. methods that Tor currently accepts.
  79. AuthCookieFile specifies the absolute path and filename of the
  80. authentication cookie that Tor is expecting and is provided iff
  81. the METHODS field contains the method "COOKIE". Controllers MUST handle
  82. escape sequences inside this string.
  83. The VERSION line contains the Tor version.
  84. [What else might we want to include that could be useful? -RD]
  85. Compatibility:
  86. Tor 0.1.2.16 and 0.2.0.4-alpha hang up after the first failed
  87. command. Earlier Tors don't know about this command but don't hang
  88. up. That means controllers will need a mechanism for distinguishing
  89. whether they're talking to a Tor that speaks PROTOCOLINFO or not.
  90. I suggest that the controllers attempt a PROTOCOLINFO. Then:
  91. - If it works, great. Authenticate as required.
  92. - If they get hung up on, reconnect and do a NULL AUTHENTICATE.
  93. - If it's unrecognized but they're not hung up on, do a NULL
  94. AUTHENTICATE.
  95. Unsolved problems:
  96. If Torbutton wants to be a Tor controller one day... talking TCP is
  97. bad enough, but reading from the filesystem is even harder. Is there
  98. a way to let simple programs work with the controller port without
  99. needing all the auth infrastructure?
  100. Once we put this approach in place, the next vulnerability we see will
  101. involve an attacker somehow getting read access to the victim's files
  102. --- and then we're back where we started. This means we still need
  103. to think about how to demand password-based authentication without
  104. bothering the user about it.