commit 8ca253a974c7e6eec9038c2d39a98a245a1ff024 Author: Damian Johnson atagar@torproject.org Date: Wed May 28 09:18:31 2014 -0700

Adding DROPGUARDS support

Adding a Controller method for tor's DROPGUARDS function...

https://trac.torproject.org/projects/tor/ticket/10032 https://gitweb.torproject.org/torspec.git/commitdiff/7c6c7fc --- docs/change_log.rst | 1 + stem/control.py | 22 +++++++++++++++++++--- stem/version.py | 2 ++ test/unit/control/controller.py | 13 +++++++++++++ 4 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/docs/change_log.rst b/docs/change_log.rst index 0bff1b5..ac892d1 100644 --- a/docs/change_log.rst +++ b/docs/change_log.rst @@ -44,6 +44,7 @@ The following are only available within Stem's `git repository * New, better :func:`~stem.connection.connect` function that deprecates :func:`~stem.connection.connect_port` and :func:`~stem.connection.connect_socket_file` * Added :func:`~stem.control.Controller.is_newnym_available` and :func:`~stem.control.Controller.get_newnym_wait` methods to the :class:`~stem.control.Controller` * Added :func:`~stem.control.Controller.get_ports` and :func:`~stem.control.Controller.get_listeners` methods to the :class:`~stem.control.Controller` + * Added :func:`~stem.control.Controller.drop_guards` (:trac:`10032`, :spec:`7c6c7fc`) * Added the id attribute to the :class:`~stem.response.events.ORConnEvent` (:spec:`6f2919a`) * Added `support for CONN_BW events <api/response.html#stem.response.events.ConnectionBandwidthEvent>`_ (:spec:`6f2919a`) * Added `support for CIRC_BW events <api/response.html#stem.response.events.CircuitBandwidthEvent>`_ (:spec:`6f2919a`) diff --git a/stem/control.py b/stem/control.py index 27cce01..78e949c 100644 --- a/stem/control.py +++ b/stem/control.py @@ -122,7 +122,8 @@ If you're fine with allowing your script to raise exceptions then this can be mo |- is_newnym_available - true if tor would presently accept a NEWNYM signal |- get_newnym_wait - seconds until tor would accept a NEWNYM signal |- is_geoip_unavailable - true if we've discovered our geoip db to be unavailable - +- map_address - maps one address to another such that connections to the original are replaced with the other + |- map_address - maps one address to another such that connections to the original are replaced with the other + +- drop_guards - drops our set of guard relays and picks a new set

BaseController - Base controller class asynchronous message handling |- msg - communicates with the tor process @@ -2450,8 +2451,9 @@ class Controller(BaseController): :param stem.RelayEndReason reason: reason the stream is closing :param str flag: not currently used

- :raises: :class:`stem.InvalidArguments` if the stream or reason are not recognized - :raises: :class:`stem.InvalidRequest` if the stream and/or reason are missing + :raises: + * :class:`stem.InvalidArguments` if the stream or reason are not recognized + * :class:`stem.InvalidRequest` if the stream and/or reason are missing """

# there's a single value offset between RelayEndReason.index_of() and the @@ -2560,6 +2562,20 @@ class Controller(BaseController):

return response.entries

+ def drop_guards(self): + """ + Drops our present guard nodes and picks a new set. + + .. versionadded:: 1.2.0 + + :raises: :class:`stem.ControllerError` if Tor couldn't fulfill the request + """ + + if self.get_version() < stem.version.Requirement.DROPGUARDS: + raise stem.UnsatisfiableRequest('DROPGUARDS was added in tor version %s' % stem.version.Requirement.DROPGUARDS) + + self.msg('DROPGUARDS') + def _post_authentication(self): super(Controller, self)._post_authentication()

diff --git a/stem/version.py b/stem/version.py index e3ba69b..791ce7b 100644 --- a/stem/version.py +++ b/stem/version.py @@ -30,6 +30,7 @@ easily parsed and compared, for instance... Requirement Description ===================================== =========== **AUTH_SAFECOOKIE** SAFECOOKIE authentication method + **DROPGUARDS** DROPGUARDS requests **EVENT_AUTHDIR_NEWDESCS** AUTHDIR_NEWDESC events **EVENT_BUILDTIMEOUT_SET** BUILDTIMEOUT_SET events **EVENT_CIRC_MINOR** CIRC_MINOR events @@ -333,6 +334,7 @@ safecookie_req.greater_than(Version("0.2.3.13"))

Requirement = stem.util.enum.Enum( ("AUTH_SAFECOOKIE", safecookie_req), + ("DROPGUARDS", Version('0.2.5.1-alpha')), ("EVENT_AUTHDIR_NEWDESCS", Version('0.1.1.10-alpha')), ("EVENT_BUILDTIMEOUT_SET", Version('0.2.2.7-alpha')), ("EVENT_CIRC_MINOR", Version('0.2.3.11-alpha')), diff --git a/test/unit/control/controller.py b/test/unit/control/controller.py index 7422430..bc6711b 100644 --- a/test/unit/control/controller.py +++ b/test/unit/control/controller.py @@ -525,3 +525,16 @@ class TestControl(unittest.TestCase):

for test_input in malformed_inputs: self.assertRaises(ProtocolError, _parse_circ_path, test_input) + + @patch('stem.control.Controller.get_version') + def test_drop_guards(self, get_version_mock): + """ + Exercises the drop_guards() method. + """ + + get_version_mock.return_value = stem.version.Version('0.1.0.14') + self.assertRaises(UnsatisfiableRequest, self.controller.drop_guards) + + with patch('stem.control.Controller.msg', Mock(return_value = None)): + get_version_mock.return_value = stem.version.Version('0.2.5.2') + self.controller.drop_guards()