[tor-commits] [stem/master] Explain hidden service descriptors in the tutorial

[atagar at torproject.org]

commit 5c5f5ca068147aabd68bbd939b5f6821a82912f1
Author: Damian Johnson <atagar at torproject.org>
Date:   Mon May 11 14:38:54 2015 -0700

    Explain hidden service descriptors in the tutorial
    
    Tempted to put this on the descriptor tutorial, but honestly a better fit here.
    Basic demos for using our descriptor fetching capabilities.
---
 docs/tutorials/mirror_mirror_on_the_wall.rst |   19 +++----
 docs/tutorials/over_the_river.rst            |   71 ++++++++++++++++++++++++++
 2 files changed, 81 insertions(+), 9 deletions(-)

diff --git a/docs/tutorials/mirror_mirror_on_the_wall.rst b/docs/tutorials/mirror_mirror_on_the_wall.rst
index 26a158c..967ec71 100644
--- a/docs/tutorials/mirror_mirror_on_the_wall.rst
+++ b/docs/tutorials/mirror_mirror_on_the_wall.rst
@@ -22,15 +22,16 @@ up of documents called **descriptors**.
 
 There are several different kinds of descriptors, the most common ones being...
 
-====================================================================== ===========
-Descriptor Type                                                        Description
-====================================================================== ===========
-`Server Descriptor <../api/descriptor/server_descriptor.html>`_        Information that relays publish about themselves. Tor clients once downloaded this information, but now they use microdescriptors instead.
-`ExtraInfo Descriptor <../api/descriptor/extrainfo_descriptor.html>`_  Relay information that Tor clients do not need in order to function. This is self-published, like server descriptors, but not downloaded by default.
-`Microdescriptor <../api/descriptor/microdescriptor.html>`_            Minimalistic document that just includes the information necessary for Tor clients to work.
-`Network Status Document <../api/descriptor/networkstatus.html>`_      Though Tor relays are decentralized, the directories that track the overall network are not. These central points are called **directory authorities**, and every hour they publish a document called a **consensus** (aka, network status document). The consensus in turn is made up of **router status entries**.
-`Router Status Entry <../api/descriptor/router_status_entry.html>`_    Relay information provided by the directory authorities including flags, heuristics used for relay selection, etc.
-====================================================================== ===========
+================================================================================ ===========
+Descriptor Type                                                                  Description
+================================================================================ ===========
+`Server Descriptor <../api/descriptor/server_descriptor.html>`_                  Information that relays publish about themselves. Tor clients once downloaded this information, but now they use microdescriptors instead.
+`ExtraInfo Descriptor <../api/descriptor/extrainfo_descriptor.html>`_            Relay information that Tor clients do not need in order to function. This is self-published, like server descriptors, but not downloaded by default.
+`Microdescriptor <../api/descriptor/microdescriptor.html>`_                      Minimalistic document that just includes the information necessary for Tor clients to work.
+`Network Status Document <../api/descriptor/networkstatus.html>`_                Though Tor relays are decentralized, the directories that track the overall network are not. These central points are called **directory authorities**, and every hour they publish a document called a **consensus** (aka, network status document). The consensus in turn is made up of **router status entries**.
+`Router Status Entry <../api/descriptor/router_status_entry.html>`_              Relay information provided by the directory authorities including flags, heuristics used for relay selection, etc.
+`Hidden Service Descriptor <../api/descriptor/hidden_service_descriptor.html>`_  Information pertaining to a `Hidden Service <https://www.torproject.org/docs/hidden-services.html.en>`_. These can only be `queried through the tor process <over_the_river.html#how-can-i-get-hidden-service-descriptors>`_.
+================================================================================ ===========
 
 .. _where-can-i-get-the-current-descriptors:
 
diff --git a/docs/tutorials/over_the_river.rst b/docs/tutorials/over_the_river.rst
index 2d51541..b898ddc 100644
--- a/docs/tutorials/over_the_river.rst
+++ b/docs/tutorials/over_the_river.rst
@@ -100,3 +100,74 @@ Now if we run this...
 
 .. image:: /_static/hidden_service.png
 
+.. _how-can-i-get--hidden-service-descriptors:
+
+How can I get hidden service descriptors?
+-----------------------------------------
+
+Like relays, hidden services publish documents about themselves called **hidden
+service descriptors**. These contain low level details for establishing
+connections. Hidden service descriptors are available from the tor process via
+its :func:`~stem.control.Controller.get_hidden_service_descriptor` method...
+
+::
+
+  from stem.control import Controller
+
+  with Controller.from_port(port = 9051) as controller:
+    controller.authenticate()
+
+    # descriptor of duck-duck-go's hidden service (http://3g2upl4pq6kufc4m.onion)
+
+    print controller.get_hidden_service_descriptor('3g2upl4pq6kufc4m')
+
+::
+
+  % python print_duck_duck_go_descriptor.py
+
+  rendezvous-service-descriptor e5dkwgp6vt7axoozixrbgjymyof7ab6u
+  version 2
+  permanent-key
+  -----BEGIN RSA PUBLIC KEY-----
+  MIGJAoGBAJ/SzzgrXPxTlFrKVhXh3buCWv2QfcNgncUpDpKouLn3AtPH5Ocys0jE
+  aZSKdvaiQ62md2gOwj4x61cFNdi05tdQjS+2thHKEm/KsB9BGLSLBNJYY356bupg
+  I5gQozM65ENelfxYlysBjJ52xSDBd8C4f/p9umdzaaaCmzXG/nhzAgMBAAE=
+  -----END RSA PUBLIC KEY-----
+  secret-id-part bmsctib2pzirgo7cltlxdm5fxqcitt5e
+  publication-time 2015-05-11 20:00:00
+  protocol-versions 2,3
+  introduction-points
+  -----BEGIN MESSAGE-----
+  aW50cm9kdWN0aW9uLXBvaW50IHZzcm4ycGNtdzNvZ21mNGo3dGpxeHptdml1Y2Rr
+  NGtpCmlwLWFkZHJlc3MgMTc2LjkuNTkuMTcxCm9uaW9uLXBvcnQgOTAwMQpvbmlv
+  ... etc...
+
+A hidden service's introduction points are a base64 encoded field that's
+possibly encrypted. These can be decoded (and decrypted if necessary) with the
+descriptor's
+:func:`~stem.descriptor.hidden_service_descriptor.HiddenServiceDescriptor.introduction_points`
+method.
+
+::
+
+  from stem.control import Controller
+
+  with Controller.from_port(port = 9051) as controller:
+    controller.authenticate()
+    desc = controller.get_hidden_service_descriptor('3g2upl4pq6kufc4m')
+
+    print "DuckDuckGo's introduction points are...\n"
+
+    for introduction_point in desc.introduction_points():
+      print '  %s:%s => %s' % (introduction_point.address, introduction_point.port, introduction_point.identifier)
+
+::
+
+  % python print_duck_duck_go_introduction_points.py
+
+  DuckDuckGo's introduction points are...
+
+    176.9.59.171:9001 => vsrn2pcmw3ogmf4j7tjqxzmviucdk4ki
+    104.131.106.181:9001 => gcl2kpqx5qnkpgxjf6x7ulqncoqj7ghh
+    188.166.58.218:443 => jeymnbhs2d6l2oib7jjvweavg45m6gju
+