Endpoints and Related Classes¶
TCPHiddenServiceEndpoint¶
-
class
txtorcon.
TCPHiddenServiceEndpoint
(reactor, config, public_port, hidden_service_dir=None, local_port=None, stealth_auth=None)¶ Bases:
object
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
- 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.
- 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).
- 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 your instance, calling listen() on it causes Tor to be launched or connected-to, your hidden service to be added, checks that the descriptor is uploaded and you get a
Deferred
with anIListeningPort
whosegetHost()
will return atxtorcon.TorOnionAddress
. The port object will also implementtxtorcon.IHiddenService
so you can get the locally-listening address and hidden serivce directory:endpoint = ... port = yield endpoint.listen(...) uri = port.getHost().onion_uri port = port.getHost().onion_port addr = IHiddenService(port).local_address hsdir = IHiddenService(port).hidden_service_dir
returns (via Deferred) an object that implements twisted.internet.interfaces.IStreamServerEndpoint
Variables: - onion_uri – the public key, like
timaq4ygg2iegci7.onion
which came from the hidden_service_dir’shostname
file - onion_private_key – the contents of
hidden_service_dir/private_key
- hiddenServiceDir – the data directory, either passed in or created
with
tempfile.mkdtemp
Parameters: - reactor – twisted.internet.interfaces.IReactorTCP provider
- config –
txtorcon.TorConfig
instance. - 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.
- stealth_auth – A list of strings, one name for each stealth authenticator
you want. Like:
['alice', 'bob']
- endpoint_generator – A callable that generates a new instance of something that implements IServerEndpoint (by default TCP4ServerEndpoint)
-
classmethod
system_tor
(reactor, control_endpoint, public_port, hidden_service_dir=None, local_port=None)¶ This returns a TCPHiddenServiceEndpoint connected to the endpoint you specify in control_endpoint. After connecting, a single hidden service is added. The endpoint can be a Unix socket if Tor’s ControlSocket option was used (instead of ControlPort).
Note
If Tor bug #11291 is not yet fixed, this won’t work if you only have Group access. XXX FIXME re-test
-
classmethod
global_tor
(reactor, public_port, hidden_service_dir=None, local_port=None, control_port=None, stealth_auth=None)¶ This returns a TCPHiddenServiceEndpoint connected to a txtorcon global Tor instance. The first time you call this, a new Tor will be launched. Subsequent calls will re-use the same connection (in fact, the very same TorControlProtocol and TorConfig instances). If the options you pass are incompatible with an already-launched Tor, RuntimeError will be thrown.
It’s probably best to not specify any option besides public_port, hidden_service_dir, and maybe local_port unless you have a specific need to.
You can also access this global txtorcon instance via
txtorcon.get_global_tor()
(which is precisely what this method uses to get it).All keyword options have defaults (e.g. random ports, or tempdirs).
Parameters: stealth_auth – None, or a list of strings – one for each stealth authenticator you require.
-
classmethod
private_tor
(reactor, public_port, hidden_service_dir=None, local_port=None, control_port=None)¶ This returns a TCPHiddenServiceEndpoint that’s always connected to its own freshly-launched Tor instance. All keyword options have defaults (e.g. random ports, or tempdirs).
-
retries
= None¶ for IProgressProvider to add_progress_listener
-
onion_uri
¶
-
onion_private_key
¶
-
add_progress_listener
(listener)¶ IProgressProvider API
-
listen
(*args, **kwargs)¶ Implement IStreamServerEndpoint.
Returns a Deferred that delivers an twisted.internet.interfaces.IListeningPort implementation.
This port can also be adapted to two other interfaces:
txtorcon.IHiddenService
so you can get the onion_uri and onion_private_key members (these correspond to “hostname” and “private_key” from the HiddenServiceDir Tor is using).txtorcon.IProgressProvider
can provide you progress updates while Tor is launched. Note that Tor is not always launched when calling this listen() method.At this point, Tor will have fully started up and successfully accepted the hidden service’s config.
FIXME TODO: also listen for an INFO-level Tor message (does exist, #tor-dev says) that indicates the hidden service’s descriptor is published.
It is “connection_dir_client_reached_eof(): Uploaded rendezvous descriptor (status 200 (“Service descriptor (v2) stored”))” at INFO level.
-
txtorcon.
get_global_tor
(*args, **kwargs)¶ See description of
txtorcon.TCPHiddenServiceEndpoint
’s class-methodglobal_tor
Parameters: - control_port – a TCP port upon which to run the launched Tor’s control-protocol (selected by the OS by default).
- 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 atxtorcon.TorConfig
which is bootstrapped.The _tor_launcher keyword arg is internal-only.
TCPHiddenServiceEndpointParser¶
-
class
txtorcon.
TCPHiddenServiceEndpointParser
¶ Bases:
object
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 withtempfile.mkdtemp()
. The IStreamServerEndpoint returned will be an instance oftxtorcon.TCPHiddenServiceEndpoint
-
prefix
= 'onion'¶
-
parseStreamServer
(reactor, public_port, localPort=None, controlPort=None, hiddenServiceDir=None)¶ twisted.internet.interfaces.IStreamServerEndpointStringParser
-
TorOnionAddress¶
-
class
txtorcon.
TorOnionAddress
(uri, port)¶ Bases:
twisted.python.util.FancyEqMixin
,object
A
TorOnionAddress
represents the public address of a Tor hidden service.Variables: In otherwords, we should be reachable at (onion_uri, onion_port) via Tor.
-
compareAttributes
= ('type', 'onion_uri', 'onion_port')¶
-
type
= 'onion'¶
-
TorOnionListeningPort¶
-
class
txtorcon.
TorOnionListeningPort
(listening_port, hs_dir, uri, port, tor_config)¶ Bases:
object
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.
-
startListening
()¶ IListeningPort API
-
stopListening
()¶ IListeningPort API
-
getHost
()¶ IListeningPort API
-
tor_config
¶
-
IProgressProvider¶
-
interface
txtorcon.
IProgressProvider
¶ FIXME move elsewhere? think harder?
-
add_progress_listener
(listener)¶ Adds a progress listener. The listener is a callable that gets called with 3 arguments corresponding to Tor’s updates: (percent, tag, message). percent is an integer from 0 to 100, tag and message are both strings. (message is the human-readable one)
-
IHiddenService¶
-
interface
txtorcon.
IHiddenService
¶ -
local_address
¶ The actual machine address we are listening on.
-
hidden_service_dir
¶ The hidden service directory, where “hostname” and “private_key” files live.
-
tor_config
¶ The TorConfig object attached to the Tor hosting this hidden service (in turn has .protocol for TorControlProtocol).
-