[tor-commits] [tor-design-2012/master] add a bit more about the control protocol

[nickm at torproject.org]

commit d69a468a07322588d60820c3e5752be05d97cdbc
Author: Nick Mathewson <nickm at torproject.org>
Date:   Wed Nov 14 01:04:09 2012 -0500

    add a bit more about the control protocol
---
 todo                |    4 ++--
 tor-design-2012.tex |   31 +++++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/todo b/todo
index da35f25..aab4d6a 100644
--- a/todo
+++ b/todo
@@ -25,10 +25,10 @@ ITEMS:
        o Bandwidth authorities
        o Path selection rules
      o stream isolation
-   . Integrate content from the third blog post [steven]
+   o Integrate content from the third blog post [steven]
      o link protocol tls
      X rise and fall of .exit
-     . controller protocol
+     o controller protocol
      o torbutton
      o tor browser bundle
 
diff --git a/tor-design-2012.tex b/tor-design-2012.tex
index 69c04a6..38a6eed 100644
--- a/tor-design-2012.tex
+++ b/tor-design-2012.tex
@@ -1826,6 +1826,37 @@ caches,'' and periodically fetch network consensus
 documents; clients can contact a cache instead, once they
 know who the caches are.
 
+\subsection{The Tor controller protocol}
+
+Tor has always had a minimalist user interface---it can be
+configured on the command line or a configuration file and sends
+output to a log file. This was fine for advanced users, but most
+users will prefer a GUI. Building a GUI into Tor would be
+difficult, and would force certain choices (e.g. GUI toolkit) to
+be made which might not suit all users and all
+platforms. Therefore Tor includes an interface for other programs to
+communicate with the Tor daemon, extracting information to display
+on the GUI and changing the Tor configuration based on user
+actions.  This interface is an ASCII-based protocol, implemented
+over a local socket, to allow another program to control Tor.
+
+The control protocol has also proven useful to researchers
+experimenting with Tor. Initially the functionality exposed in the
+control protocol was simply that exposed by the configuration file
+and log files. Providing status information in a specified and
+machine-readable format made the task of monitoring and
+controlling Tor easier. Later, functionality was added to the
+control protocol which should not be exposed to ordinary Tor users
+but is useful to researchers, such as allowing controllers to
+arbitrarily control the path selection process.
+
+To prevent  arbitrary local processes from changing Tor's
+configuration to make it less secure, the control protocol
+provides authentication mechanisms so that only authorized local
+processes (ones that can read an appropriate file on the
+filesystem, or that know an appropriate passord) can connect to
+the controller port.
+
 \section{Attacks and Defenses}
 \label{sec:attacks}