[tor-commits] [stem/master] Descriptor digest example

[atagar at torproject.org]

commit 3e3d9bd5c3a906136168f8d57933b882a06c3872
Author: Damian Johnson <atagar at torproject.org>
Date:   Tue Dec 11 10:16:33 2018 -0800

    Descriptor digest example
    
    Waste not, want not. I wrote this demo script for my recent status report
    (https://blog.atagar.com/november2018/), but on reflection it makes a good
    example for how to use our new digest methods.
---
 docs/_static/digest_chart.png                     | Bin 0 -> 66121 bytes
 docs/_static/example/check_digests.py             |  52 ++++++++++++++++++++++
 docs/tutorials/double_double_toil_and_trouble.rst |   5 +++
 docs/tutorials/examples/check_digests.rst         |  38 ++++++++++++++++
 4 files changed, 95 insertions(+)

diff --git a/docs/_static/digest_chart.png b/docs/_static/digest_chart.png
new file mode 100644
index 00000000..0a3dc3d5
Binary files /dev/null and b/docs/_static/digest_chart.png differ
diff --git a/docs/_static/example/check_digests.py b/docs/_static/example/check_digests.py
new file mode 100644
index 00000000..2be3c368
--- /dev/null
+++ b/docs/_static/example/check_digests.py
@@ -0,0 +1,52 @@
+import sys
+
+import stem.descriptor.remote
+import stem.util.tor_tools
+
+
+def download_descriptors(fingerprint):
+  """
+  Downloads the descriptors we need to validate this relay. Downloads are
+  parallelized, providing the caller with a tuple of the form...
+
+    (router_status_entry, server_descriptor, extrainfo_descriptor)
+  """
+
+  conensus_query = stem.descriptor.remote.get_consensus()
+  server_desc_query = stem.descriptor.remote.get_server_descriptors(fingerprint)
+  extrainfo_query = stem.descriptor.remote.get_extrainfo_descriptors(fingerprint)
+
+  router_status_entries = filter(lambda desc: desc.fingerprint == fingerprint, conensus_query.run())
+
+  if len(router_status_entries) != 1:
+    raise IOError("Unable to find relay '%s' in the consensus" % fingerprint)
+
+  return (
+    router_status_entries[0],
+    server_desc_query.run()[0],
+    extrainfo_query.run()[0],
+  )
+
+if __name__ == '__main__':
+  fingerprint = raw_input("What relay fingerprint would you like to validate?\n")
+  print('')  # blank line
+
+  if not stem.util.tor_tools.is_valid_fingerprint(fingerprint):
+    print("'%s' is not a valid relay fingerprint" % fingerprint)
+    sys.exit(1)
+
+  try:
+    router_status_entry, server_desc, extrainfo_desc = download_descriptors(fingerprint)
+  except Exception as exc:
+    print(exc)
+    sys.exit(1)
+
+  if router_status_entry.digest == server_desc.digest():
+    print("Server descriptor digest is correct")
+  else:
+    print("Server descriptor digest invalid, expected %s but is %s" % (router_status_entry.digest, server_desc.digest()))
+
+  if server_desc.extra_info_digest == extrainfo_desc.digest():
+    print("Extrainfo descriptor digest is correct")
+  else:
+    print("Extrainfo descriptor digest invalid, expected %s but is %s" % (server_desc.extra_info_digest, extrainfo_desc.digest()))
diff --git a/docs/tutorials/double_double_toil_and_trouble.rst b/docs/tutorials/double_double_toil_and_trouble.rst
index 6701f1dc..c9a63a7b 100644
--- a/docs/tutorials/double_double_toil_and_trouble.rst
+++ b/docs/tutorials/double_double_toil_and_trouble.rst
@@ -132,3 +132,8 @@ Descriptors
 
   Example for writing a Tor consensus to disk, and reading it back.
 
+* `Checking Digests <examples/check_digests.html>`_
+
+  Looking for additional integrity that your descriptor is properly signed?
+  Digests embedded in parent documents provide transitive validation.
+
diff --git a/docs/tutorials/examples/check_digests.rst b/docs/tutorials/examples/check_digests.rst
new file mode 100644
index 00000000..dc2f0ee8
--- /dev/null
+++ b/docs/tutorials/examples/check_digests.rst
@@ -0,0 +1,38 @@
+Checking Descriptor Digests
+===========================
+
+.. image:: /_static/buttons/back.png
+   :target: ../double_double_toil_and_trouble.html
+
+Tor relay information is provided by `multiple documents
+<../mirror_mirror_on_the_wall.html#what-is-a-descriptor>`_. Signed descriptors
+transitively validate others by inclusion of their digest. For example, our
+consensus references server descriptor digest, and server descriptors in turn
+cite extrainfo digests.
+
+To illustrate, here’s a diagram from Iain...
+
+.. image:: /_static/digest_chart.png
+
+Stem can calculate digests from `server
+<../../api/descriptor/server_descriptor.html#stem.descriptor.server_descriptor.ServerDescriptor.digest>`_,
+`extrainfo
+<../../api/descriptor/extrainfo_descriptor.html#stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor.digest>`_,
+`microdescriptor
+<../../api/descriptor/microdescriptor.html#stem.descriptor.microdescriptor.Microdescriptor.digest>`_,
+and `consensus documents
+<../../api/descriptor/networkstatus.html#stem.descriptor.networkstatus.NetworkStatusDocument.digest>`_.
+For instance, to validate an extrainfo descriptor...
+
+.. literalinclude:: /_static/example/check_digests.py
+   :language: python
+
+::
+
+  % python check_digests.py
+  What relay fingerprint would you like to validate?
+  3BB34C63072D9D10E836EE42968713F7B9325F66
+
+  Server descriptor digest is correct
+  Extrainfo descriptor digest is correct
+