commit a3d7cf810ab5ccd2d92ea0591c3b9142fe6f120e Author: Damian Johnson atagar@torproject.org Date: Mon May 11 19:26:53 2015 -0700
Discuss descriptor validation in the tutorials
Validation was relatively unimportant in prior releases since... well, it was the default. Only folks that opted out of it for performance reasons ever gave it a thought.
Now that it's opt-in adding a quick, simple note to our tutorials about it. --- docs/api/response.rst | 1 + docs/tutorials/mirror_mirror_on_the_wall.rst | 33 ++++++++++++++++++++++++++ docs/tutorials/over_the_river.rst | 30 ++++++++++++++++++----- stem/control.py | 2 +- 4 files changed, 59 insertions(+), 7 deletions(-)
diff --git a/docs/api/response.rst b/docs/api/response.rst index b2dcda0..53d27c1 100644 --- a/docs/api/response.rst +++ b/docs/api/response.rst @@ -6,6 +6,7 @@ Controller Responses Responses ---------
+.. autoclass:: stem.response.add_onion.AddOnionResponse .. autoclass:: stem.response.authchallenge.AuthChallengeResponse .. autoclass:: stem.response.getconf.GetConfResponse .. autoclass:: stem.response.getinfo.GetInfoResponse diff --git a/docs/tutorials/mirror_mirror_on_the_wall.rst b/docs/tutorials/mirror_mirror_on_the_wall.rst index 967ec71..ec3a9f8 100644 --- a/docs/tutorials/mirror_mirror_on_the_wall.rst +++ b/docs/tutorials/mirror_mirror_on_the_wall.rst @@ -8,6 +8,7 @@ with what they are and where to get them then you may want to skip to the end. * :ref:`where-can-i-get-the-current-descriptors` * :ref:`where-can-i-get-past-descriptors` * :ref:`can-i-get-descriptors-from-the-tor-process` +* :ref:`validating-the-descriptors-content` * :ref:`saving-and-loading-descriptors` * :ref:`putting-it-together`
@@ -143,6 +144,38 @@ through Tor's control socket... for desc in parse_file('/home/atagar/.tor/cached-consensus'): print 'found relay %s (%s)' % (desc.nickname, desc.fingerprint)
+.. _validating-the-descriptors-content: + +Validating the descriptor's content +----------------------------------- + +Stem can optionally validate descriptors, checking their integrity and +compliance with Tor's specs. This does the following... + +* Checks that we have mandatory fields, and that their content conforms with + what Tor's spec says they should have. This can be useful when data + integrity is important to you since it provides an upfront assurance that + the descriptor's correct (no need for 'None' checks). + +* If you have **pycrypto** we'll validate signatures for descriptor types + where that has been implemented (such as server and hidden service + descriptors). + +Prior to Stem 1.4.0 descriptors were validated by default, but this has become +opt-in since then. + +General rule of thumb: if *speed* is your chief concern then leave it off, but +if *correctness* or *signature validation* is important then turn it on. +Validating is as simple as including **validate = True** in any method that +provides descriptors... + +:: + + from stem.descriptor import parse_file + + for desc in parse_file('/home/atagar/.tor/cached-consensus', validate = True): + print 'found relay %s (%s)' % (desc.nickname, desc.fingerprint) + .. _saving-and-loading-descriptors:
Saving and loading descriptors diff --git a/docs/tutorials/over_the_river.rst b/docs/tutorials/over_the_river.rst index 90ae7dd..ff4b324 100644 --- a/docs/tutorials/over_the_river.rst +++ b/docs/tutorials/over_the_river.rst @@ -6,9 +6,20 @@ give you a way of providing a service without exposing your address. These services are only accessible through Tor or `Tor2web https://tor2web.org/`_, and useful for a surprising number of things...
- * **Hosting an anonymized site**. This is usually the first thing that comes to mind, and something we'll demonstrate in a sec. - * Providing an **endpoint Tor users can reach** without exiting the Tor network. This eliminates the risk of an unreliable or malicious exit getting in the way. Great examples of this are `Facebook http://arstechnica.com/security/2014/10/facebook-offers-hidden-service-to-tor-users/`_ (*facebookcorewwwi.onion*) and `DuckDuckGo https://lists.torproject.org/pipermail/tor-talk/2010-August/003095.html`_ (*3g2upl4pq6kufc4m.onion*). - * **Personal services**. For instance you can host your home SSH server as a hidden service to prevent eavesdroppers from knowing where you live while traveling abroad. +* **Hosting an anonymized site**. This is usually the first thing that comes to + mind, and something we'll demonstrate in a sec. + +* Providing an **endpoint Tor users can reach** without exiting the Tor + network. This eliminates the risk of an unreliable or malicious exit getting + in the way. Great examples of this are `Facebook + http://arstechnica.com/security/2014/10/facebook-offers-hidden-service-to-tor-users/`_ + (*facebookcorewwwi.onion*) and `DuckDuckGo + https://lists.torproject.org/pipermail/tor-talk/2010-August/003095.html`_ + (*3g2upl4pq6kufc4m.onion*). + +* **Personal services**. For instance you can host your home SSH server as a + hidden service to prevent eavesdroppers from knowing where you live while + traveling abroad.
`Tor2web https://tor2web.org/`_ provides a quick and easy way of seeing if your hidden service is working. To use it simply replace the **.onion** of @@ -22,16 +33,23 @@ your address with **.tor2web.org**... Running a hidden service ------------------------
-Hidden services can be `configured through your torrc https://www.torproject.org/docs/tor-manual.html.en#_hidden_service_options`_, but Stem also provides some methods to easily work with them... +Hidden services can be `configured through your torrc +https://www.torproject.org/docs/tor-manual.html.en#_hidden_service_options`_, +but Stem also provides some methods to easily work with them...
* :func:`~stem.control.Controller.create_hidden_service` * :func:`~stem.control.Controller.remove_hidden_service` * :func:`~stem.control.Controller.get_hidden_service_conf` * :func:`~stem.control.Controller.set_hidden_service_conf`
-The main threat to your anonymity when running a hidden service is the service itself. Debug information for instance might leak your real address, undermining what Tor provides. This includes the following example, **do not rely on it not to leak**. +The main threat to your anonymity when running a hidden service is the service +itself. Debug information for instance might leak your real address, +undermining what Tor provides. This includes the following example, **do not +rely on it not to leak**.
-But with that out of the way lets take a look at a simple `Flask http://flask.pocoo.org/`_ example based on one by `Jordan Wright https://jordan-wright.github.io/blog/2014/10/06/creating-tor-hidden-services-with-python/`_... +But with that out of the way lets take a look at a simple `Flask +http://flask.pocoo.org/`_ example based on one by `Jordan Wright +https://jordan-wright.github.io/blog/2014/10/06/creating-tor-hidden-services-with-python/`_...
::
diff --git a/stem/control.py b/stem/control.py index 1c31dda..657f559 100644 --- a/stem/control.py +++ b/stem/control.py @@ -2615,7 +2615,7 @@ class Controller(BaseController): :param bool await_publication: blocks until our descriptor is successfully published if **True**
- :returns: :class:`~stem.response.AddOnionResponse` with the response + :returns: :class:`~stem.response.add_onion.AddOnionResponse` with the response
:raises: :class:`stem.ControllerError` if the call fails """