[tor-commits] [stem/master] Add an example of using basic hidden service auth

[atagar at torproject.org]

commit 3f9057b45152ab0de1600c16c4cd11bb5639c14e
Author: Damian Johnson <atagar at torproject.org>
Date:   Wed Nov 29 12:15:30 2017 -0800

    Add an example of using basic hidden service auth
    
    Snippet courtesy of ZeroMux.
---
 docs/tutorials/over_the_river.rst | 24 ++++++++++++++++++++++++
 stem/socket.py                    |  8 ++++----
 stem/util/system.py               |  2 ++
 3 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/docs/tutorials/over_the_river.rst b/docs/tutorials/over_the_river.rst
index 3f8ae0c2..dac78827 100644
--- a/docs/tutorials/over_the_river.rst
+++ b/docs/tutorials/over_the_river.rst
@@ -70,6 +70,30 @@ Now if we run this...
 
 .. image:: /_static/hidden_service.png
 
+.. _hidden-service-authentication:
+
+Hidden service authentication
+-----------------------------
+
+Hidden services you create can restrict their access, requiring in essence a
+password...
+
+::
+
+  >>> from stem.control import Controller
+  >>> controller = Controller.from_port()
+  >>> controller.authenticate()
+  >>> response = controller.create_ephemeral_hidden_service({80: 8080}, await_publication=True, basic_auth={'bob': None, 'alice': None})
+  >>> response.service_id, response.client_auth
+  ('l3lnorirzn7hrjnw', {'alice': 'I6AMKiay+UkM5MfrvdnF2A', 'bob': 'VLsbrSGyrb5JYEvZmQ3tMg'})
+
+To access this service users simply provide this credential to tor via their
+torrc or SETCONF prior to visiting it...
+
+::
+
+  >>> controller.set_conf('HidServAuth', 'l3lnorirzn7hrjnw.onion I6AMKiay+UkM5MfrvdnF2A')
+
 .. _ephemeral-hidden-services:
 
 Ephemeral hidden services
diff --git a/stem/socket.py b/stem/socket.py
index ef2d77c7..b05524b5 100644
--- a/stem/socket.py
+++ b/stem/socket.py
@@ -167,11 +167,11 @@ class ControlSocket(object):
         # everything down. However, there's a couple cases where this will
         # cause deadlock...
         #
-        # * this socketClosed was *caused by* a close() call, which is joining
-        #   on our thread
+        # * This SocketClosed was *caused by* a close() call, which is joining
+        #   on our thread.
         #
-        # * a send() call that's currently in flight is about to call close(),
-        #   also attempting to join on us
+        # * A send() call that's currently in flight is about to call close(),
+        #   also attempting to join on us.
         #
         # To resolve this we make a non-blocking call to acquire the send lock.
         # If we get it then great, we can close safely. If not then one of the
diff --git a/stem/util/system.py b/stem/util/system.py
index 8de186b1..cec095ea 100644
--- a/stem/util/system.py
+++ b/stem/util/system.py
@@ -1266,6 +1266,8 @@ def call(command, default = UNDEFINED, ignore_exit_status = False, timeout = Non
     * **CallTimeoutError** if the timeout is reached without a default
   """
 
+  # TODO: in stem 2.x return a struct with stdout, stderr, and runtime instead
+
   global SYSTEM_CALL_TIME
 
   if isinstance(command, str):