Changeset 839140c in trunk

Timestamp:

2023-06-12T17:41:49Z (23 months ago)

Author:

GitHub <noreply@…>

Branches:

master

Children:

07a288f, 9cf69c5, cb082b2

Parents:

d510103 (diff), 7ff20a3 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

git-author:

Itamar Turner-Trauring <itamar@…> (2023-06-12 17:41:49)

git-committer:

GitHub <noreply@…> (2023-06-12 17:41:49)

Message:

Merge pull request #1303 from tahoe-lafs/4029-http-storage-client-respects-request-to-use-tor

Http storage client respects request to use tor

Fixes ticket:4029

Files:

• .github/workflows/ci.yml (modified) (1 diff)
• integration/conftest.py (modified) (2 diffs)
• integration/test_tor.py (modified) (7 diffs)
• integration/util.py (modified) (5 diffs)
• newsfragments/4029.bugfix (added)
• nix/python-overrides.nix (modified) (1 diff)
• nix/txtorcon.nix (added)
• setup.py (modified) (1 diff)
• src/allmydata/client.py (modified) (5 diffs)
• src/allmydata/storage/http_client.py (modified) (4 diffs)
• src/allmydata/storage_client.py (modified) (11 diffs)
• src/allmydata/test/test_tor_provider.py (modified) (10 diffs)
• src/allmydata/util/tor_provider.py (modified) (10 diffs)

.github/workflows/ci.yml ¶

@@ -167 +167 @@
         include:
           - os: macos-12
-            python-version: "3.9"
+            python-version: "3.11"
             force-foolscap: false
           - os: windows-latest

integration/conftest.py ¶

@@ -280 +280 @@
 
 
-@pytest.fixture(scope='session')
+@pytest.fixture
 @log_call(
     action_type=u"integration:tor:introducer",
@@ -343 +343 @@
 
 
-@pytest.fixture(scope='session')
+@pytest.fixture
 def tor_introducer_furl(tor_introducer, temp_dir):
     furl_fname = join(temp_dir, 'introducer_tor', 'private', 'introducer.furl')

integration/test_tor.py ¶

@@ -20 +20 @@
 )
 from allmydata.client import read_config
+from allmydata.util.deferredutil import async_to_deferred
 
 # see "conftest.py" for the fixtures (e.g. "tor_network")
@@ -32 +33 @@
 @pytest_twisted.inlineCallbacks
 def test_onion_service_storage(reactor, request, temp_dir, flog_gatherer, tor_network, tor_introducer_furl):
-    carol = yield _create_anonymous_node(reactor, 'carol', 8008, request, temp_dir, flog_gatherer, tor_network, tor_introducer_furl)
-    dave = yield _create_anonymous_node(reactor, 'dave', 8009, request, temp_dir, flog_gatherer, tor_network, tor_introducer_furl)
+    """
+    Two nodes and an introducer all configured to use Tahoe.
+
+    The two nodes can talk to the introducer and each other: we upload to one
+    node, read from the other.
+    """
+    carol = yield _create_anonymous_node(reactor, 'carol', 8008, request, temp_dir, flog_gatherer, tor_network, tor_introducer_furl, 2)
+    dave = yield _create_anonymous_node(reactor, 'dave', 8009, request, temp_dir, flog_gatherer, tor_network, tor_introducer_furl, 2)
     yield util.await_client_ready(carol, minimum_number_of_servers=2, timeout=600)
     yield util.await_client_ready(dave, minimum_number_of_servers=2, timeout=600)
+    yield upload_to_one_download_from_the_other(reactor, temp_dir, carol, dave)
 
-    # ensure both nodes are connected to "a grid" by uploading
-    # something via carol, and retrieve it using dave.
+
+@async_to_deferred
+async def upload_to_one_download_from_the_other(reactor, temp_dir, upload_to: util.TahoeProcess, download_from: util.TahoeProcess):
+    """
+    Ensure both nodes are connected to "a grid" by uploading something via one
+    node, and retrieve it using the other.
+    """
+
     gold_path = join(temp_dir, "gold")
     with open(gold_path, "w") as f:
@@ -55 +69 @@
         (
             sys.executable, '-b', '-m', 'allmydata.scripts.runner',
-            '-d', join(temp_dir, 'carol'),
+            '-d', upload_to.node_dir,
             'put', gold_path,
         ),
         env=environ,
     )
-    yield proto.done
+    await proto.done
     cap = proto.output.getvalue().strip().split()[-1]
     print("capability: {}".format(cap))
@@ -70 +84 @@
         (
             sys.executable, '-b', '-m', 'allmydata.scripts.runner',
-            '-d', join(temp_dir, 'dave'),
+            '-d', download_from.node_dir,
             'get', cap,
         ),
         env=environ,
     )
-    yield proto.done
-
-    dave_got = proto.output.getvalue().strip()
-    assert dave_got == open(gold_path, 'rb').read().strip()
+    await proto.done
+    download_got = proto.output.getvalue().strip()
+    assert download_got == open(gold_path, 'rb').read().strip()
 
 
 @pytest_twisted.inlineCallbacks
-def _create_anonymous_node(reactor, name, control_port, request, temp_dir, flog_gatherer, tor_network, introducer_furl):
+def _create_anonymous_node(reactor, name, control_port, request, temp_dir, flog_gatherer, tor_network, introducer_furl, shares_total: int) -> util.TahoeProcess:
     node_dir = FilePath(temp_dir).child(name)
     web_port = "tcp:{}:interface=localhost".format(control_port + 2000)
@@ -104 +117 @@
                 '--shares-needed', '1',
                 '--shares-happy', '1',
-                '--shares-total', '2',
+                '--shares-total', str(shares_total),
                 node_dir.path,
             ),
@@ -114 +127 @@
     # Which services should this client connect to?
     write_introducer(node_dir, "default", introducer_furl)
+    util.basic_node_configuration(request, flog_gatherer, node_dir.path)
 
     config = read_config(node_dir.path, "tub.port")
-    config.set_config("node", "log_gatherer.furl", flog_gatherer)
     config.set_config("tor", "onion", "true")
     config.set_config("tor", "onion.external_port", "3457")
@@ -126 +139 @@
     print("okay, launched")
     return result
+
+@pytest.mark.skipif(sys.platform.startswith('darwin'), reason='This test has issues on macOS')
+@pytest_twisted.inlineCallbacks
+def test_anonymous_client(reactor, request, temp_dir, flog_gatherer, tor_network, introducer_furl):
+    """
+    A normal node (normie) and a normal introducer are configured, and one node
+    (anonymoose) which is configured to be anonymous by talking via Tor.
+
+    Anonymoose should be able to communicate with normie.
+
+    TODO how to ensure that anonymoose is actually using Tor?
+    """
+    normie = yield util._create_node(
+        reactor, request, temp_dir, introducer_furl, flog_gatherer, "normie",
+        web_port="tcp:9989:interface=localhost",
+        storage=True, needed=1, happy=1, total=1,
+    )
+    yield util.await_client_ready(normie)
+
+    anonymoose = yield _create_anonymous_node(reactor, 'anonymoose', 8008, request, temp_dir, flog_gatherer, tor_network, introducer_furl, 1)
+    yield util.await_client_ready(anonymoose, minimum_number_of_servers=1, timeout=600)
+
+    yield upload_to_one_download_from_the_other(reactor, temp_dir, normie, anonymoose)

integration/util.py ¶

@@ -141 +141 @@
     def outReceived(self, data):
         data = str(data, sys.stdout.encoding)
-        sys.stdout.write(self.name + data)
+        for line in data.splitlines():
+            sys.stdout.write(self.name + line + "\n")
         self._output.write(data)
         if not self.magic_seen.called and self._magic_text in self._output.getvalue():
@@ -149 +150 @@
     def errReceived(self, data):
         data = str(data, sys.stderr.encoding)
-        sys.stdout.write(self.name + data)
+        for line in data.splitlines():
+            sys.stdout.write(self.name + line + "\n")
 
 
@@ -310 +312 @@
     d.addCallback(lambda ignored: tahoe_process)
     return d
+
+
+def basic_node_configuration(request, flog_gatherer, node_dir: str):
+    """
+    Setup common configuration options for a node, given a ``pytest`` request
+    fixture.
+    """
+    config_path = join(node_dir, 'tahoe.cfg')
+    config = get_config(config_path)
+    set_config(
+        config,
+        u'node',
+        u'log_gatherer.furl',
+        flog_gatherer,
+    )
+    force_foolscap = request.config.getoption("force_foolscap")
+    assert force_foolscap in (True, False)
+    set_config(
+        config,
+        'storage',
+        'force_foolscap',
+        str(force_foolscap),
+    )
+    set_config(
+        config,
+        'client',
+        'force_foolscap',
+        str(force_foolscap),
+    )
+    write_config(FilePath(config_path), config)
 
 
@@ -352 +384 @@
 
         def created(_):
-            config_path = join(node_dir, 'tahoe.cfg')
-            config = get_config(config_path)
-            set_config(
-                config,
-                u'node',
-                u'log_gatherer.furl',
-                flog_gatherer,
-            )
-            force_foolscap = request.config.getoption("force_foolscap")
-            assert force_foolscap in (True, False)
-            set_config(
-                config,
-                'storage',
-                'force_foolscap',
-                str(force_foolscap),
-            )
-            set_config(
-                config,
-                'client',
-                'force_foolscap',
-                str(force_foolscap),
-            )
-            write_config(FilePath(config_path), config)
+            basic_node_configuration(request, flog_gatherer, node_dir)
         created_d.addCallback(created)
 
@@ -622 +632 @@
             for server in servers
         ]
-        # if any times are null/None that server has never been
-        # contacted (so it's down still, probably)
-        never_received_data = server_times.count(None)
-        if never_received_data > 0:
-            print(f"waiting because {never_received_data} server(s) not contacted")
-            time.sleep(1)
-            continue
-
-        # check that all times are 'recent enough'
-        if any([time.time() - t > liveness for t in server_times]):
+        # check that all times are 'recent enough' (it's OK if _some_ servers
+        # are down, we just want to make sure a sufficient number are up)
+        if len([time.time() - t <= liveness for t in server_times if t is not None]) < minimum_number_of_servers:
             print("waiting because at least one server too old")
             time.sleep(1)

nix/python-overrides.nix ¶

@@ -22 +22 @@
   txi2p = self.callPackage ./txi2p.nix { };
 
-  # Update the version of klein.
+  # Some packages are of somewhat too-old versions - update them.
   klein = self.callPackage ./klein.nix {
     # Avoid infinite recursion.
     inherit (super) klein;
+  };
+  txtorcon = self.callPackage ./txtorcon.nix {
+    inherit (super) txtorcon;
   };
 

setup.py ¶

@@ -165 +165 @@
 
 tor_requires = [
-    # This is exactly what `foolscap[tor]` means but pip resolves the pair of
-    # dependencies "foolscap[i2p] foolscap[tor]" to "foolscap[i2p]" so we lose
-    # this if we don't declare it ourselves!
-    "txtorcon >= 0.17.0",
+    # 23.5 added support for custom TLS contexts in web_agent(), which is
+    # needed for the HTTP storage client to run over Tor.
+    "txtorcon >= 23.5.0",
 ]
 

src/allmydata/client.py ¶

@@ -11 +11 @@
 from base64 import urlsafe_b64encode
 from functools import partial
-# On Python 2 this will be the backported package:
 from configparser import NoSectionError
 
@@ -48 +47 @@
 from allmydata.util.time_format import parse_duration, parse_date
 from allmydata.util.i2p_provider import create as create_i2p_provider
-from allmydata.util.tor_provider import create as create_tor_provider
+from allmydata.util.tor_provider import create as create_tor_provider, _Provider as TorProvider
 from allmydata.stats import StatsProvider
 from allmydata.history import History
@@ -269 +268 @@
     storage_broker = create_storage_farm_broker(
         config, default_connection_handlers, foolscap_connection_handlers,
-        tub_options, introducer_clients
+        tub_options, introducer_clients, tor_provider
     )
 
@@ -465 +464 @@
 
 
-def create_storage_farm_broker(config: _Config, default_connection_handlers, foolscap_connection_handlers, tub_options, introducer_clients):
+def create_storage_farm_broker(config: _Config, default_connection_handlers, foolscap_connection_handlers, tub_options, introducer_clients, tor_provider: Optional[TorProvider]):
     """
     Create a StorageFarmBroker object, for use by Uploader/Downloader
@@ -501 +500 @@
         node_config=config,
         storage_client_config=storage_client_config,
+        default_connection_handlers=default_connection_handlers,
+        tor_provider=tor_provider,
     )
     for ic in introducer_clients:

src/allmydata/storage/http_client.py ¶

@@ -16 +16 @@
     Set,
     Dict,
+    Callable,
 )
 from base64 import b64encode
@@ -32 +33 @@
 from twisted.web.http_headers import Headers
 from twisted.web import http
-from twisted.web.iweb import IPolicyForHTTPS, IResponse
+from twisted.web.iweb import IPolicyForHTTPS, IResponse, IAgent
 from twisted.internet.defer import inlineCallbacks, Deferred, succeed
 from twisted.internet.interfaces import (
@@ -338 +339 @@
     @classmethod
     def from_nurl(
-        cls, nurl: DecodedURL, reactor, pool: Optional[HTTPConnectionPool] = None
+        cls,
+        nurl: DecodedURL,
+        reactor,
+        # TODO default_connection_handlers should really be a class, not a dict
+        # of strings...
+        default_connection_handlers: dict[str, str],
+        pool: Optional[HTTPConnectionPool] = None,
+        agent_factory: Optional[
+            Callable[[object, IPolicyForHTTPS, HTTPConnectionPool], IAgent]
+        ] = None,
     ) -> StorageClient:
         """
         Create a ``StorageClient`` for the given NURL.
         """
+        # Safety check: if we're using normal TCP connections, we better not be
+        # configured for Tor or I2P.
+        if agent_factory is None:
+            assert default_connection_handlers["tcp"] == "tcp"
+
         assert nurl.fragment == "v=1"
         assert nurl.scheme == "pb"
@@ -354 +369 @@
             cls.TEST_MODE_REGISTER_HTTP_POOL(pool)
 
+        def default_agent_factory(
+            reactor: object,
+            tls_context_factory: IPolicyForHTTPS,
+            pool: HTTPConnectionPool,
+        ) -> IAgent:
+            return Agent(reactor, tls_context_factory, pool=pool)
+
+        if agent_factory is None:
+            agent_factory = default_agent_factory
+
         treq_client = HTTPClient(
-            Agent(
+            agent_factory(
                 reactor,
                 _StorageClientHTTPSPolicy(expected_spki_hash=certificate_hash),
-                pool=pool,
+                pool,
             )
         )

src/allmydata/storage_client.py ¶

@@ -52 +52 @@
 from twisted.python.failure import Failure
 from twisted.web import http
+from twisted.web.iweb import IAgent, IPolicyForHTTPS
 from twisted.internet.task import LoopingCall
 from twisted.internet import defer, reactor
@@ -78 +79 @@
     ed25519,
 )
+from allmydata.util.tor_provider import _Provider as TorProvider
 from allmydata.util import log, base32, connection_status
 from allmydata.util.assertutil import precondition
@@ -203 +205 @@
             node_config: _Config,
             storage_client_config=None,
+            default_connection_handlers=None,
+            tor_provider: Optional[TorProvider]=None,
     ):
         service.MultiService.__init__(self)
+        if default_connection_handlers is None:
+            default_connection_handlers = {"tcp": "tcp"}
+
         assert permute_peers # False not implemented yet
         self.permute_peers = permute_peers
@@ -224 +231 @@
         self._threshold_listeners : list[tuple[float,defer.Deferred[Any]]]= [] # tuples of (threshold, Deferred)
         self._connected_high_water_mark = 0
+        self._tor_provider = tor_provider
+        self._default_connection_handlers = default_connection_handlers
 
     @log_call(action_type=u"storage-client:broker:set-static-servers")
@@ -316 +325 @@
                 server["ann"],
                 grid_manager_verifier=gm_verifier,
+                default_connection_handlers=self._default_connection_handlers,
+                tor_provider=self._tor_provider
             )
             s.on_status_changed(lambda _: self._got_connection())
@@ -1050 +1061 @@
     """
 
-    def __init__(self, server_id: bytes, announcement, reactor=reactor, grid_manager_verifier=None):
+    def __init__(self, server_id: bytes, announcement, default_connection_handlers: dict[str,str], reactor=reactor, grid_manager_verifier=None, tor_provider: Optional[TorProvider]=None):
         service.MultiService.__init__(self)
         assert isinstance(server_id, bytes)
@@ -1058 +1069 @@
         self._reactor = reactor
         self._grid_manager_verifier = grid_manager_verifier
+        self._tor_provider = tor_provider
+        self._default_connection_handlers = default_connection_handlers
+
         furl = announcement["anonymous-storage-FURL"].encode("utf-8")
         (
@@ -1219 +1233 @@
         return connecting
 
+    async def _agent_factory(self) -> Optional[Callable[[object, IPolicyForHTTPS, HTTPConnectionPool],IAgent]]:
+        """Return a factory for ``twisted.web.iweb.IAgent``."""
+        # TODO default_connection_handlers should really be an object, not a
+        # dict, so we can ask "is this using Tor" without poking at a
+        # dictionary with arbitrary strings... See
+        # https://tahoe-lafs.org/trac/tahoe-lafs/ticket/4032
+        handler = self._default_connection_handlers["tcp"]
+        if handler == "tcp":
+            return None
+        if handler == "tor":
+            assert self._tor_provider is not None
+            tor_instance = await self._tor_provider.get_tor_instance(self._reactor)
+
+            def agent_factory(reactor: object, tls_context_factory: IPolicyForHTTPS, pool: HTTPConnectionPool) -> IAgent:
+                assert reactor == self._reactor
+                return tor_instance.web_agent(pool=pool, tls_context_factory=tls_context_factory)
+            return agent_factory
+        else:
+            raise RuntimeError(f"Unsupported tcp connection handler: {handler}")
+
     @async_to_deferred
     async def _pick_server_and_get_version(self):
@@ -1236 +1270 @@
             # version() calls before we are live talking to a server, it could only
             # be one. See https://tahoe-lafs.org/trac/tahoe-lafs/ticket/3992
+
+            agent_factory = await self._agent_factory()
 
             def request(reactor, nurl: DecodedURL):
@@ -1243 +1279 @@
                 pool.retryAutomatically = False
                 return StorageClientGeneral(
-                    StorageClient.from_nurl(nurl, reactor, pool)
+                    StorageClient.from_nurl(
+                        nurl, reactor, self._default_connection_handlers,
+                        pool=pool, agent_factory=agent_factory)
                 ).get_version()
 
@@ -1250 +1288 @@
             # If we've gotten this far, we've found a working NURL.
             self._istorage_server = _HTTPStorageServer.from_http_client(
-                StorageClient.from_nurl(nurl, reactor)
+                StorageClient.from_nurl(
+                    nurl, reactor, self._default_connection_handlers,
+                    agent_factory=agent_factory
+                )
             )
             return self._istorage_server

src/allmydata/test/test_tor_provider.py ¶

@@ -2 +2 @@
 Ported to Python 3.
 """
-from __future__ import absolute_import
-from __future__ import division
-from __future__ import print_function
-from __future__ import unicode_literals
-
-from future.utils import PY2
-if PY2:
-    from future.builtins import filter, map, zip, ascii, chr, hex, input, next, oct, open, pow, round, super, bytes, dict, list, object, range, str, max, min  # noqa: F401
 
 import os
@@ -95 +87 @@
         private_dir = "private"
         txtorcon = mock.Mock()
-        tpp = mock.Mock
-        tpp.tor_protocol = mock.Mock()
-        txtorcon.launch_tor = mock.Mock(return_value=tpp)
+        tor = mock.Mock
+        txtorcon.launch = mock.Mock(return_value=tor)
 
         with mock.patch("allmydata.util.tor_provider.allocate_tcp_port",
@@ -103 +94 @@
             d = tor_provider._launch_tor(reactor, tor_executable, private_dir,
                                          txtorcon)
-        tor_control_endpoint, tor_control_proto = self.successResultOf(d)
-        self.assertIs(tor_control_proto, tpp.tor_protocol)
+        tor_control_endpoint, tor_result = self.successResultOf(d)
+        self.assertIs(tor_result, tor)
 
     def test_launch(self):
@@ -162 +153 @@
 
 
+class FakeTor:
+    """Pretends to be a ``txtorcon.Tor`` instance."""
+    def __init__(self):
+        self.protocol = object()
+
+
 class CreateOnion(unittest.TestCase):
     def test_no_txtorcon(self):
@@ -172 +169 @@
                              "Cannot create onion without txtorcon. "
                              "Please 'pip install tahoe-lafs[tor]' to fix this.")
+
     def _do_test_launch(self, executable):
         basedir = self.mktemp()
@@ -182 +180 @@
             args.append("--tor-executable=%s" % executable)
         cli_config = make_cli_config(basedir, *args)
-        protocol = object()
+        tor_instance = FakeTor()
         launch_tor = mock.Mock(return_value=defer.succeed(("control_endpoint",
-                                                           protocol)))
+                                                           tor_instance)))
         txtorcon = mock.Mock()
         ehs = mock.Mock()
@@ -205 +203 @@
                                       os.path.abspath(private_dir), txtorcon)
         txtorcon.EphemeralHiddenService.assert_called_with("3457 127.0.0.1:999999")
-        ehs.add_to_tor.assert_called_with(protocol)
-        ehs.remove_from_tor.assert_called_with(protocol)
+        ehs.add_to_tor.assert_called_with(tor_instance.protocol)
+        ehs.remove_from_tor.assert_called_with(tor_instance.protocol)
 
         expected = {"launch": "true",
@@ -588 +586 @@
         with mock_txtorcon(txtorcon):
             p = tor_provider.create(reactor, cfg)
+        tor_instance = FakeTor()
         tor_state = mock.Mock()
-        tor_state.protocol = object()
+        tor_state.protocol = tor_instance.protocol
         ehs = mock.Mock()
         ehs.add_to_tor = mock.Mock(return_value=defer.succeed(None))
         ehs.remove_from_tor = mock.Mock(return_value=defer.succeed(None))
         txtorcon.EphemeralHiddenService = mock.Mock(return_value=ehs)
-        launch_tor = mock.Mock(return_value=defer.succeed((None,tor_state.protocol)))
+        launch_tor = mock.Mock(return_value=defer.succeed((None,tor_instance)))
         with mock.patch("allmydata.util.tor_provider._launch_tor",
                         launch_tor):
@@ -629 +628 @@
         with mock_txtorcon(txtorcon):
             p = tor_provider.create(reactor, cfg)
-        tor_state = mock.Mock()
-        tor_state.protocol = object()
-        txtorcon.build_tor_connection = mock.Mock(return_value=tor_state)
+        tor_instance = FakeTor()
+        txtorcon.connect = mock.Mock(return_value=tor_instance)
         ehs = mock.Mock()
         ehs.add_to_tor = mock.Mock(return_value=defer.succeed(None))
@@ -643 +641 @@
         self.successResultOf(d)
         self.assertIs(p._onion_ehs, ehs)
-        self.assertIs(p._onion_tor_control_proto, tor_state.protocol)
+        self.assertIs(p._onion_tor_control_proto, tor_instance.protocol)
         cfs.assert_called_with(reactor, "ep_desc")
-        txtorcon.build_tor_connection.assert_called_with(tcep)
+        txtorcon.connect.assert_called_with(reactor, tcep)
         txtorcon.EphemeralHiddenService.assert_called_with("456 127.0.0.1:123",
                                                            b"private key")
-        ehs.add_to_tor.assert_called_with(tor_state.protocol)
+        ehs.add_to_tor.assert_called_with(tor_instance.protocol)
 
         yield p.stopService()
-        ehs.remove_from_tor.assert_called_with(tor_state.protocol)
+        ehs.remove_from_tor.assert_called_with(tor_instance.protocol)

src/allmydata/util/tor_provider.py ¶

@@ -3 +3 @@
 Ported to Python 3.
 """
-from __future__ import absolute_import, print_function, with_statement
-from __future__ import division
-from __future__ import unicode_literals
-
-from future.utils import PY2
-if PY2:
-    from future.builtins import filter, map, zip, ascii, chr, hex, input, next, oct, open, pow, round, super, bytes, dict, list, object, range, str, max, min  # noqa: F401
-
+
+from __future__ import annotations
+
+from typing import Optional
 import os
 
@@ -27 +23 @@
     IAddressFamily,
 )
+
 
 def _import_tor():
@@ -42 +39 @@
         return None
 
-def create(reactor, config, import_tor=None, import_txtorcon=None):
+def create(reactor, config, import_tor=None, import_txtorcon=None) -> Optional[_Provider]:
     """
     Create a new _Provider service (this is an IService so must be
@@ -99 +96 @@
 @inlineCallbacks
 def _launch_tor(reactor, tor_executable, private_dir, txtorcon):
+    """
+    Launches Tor, returns a corresponding ``(control endpoint string,
+    txtorcon.Tor instance)`` tuple.
+    """
     # TODO: handle default tor-executable
     # TODO: it might be a good idea to find exactly which Tor we used,
@@ -105 +106 @@
     # different Tor being present at node startup. OTOH, maybe we don't
     # need to worry about it.
-    tor_config = txtorcon.TorConfig()
-    tor_config.DataDirectory = data_directory(private_dir)
 
     # unix-domain control socket
-    tor_config.ControlPort = "unix:" + os.path.join(private_dir, "tor.control")
-    tor_control_endpoint_desc = tor_config.ControlPort
-
-    tor_config.SOCKSPort = allocate_tcp_port()
-
-    tpp = yield txtorcon.launch_tor(
-        tor_config, reactor,
+    tor_control_endpoint_desc = "unix:" + os.path.join(private_dir, "tor.control")
+
+    tor = yield txtorcon.launch(
+        reactor,
+        control_port=tor_control_endpoint_desc,
+        data_directory=data_directory(private_dir),
         tor_binary=tor_executable,
+        socks_port=allocate_tcp_port(),
         # can be useful when debugging; mirror Tor's output to ours
         # stdout=sys.stdout,
@@ -122 +121 @@
     )
 
-    # now tor is launched and ready to be spoken to
-    # as a side effect, we've got an ITorControlProtocol ready to go
-    tor_control_proto = tpp.tor_protocol
-
     # How/when to shut down the new process? for normal usage, the child
     # tor will exit when it notices its parent (us) quit. Unit tests will
@@ -135 +130 @@
     # that fires when Tor has actually exited.
 
-    returnValue((tor_control_endpoint_desc, tor_control_proto))
+    returnValue((tor_control_endpoint_desc, tor))
+
 
 @inlineCallbacks
@@ -170 +166 @@
             tahoe_config_tor["tor.executable"] = tor_executable
         print("launching Tor (to allocate .onion address)..", file=stdout)
-        (_, tor_control_proto) = yield _launch_tor(
+        (_, tor) = yield _launch_tor(
             reactor, tor_executable, private_dir, txtorcon)
+        tor_control_proto = tor.protocol
         print("Tor launched", file=stdout)
     else:
@@ -295 +292 @@
 
     def _get_launched_tor(self, reactor):
-        # this fires with a tuple of (control_endpoint, tor_protocol)
+        # this fires with a tuple of (control_endpoint, txtorcon.Tor instance)
         if not self._tor_launched:
             self._tor_launched = OneShotObserverList()
@@ -326 +323 @@
             require("private_key_file")
 
-    @inlineCallbacks
-    def _start_onion(self, reactor):
+    def get_tor_instance(self, reactor: object):
+        """Return a ``Deferred`` that fires with a ``txtorcon.Tor`` instance."""
         # launch tor, if necessary
         if self._get_tor_config("launch", False, boolean=True):
-            (_, tor_control_proto) = yield self._get_launched_tor(reactor)
+            return self._get_launched_tor(reactor).addCallback(lambda t: t[1])
         else:
             controlport = self._get_tor_config("control.port", None)
             tcep = clientFromString(reactor, controlport)
-            tor_state = yield self._txtorcon.build_tor_connection(tcep)
-            tor_control_proto = tor_state.protocol
-
+            return self._txtorcon.connect(reactor, tcep)
+
+    @inlineCallbacks
+    def _start_onion(self, reactor):
+        tor_instance = yield self.get_tor_instance(reactor)
+        tor_control_proto = tor_instance.protocol
         local_port = int(self._get_tor_config("onion.local_port"))
         external_port = int(self._get_tor_config("onion.external_port"))