commit af691f5b54d1f571ee51d8c67010ea19e4c672fd Author: Damian Johnson <atagar@torproject.org> Date: Sat May 5 17:48:29 2012 -0700 Supporting controllers in the connection module Users will be using a BaseController subclass unless they really need to work at a low level, in which case they'll be using a ControlSocket. Making the connection module (which does authentication) support both. --- stem/connection.py | 86 +++++++++++++++++++------------ test/integ/connection/authentication.py | 26 +++++++--- test/integ/connection/connect.py | 4 +- test/runner.py | 38 +++++++++++--- 4 files changed, 103 insertions(+), 51 deletions(-) diff --git a/stem/connection.py b/stem/connection.py index d950049..825edf5 100644 --- a/stem/connection.py +++ b/stem/connection.py @@ -277,7 +277,7 @@ def _connect(control_socket, password, chroot_path, controller): print "Unable to authenticate: %s" % exc return None -def authenticate(control_socket, password = None, chroot_path = None, protocolinfo_response = None): +def authenticate(controller, password = None, chroot_path = None, protocolinfo_response = None): """ Authenticates to a control socket using the information provided by a PROTOCOLINFO response. In practice this will often be all we need to @@ -288,7 +288,8 @@ def authenticate(control_socket, password = None, chroot_path = None, protocolin about, then have a AuthenticationFailure catch-all at the end. Arguments: - control_socket (stem.socket.ControlSocket) - socket to be authenticated + controller (stem.socket.ControlSocket or stem.control.BaseController) - + tor controller connection to be authenticated password (str) - passphrase to present to the socket if it uses password authentication (skips password auth if None) chroot_path (str) - path prefix if in a chroot environment @@ -302,8 +303,8 @@ def authenticate(control_socket, password = None, chroot_path = None, protocolin follows... stem.connection.IncorrectSocketType - The control_socket does not speak the tor control protocol. Most often - this happened because the user confused the SocksPort or ORPort with the + The controller does not speak the tor control protocol. Most often this + happened because the user confused the SocksPort or ORPort with the ControlPort. stem.connection.UnrecognizedAuthMethods @@ -355,7 +356,7 @@ def authenticate(control_socket, password = None, chroot_path = None, protocolin if not protocolinfo_response: try: - protocolinfo_response = get_protocolinfo(control_socket) + protocolinfo_response = get_protocolinfo(controller) except stem.socket.ProtocolError: raise IncorrectSocketType("unable to use the control socket") except stem.socket.SocketError, exc: @@ -397,16 +398,16 @@ def authenticate(control_socket, password = None, chroot_path = None, protocolin try: if auth_type == AuthMethod.NONE: - authenticate_none(control_socket, False) + authenticate_none(controller, False) elif auth_type == AuthMethod.PASSWORD: - authenticate_password(control_socket, password, False) + authenticate_password(controller, password, False) elif auth_type == AuthMethod.COOKIE: cookie_path = protocolinfo_response.cookie_path if chroot_path: cookie_path = os.path.join(chroot_path, cookie_path.lstrip(os.path.sep)) - authenticate_cookie(control_socket, cookie_path, False) + authenticate_cookie(controller, cookie_path, False) return # success! except OpenAuthRejected, exc: @@ -439,7 +440,7 @@ def authenticate(control_socket, password = None, chroot_path = None, protocolin raise AssertionError("BUG: Authentication failed without providing a recognized exception: %s" % str(auth_exceptions)) -def authenticate_none(control_socket, suppress_ctl_errors = True): +def authenticate_none(controller, suppress_ctl_errors = True): """ Authenticates to an open control socket. All control connections need to authenticate before they can be used, even if tor hasn't been configured to @@ -452,7 +453,8 @@ def authenticate_none(control_socket, suppress_ctl_errors = True): For general usage use the authenticate() function instead. Arguments: - control_socket (stem.socket.ControlSocket) - socket to be authenticated + controller (stem.socket.ControlSocket or stem.control.BaseController) - + tor controller connection suppress_ctl_errors (bool) - reports raised stem.socket.ControllerError as authentication rejection if True, otherwise they're re-raised @@ -462,23 +464,22 @@ def authenticate_none(control_socket, suppress_ctl_errors = True): """ try: - control_socket.send("AUTHENTICATE") - auth_response = control_socket.recv() + auth_response = _msg(controller, "AUTHENTICATE") # if we got anything but an OK response then error if str(auth_response) != "OK": - try: control_socket.connect() + try: controller.connect() except: pass raise OpenAuthRejected(str(auth_response), auth_response) except stem.socket.ControllerError, exc: - try: control_socket.connect() + try: controller.connect() except: pass if not suppress_ctl_errors: raise exc else: raise OpenAuthRejected("Socket failed (%s)" % exc) -def authenticate_password(control_socket, password, suppress_ctl_errors = True): +def authenticate_password(controller, password, suppress_ctl_errors = True): """ Authenticates to a control socket that uses a password (via the HashedControlPassword torrc option). Quotes in the password are escaped. @@ -495,7 +496,8 @@ def authenticate_password(control_socket, password, suppress_ctl_errors = True): future versions. Arguments: - control_socket (stem.socket.ControlSocket) - socket to be authenticated + controller (stem.socket.ControlSocket or stem.control.BaseController) - + tor controller connection password (str) - passphrase to present to the socket suppress_ctl_errors (bool) - reports raised stem.socket.ControllerError as authentication rejection if True, otherwise they're re-raised @@ -514,12 +516,11 @@ def authenticate_password(control_socket, password, suppress_ctl_errors = True): password = password.replace('"', '\\"') try: - control_socket.send("AUTHENTICATE \"%s\"" % password) - auth_response = control_socket.recv() + auth_response = _msg(controller, "AUTHENTICATE \"%s\"" % password) # if we got anything but an OK response then error if str(auth_response) != "OK": - try: control_socket.connect() + try: controller.connect() except: pass # all we have to go on is the error message from tor... @@ -531,13 +532,13 @@ def authenticate_password(control_socket, password, suppress_ctl_errors = True): else: raise PasswordAuthRejected(str(auth_response), auth_response) except stem.socket.ControllerError, exc: - try: control_socket.connect() + try: controller.connect() except: pass if not suppress_ctl_errors: raise exc else: raise PasswordAuthRejected("Socket failed (%s)" % exc) -def authenticate_cookie(control_socket, cookie_path, suppress_ctl_errors = True): +def authenticate_cookie(controller, cookie_path, suppress_ctl_errors = True): """ Authenticates to a control socket that uses the contents of an authentication cookie (generated via the CookieAuthentication torrc option). This does basic @@ -559,7 +560,8 @@ def authenticate_cookie(control_socket, cookie_path, suppress_ctl_errors = True) future versions. Arguments: - control_socket (stem.socket.ControlSocket) - socket to be authenticated + controller (stem.socket.ControlSocket or stem.control.BaseController) - + tor controller connection cookie_path (str) - path of the authentication cookie to send to tor suppress_ctl_errors (bool) - reports raised stem.socket.ControllerError as authentication rejection if True, otherwise they're re-raised @@ -599,12 +601,12 @@ def authenticate_cookie(control_socket, cookie_path, suppress_ctl_errors = True) raise UnreadableCookieFile("Authentication failed: unable to read '%s' (%s)" % (cookie_path, exc), cookie_path) try: - control_socket.send("AUTHENTICATE %s" % binascii.b2a_hex(auth_cookie_contents)) - auth_response = control_socket.recv() + msg = "AUTHENTICATE %s" % binascii.b2a_hex(auth_cookie_contents) + auth_response = _msg(controller, msg) # if we got anything but an OK response then error if str(auth_response) != "OK": - try: control_socket.connect() + try: controller.connect() except: pass # all we have to go on is the error message from tor... @@ -617,20 +619,21 @@ def authenticate_cookie(control_socket, cookie_path, suppress_ctl_errors = True) else: raise CookieAuthRejected(str(auth_response), cookie_path, auth_response) except stem.socket.ControllerError, exc: - try: control_socket.connect() + try: controller.connect() except: pass if not suppress_ctl_errors: raise exc else: raise CookieAuthRejected("Socket failed (%s)" % exc, cookie_path) -def get_protocolinfo(control_socket): +def get_protocolinfo(controller): """ Issues a PROTOCOLINFO query to a control socket, getting information about the tor process running on it. If the socket is already closed then it is first reconnected. Arguments: - control_socket (stem.socket.ControlSocket) - connected tor control socket + controller (stem.socket.ControlSocket or stem.control.BaseController) - + tor controller connection Returns: stem.connection.ProtocolInfoResponse provided by tor @@ -642,8 +645,7 @@ def get_protocolinfo(control_socket): """ try: - control_socket.send("PROTOCOLINFO 1") - protocolinfo_response = control_socket.recv() + protocolinfo_response = _msg(controller, "PROTOCOLINFO 1") except: protocolinfo_response = None @@ -651,17 +653,22 @@ def get_protocolinfo(control_socket): # next followed by authentication. Transparently reconnect if that happens. if not protocolinfo_response or str(protocolinfo_response) == "Authentication required.": - control_socket.connect() + controller.connect() try: - control_socket.send("PROTOCOLINFO 1") - protocolinfo_response = control_socket.recv() + protocolinfo_response = _msg(controller, "PROTOCOLINFO 1") except stem.socket.SocketClosed, exc: raise stem.socket.SocketError(exc) ProtocolInfoResponse.convert(protocolinfo_response) - # attempt ot expand relative cookie paths via the control port or socket file + # attempt to expand relative cookie paths via the control port or socket file + + if isinstance(controller, stem.socket.ControlSocket): + control_socket = controller + else: + control_socket = controller.get_socket() + if isinstance(control_socket, stem.socket.ControlPort): if control_socket.get_address() == "127.0.0.1": pid_method = stem.util.system.get_pid_by_port @@ -672,6 +679,17 @@ def get_protocolinfo(control_socket): return protocolinfo_response +def _msg(controller, message): + """ + Sends and receives a message with either a ControlSocket or BaseController. + """ + + if isinstance(controller, stem.socket.ControlSocket): + controller.send(message) + return controller.recv() + else: + return controller.msg(message) + def _expand_cookie_path(protocolinfo_response, pid_resolver, pid_resolution_arg): """ Attempts to expand a relative cookie path with the given pid resolver. This diff --git a/test/integ/connection/authentication.py b/test/integ/connection/authentication.py index f80b848..c209d2b 100644 --- a/test/integ/connection/authentication.py +++ b/test/integ/connection/authentication.py @@ -80,7 +80,7 @@ class TestAuthenticate(unittest.TestCase): def setUp(self): test.runner.require_control(self) - def test_authenticate_general(self): + def test_authenticate_general_socket(self): """ Tests that the authenticate function can authenticate to our socket. """ @@ -88,7 +88,17 @@ class TestAuthenticate(unittest.TestCase): runner = test.runner.get_runner() with runner.get_tor_socket(False) as control_socket: stem.connection.authenticate(control_socket, test.runner.CONTROL_PASSWORD, runner.get_chroot()) - test.runner.exercise_socket(self, control_socket) + test.runner.exercise_controller(self, control_socket) + + def test_authenticate_general_controller(self): + """ + Tests that the authenticate function can authenticate via a Controller. + """ + + runner = test.runner.get_runner() + with runner.get_tor_controller(False) as controller: + stem.connection.authenticate(controller, test.runner.CONTROL_PASSWORD, runner.get_chroot()) + test.runner.exercise_controller(self, controller) def test_authenticate_general_example(self): """ @@ -108,7 +118,7 @@ class TestAuthenticate(unittest.TestCase): try: # this authenticate call should work for everything but password-only auth stem.connection.authenticate(control_socket, chroot_path = runner.get_chroot()) - test.runner.exercise_socket(self, control_socket) + test.runner.exercise_controller(self, control_socket) except stem.connection.IncorrectSocketType: self.fail() except stem.connection.MissingPassword: @@ -117,7 +127,7 @@ class TestAuthenticate(unittest.TestCase): try: stem.connection.authenticate_password(control_socket, controller_password) - test.runner.exercise_socket(self, control_socket) + test.runner.exercise_controller(self, control_socket) except stem.connection.PasswordAuthFailed: self.fail() except stem.connection.AuthenticationFailure: @@ -144,7 +154,7 @@ class TestAuthenticate(unittest.TestCase): self.assertRaises(stem.connection.MissingPassword, stem.connection.authenticate, control_socket) else: stem.connection.authenticate(control_socket, chroot_path = runner.get_chroot()) - test.runner.exercise_socket(self, control_socket) + test.runner.exercise_controller(self, control_socket) # tests with the incorrect password with runner.get_tor_socket(False) as control_socket: @@ -152,12 +162,12 @@ class TestAuthenticate(unittest.TestCase): self.assertRaises(stem.connection.IncorrectPassword, stem.connection.authenticate, control_socket, "blarg") else: stem.connection.authenticate(control_socket, "blarg", runner.get_chroot()) - test.runner.exercise_socket(self, control_socket) + test.runner.exercise_controller(self, control_socket) # tests with the right password with runner.get_tor_socket(False) as control_socket: stem.connection.authenticate(control_socket, test.runner.CONTROL_PASSWORD, runner.get_chroot()) - test.runner.exercise_socket(self, control_socket) + test.runner.exercise_controller(self, control_socket) def test_authenticate_none(self): """ @@ -299,7 +309,7 @@ class TestAuthenticate(unittest.TestCase): elif auth_type == stem.connection.AuthMethod.COOKIE: stem.connection.authenticate_cookie(control_socket, auth_arg) - test.runner.exercise_socket(self, control_socket) + test.runner.exercise_controller(self, control_socket) except stem.connection.AuthenticationFailure, exc: # authentication functions should re-attach on failure self.assertTrue(control_socket.is_alive()) diff --git a/test/integ/connection/connect.py b/test/integ/connection/connect.py index 29cf2dc..ac66ceb 100644 --- a/test/integ/connection/connect.py +++ b/test/integ/connection/connect.py @@ -34,7 +34,7 @@ class TestConnect(unittest.TestCase): controller = stem.connection.Controller.NONE) if test.runner.Torrc.PORT in runner.get_options(): - test.runner.exercise_socket(self, control_socket) + test.runner.exercise_controller(self, control_socket) control_socket.close() else: self.assertEquals(control_socket, None) @@ -53,7 +53,7 @@ class TestConnect(unittest.TestCase): controller = stem.connection.Controller.NONE) if test.runner.Torrc.SOCKET in runner.get_options(): - test.runner.exercise_socket(self, control_socket) + test.runner.exercise_controller(self, control_socket) control_socket.close() else: self.assertEquals(control_socket, None) diff --git a/test/runner.py b/test/runner.py index 6702b8b..66636f2 100644 --- a/test/runner.py +++ b/test/runner.py @@ -8,7 +8,7 @@ TorInaccessable - Tor can't be queried for the information require_control - skips the test unless tor provides a controller endpoint require_version - skips the test unless we meet a tor version requirement -exercise_socket - Does a basic sanity check that a control socket can be used +exercise_controller - basic sanity check that a controller connection can be used get_runner - Singleton for fetching our runtime context. Runner - Runtime context for our integration tests. @@ -25,7 +25,8 @@ Runner - Runtime context for our integration tests. |- get_tor_cwd - current working directory of our tor process |- get_chroot - provides the path of our emulated chroot if we have one |- get_pid - process id of our tor process - |- get_tor_socket - provides a socket to the tor instance + |- get_tor_socket - provides a socket to our test instance + |- get_tor_controller - provides a controller for our test instance |- get_tor_version - provides the version of tor we're running against +- get_tor_command - provides the command used to start tor """ @@ -115,14 +116,15 @@ def require_version(test_case, req_version): if get_runner().get_tor_version() < req_version: test_case.skipTest("(requires %s)" % req_version) -def exercise_socket(test_case, control_socket): +def exercise_controller(test_case, controller): """ Checks that we can now use the socket by issuing a 'GETINFO config-file' query. Arguments: test_case (unittest.TestCase) - test being ran - control_socket (stem.socket.ControlSocket) - socket to be tested + controller (stem.socket.ControlSocket or stem.control.BaseController) - + tor controller connection to be authenticated """ runner = get_runner() @@ -131,8 +133,12 @@ def exercise_socket(test_case, control_socket): if chroot_path and torrc_path.startswith(chroot_path): torrc_path = torrc_path[len(chroot_path):] - control_socket.send("GETINFO config-file") - config_file_response = control_socket.recv() + if isinstance(controller, stem.socket.ControlSocket): + controller.send("GETINFO config-file") + config_file_response = controller.recv() + else: + config_file_response = controller.msg("GETINFO config-file") + test_case.assertEquals("config-file=%s\nOK" % torrc_path, str(config_file_response)) def get_runner(): @@ -429,7 +435,7 @@ class Runner: def get_tor_socket(self, authenticate = True): """ - Provides a socket connected to the tor test instance's control socket. + Provides a socket connected to our tor test instance. Arguments: authenticate (bool) - if True then the socket is authenticated @@ -452,6 +458,24 @@ class Runner: return control_socket + def get_tor_controller(self, authenticate = True): + """ + Provides a controller connected to our tor test instance. + + Arguments: + authenticate (bool) - if True then the socket is authenticated + + Returns: + stem.socket.BaseController connected with our testing instance + + Raises: + TorInaccessable if tor can't be connected to + """ + + # TODO: replace with our general controller when we have one + control_socket = self.get_tor_socket(authenticate) + return stem.control.BaseController(control_socket) + def get_tor_version(self): """ Queries our test instance for tor's version.