# Endpoints and Related Classes

## TCPHiddenServiceEndpoint

class txtorcon.TCPHiddenServiceEndpoint(reactor, config, public_port, hidden_service_dir=None, local_port=None, auth=None, stealth_auth=None, ephemeral=None, private_key=None, group_readable=False, version=None, single_hop=None)

  This represents something listening on an arbitrary local port that has a Tor configured with a Hidden Service pointing at it. TCP4ServerEndpoint is used under the hood to do the local listening.

  There are three main ways to use this class, and you are encouraged to use the @classmethod ways of creating instances: system_tor, global_tor, and private_tor

  1. system_tor(…) connects to an already-started tor on the endpoint you specify; stricly speaking not a “system” tor since you could have spawned it some other way. See Tor bug 11291 however.

  2. global_tor(…) refers to a single possible Tor instance per python process. So the first call to this launches a new Tor, and subsequent calls re-use the existing Tor (that is, add more hidden services to it).

  3. private_tor(…) launches a new Tor instance no matter what, so it will have just the one hidden serivce on it.

  If you need to set configuration options that are not reflected in any of the method signatures above, you’ll have to construct an instance of this class yourself (i.e. with a TorConfig instance you’ve created).

  No matter how you came by this endpoint instance, you should call listen() on it to trigger any work required to create the service: Tor will be launched or connected-to; config for the onion service will be added; the uploading of descriptors is awaited.

  The `Deferred` from `listen()` will fire with an `IListeningPort` whose `getHost()` will return a `txtorcon.TorOnionAddress`. The port object also has a .onion_service property which resolves to the `txtorcon.IOnionService` or `txtorcon.IAuthenticatedOnionClients` instance (and from which you can recover private keys, the hostname, etc)

  Variables:

    - onion_uri – the public key, like `fjblvrw2jrxnhtg67qpbzi45r7ofojaoo3orzykesly2j3c2m3htapid.onion` which came from the hidden_service_dir’s `hostname` file

    - onion_private_key – the contents of `hidden_service_dir/private_key`

    - hidden_service_dir – the data directory, either passed in or created with `tempfile.mkdtemp`

  NOTE that if you do not specify a version= then you will get a version 2 service (new onion APIs return version=3 services by default). This is for backwards-compatiblity reasons, as version= didn’t exist before 18.0.0

  Parameters:

    - reactor – twisted.internet.interfaces.IReactorTCP provider

    - config – `txtorcon.TorConfig` instance or a Deferred yielding one

    - public_port – The port number we will advertise in the hidden serivces directory.

    - local_port – The port number we will perform our local tcp listen on and receive incoming connections from the tor process.

    - hidden_service_dir – If not None, point to a HiddenServiceDir directory (i.e. with “hostname” and “private_key” files in it). If not provided, one is created with temp.mkdtemp() AND DELETED when the reactor shuts down.

    - auth – An AuthBasic or AuthStealth instance (or None)

    - stealth_auth – Deprecated; use ``auth=``. This is for backwards-comapatibility only.

    - endpoint_generator – A callable that generates a new instance of something that implements IServerEndpoint (by default TCP4ServerEndpoint)

    - group_readable – Only for filesystem services. Causes the directory to be group-readable when Tor creates it.

    - version – Either None, 2 or 3 to specify a version 2 service or Proposition 224 (version 3) service.

    - single_hop – if True, pass the NonAnonymous flag. Note that Tor options HiddenServiceSingleHopMode, HiddenServiceNonAnonymousMode must be set to 1 and there must be no SOCKSPort configured for this to actually work.

txtorcon.get_global_tor(reactor, control_port=None, progress_updates=None, _tor_launcher=None)

  See description of `txtorcon.TCPHiddenServiceEndpoint`’s class-method `global_tor`

  Parameters:

    control_port

  a TCP port upon which to run the launched Tor’s control-protocol (selected by the OS by default).

  Parameters:

    progress_updates

  A callable that takes 3 args: `percent, tag, message` which is called when Tor announcing some progress setting itself up.

  Returns:

  a `Deferred` that fires a `txtorcon.TorConfig` which is bootstrapped.

  The _tor_launcher keyword arg is internal-only.

  Deprecated in txtorcon 18.0.0.

## TCPHiddenServiceEndpointParser

class txtorcon.TCPHiddenServiceEndpointParser

  This provides a twisted IPlugin and IStreamServerEndpointsStringParser so you can call serverFromString with a string argument like:

  `onion:80:localPort=9876:controlPort=9052:hiddenServiceDir=/dev/shm/foo`

  …or simply:

  `onion:80`

  If `controlPort` is specified, it means connect to an already-running Tor on that port and add a hidden-serivce to it.

  `localPort` is optional and if not specified, a port is selected by the OS.

  If `hiddenServiceDir` is not specified, one is created with `tempfile.mkdtemp()`. The IStreamServerEndpoint returned will be an instance of `txtorcon.TCPHiddenServiceEndpoint`

  If `privateKey` or `privateKeyFile` is specified, the service will be “ephemeral” and Tor will receive the private key via the ADD_ONION control-port command.

## TorOnionAddress

class txtorcon.TorOnionAddress(port, hs)

  A `TorOnionAddress` represents the public address of a Tor onion service. Instances of these come from calling the Twisted method .getHost() on twisted.internet.interfaces.IListeningPort which was returned from the `txtorcon.TCPHiddenServiceEndpoint.listen`

  Variables:

    - type – A string describing the type of transport, ‘onion’.

    - onion_port – The public port we’re advertising

    - onion_key – the private key for the service

## TorOnionListeningPort

class txtorcon.TorOnionListeningPort(listening_port, public_port, hiddenservice, tor_config)

  Our TCPHiddenServiceEndpoint’s listen method will return a deferred which fires an instance of this object. The getHost method will return a TorOnionAddress instance… which can be used to determine the onion address of a newly created Tor Hidden Service.

  startListening and stopListening methods proxy to the “TCP ListeningPort” object… which implements IListeningPort interface but has many more responsibilities we needn’t worry about here.

## IProgressProvider

interface txtorcon.IProgressProvider

  FIXME move elsewhere? think harder?