[tor-commits] [stem/master] Discuss descriptor validation in the tutorials

atagar at torproject.org atagar at torproject.org
Tue May 12 02:36:12 UTC 2015 

commit a3d7cf810ab5ccd2d92ea0591c3b9142fe6f120e
Author: Damian Johnson <atagar at 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
     """

More information about the tor-commits mailing list