[stem/master] Rename new authentication methods - tor-commits

7 Aug 2020

commit e302e46be576afac28bb84f5c6865047cd7fdf68
Author: Damian Johnson atagar@torproject.org
Date:   Tue Aug 4 19:00:37 2020 -0700
Rename new authentication methods
These method names were based on the controller commands which is fine, but we
    have some conventions of our own. Renaming these methods for a couple
    reasons...
* For consitency Stem still calls these 'hidden services', and will continue
        to do so until...
https://trac.torproject.org/projects/tor/ticket/25918
* We prefix getter methods like this with 'list_'.
---
 stem/control.py                  | 26 ++++++++++++--------------
 test/integ/control/controller.py | 21 +++++++++++----------
 2 files changed, 23 insertions(+), 24 deletions(-)

diff --git a/stem/control.py b/stem/control.py
index 5bdb4a5a..61c4a277 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -112,9 +112,9 @@ If you're fine with allowing your script to raise exceptions then this can be mo
     |- create_ephemeral_hidden_service - create a new ephemeral hidden service
     |- remove_ephemeral_hidden_service - removes an ephemeral hidden service
     |
-    |- add_onion_client_auth - add Client Authentication for a v3 onion service
-    |- remove_onion_client_auth - remove Client Authentication for a v3 onion service
-    |- view_onion_client_auth - view Client Authentication for a v3 onion service
+    |- add_hidden_service_auth - authenticate to a v3 hidden service
+    |- remove_hidden_service_auth - revoke authentication to a v3 hidden service
+    |- list_hidden_service_auth - list v3 hidden services we authenticate with
     |
     |- add_event_listener - attaches an event listener to be notified of tor events
     |- remove_event_listener - removes a listener so it isn't notified of further events
@@ -2905,12 +2905,6 @@ class Controller(BaseController):
     response. For instance, only bob can access using the given newly generated
     credentials...
-    Note that **basic_auth** only works for legacy (v2) onion services.
-    There is not yet any Control Port support for adding Client Auth to the
-    server side of a v3 onion service.
-
-    To add Client Authentication on the client side of a v3 onion, you can use
-    :func`~stem.control.Controller.add_onion_client_auth`.
     ::
>>> response = controller.create_ephemeral_hidden_service(80, basic_auth = {'bob': None})
@@ -2927,6 +2921,10 @@ class Controller(BaseController):
         'bob': 'vGnNRpWYiMBFTWD2gbBlcA',
       })
+    Please note that **basic_auth** only works for legacy (v2) hidden services.
+    Version 3 can't enable service authentication through the control protocol
+    (`ticket https://gitlab.torproject.org/tpo/core/tor/-/issues/40084`_).
+
     To create a **version 3** service simply specify **ED25519-V3** as the
     our key type, and to create a **version 2** service use **RSA1024**. The
     default version of newly created hidden services is based on the
@@ -3085,9 +3083,9 @@ class Controller(BaseController):
     else:
       raise stem.ProtocolError('DEL_ONION returned unexpected response code: %s' % response.code)
-  async def add_onion_client_auth(self, service_id: str, private_key_blob: str, key_type: str = 'x25519', client_name: Optional[str] = None, permanent: Optional[bool] = False) -> stem.response.onion_client_auth.OnionClientAuthAddResponse:
+  async def add_hidden_service_auth(self, service_id: str, private_key_blob: str, key_type: str = 'x25519', client_name: Optional[str] = None, permanent: Optional[bool] = False) -> stem.response.onion_client_auth.OnionClientAuthAddResponse:
     """
-    Adds Client Authentication for a v3 onion service.
+    Authenticate with a v3 hidden service.
:param service_id: hidden service address without the '.onion' suffix
     :param key_type: the type of private key in use. x25519 is the only one supported right now
@@ -3119,9 +3117,9 @@ class Controller(BaseController):
return response
-  async def remove_onion_client_auth(self, service_id: str) -> stem.response.onion_client_auth.OnionClientAuthRemoveResponse:
+  async def remove_hidden_service_auth(self, service_id: str) -> stem.response.onion_client_auth.OnionClientAuthRemoveResponse:
     """
-    Removes Client Authentication for a v3 onion service.
+    Revoke authentication with a v3 hidden service.
:param service_id: hidden service address without the '.onion' suffix
@@ -3137,7 +3135,7 @@ class Controller(BaseController):
return response
-  async def view_onion_client_auth(self, service_id: str) -> stem.response.onion_client_auth.OnionClientAuthViewResponse:
+  async def list_hidden_service_auth(self, service_id: str) -> stem.response.onion_client_auth.OnionClientAuthViewResponse:
     """
     View Client Authentication for a v3 onion service.
diff --git a/test/integ/control/controller.py b/test/integ/control/controller.py
index 47c51caf..2f8f2da0 100644
--- a/test/integ/control/controller.py
+++ b/test/integ/control/controller.py
@@ -1604,9 +1604,10 @@ class TestController(unittest.TestCase):
@test.require.controller
   @async_test
-  async def test_client_auth_for_v3_onion(self):
+  async def test_hidden_service_v3_authentication(self):
     """
-    Exercises adding, viewing and removing Client Auth for a v3 ephemeral hidden service.
+    Exercises adding, viewing and removing authentication credentials for a v3
+    service.
     """
runner = test.runner.get_runner()
@@ -1618,19 +1619,19 @@ class TestController(unittest.TestCase):
       exc_msg = "ONION_CLIENT_AUTH_ADD response didn't have an OK status: Failed to decode x25519 private key"
with self.assertRaisesWith(stem.ProtocolError, exc_msg):
-        await controller.add_onion_client_auth(service_id, private_key)
+        await controller.add_hidden_service_auth(service_id, private_key)
# This is a valid key
       private_key = 'FCV0c0ELDKKDpSFgVIB8Yow8Evj5iD+GoiTtK878NkQ='
-      response = await controller.add_onion_client_auth(service_id, private_key)
+      response = await controller.add_hidden_service_auth(service_id, private_key)
# View the credential
-      response = await controller.view_onion_client_auth(service_id)
+      response = await controller.list_hidden_service_auth(service_id)
       self.assertEqual(response.client_auth_credential, '%s x25519:%s' % (service_id, private_key))
# Remove the credential
-      await controller.remove_onion_client_auth(service_id)
-      response = await controller.view_onion_client_auth(service_id)
+      await controller.remove_hidden_service_auth(service_id)
+      response = await controller.list_hidden_service_auth(service_id)
       self.assertTrue(response.client_auth_credential is None)
# Test that an invalid service ID throws the appropriate error for adding, removing or viewing client auth
@@ -1638,17 +1639,17 @@ class TestController(unittest.TestCase):
       exc_msg = "ONION_CLIENT_AUTH_ADD response didn't have an OK status: Invalid v3 address "%s"" % service_id
with self.assertRaisesWith(stem.ProtocolError, exc_msg):
-        await controller.add_onion_client_auth(service_id, private_key)
+        await controller.add_hidden_service_auth(service_id, private_key)
exc_msg = "ONION_CLIENT_AUTH_REMOVE response didn't have an OK status: Invalid v3 address "%s"" % service_id
with self.assertRaisesWith(stem.ProtocolError, exc_msg):
-        await controller.remove_onion_client_auth(service_id)
+        await controller.remove_hidden_service_auth(service_id)
exc_msg = "ONION_CLIENT_AUTH_VIEW response didn't have an OK status: Invalid v3 address "%s"" % service_id
with self.assertRaisesWith(stem.ProtocolError, exc_msg):
-        await controller.view_onion_client_auth(service_id)
+        await controller.list_hidden_service_auth(service_id)
async def _get_router_status_entry(self, controller):
     """

    