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
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 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
fromlisten()
will fire with anIListeningPort
whosegetHost()
will return atxtorcon.TorOnionAddress
. The port object also has a .onion_service property which resolves to thetxtorcon.IOnionService
ortxtorcon.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’shostname
fileonion_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 onepublic_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-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.
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 withtempfile.mkdtemp()
. The IStreamServerEndpoint returned will be an instance oftxtorcon.TCPHiddenServiceEndpoint
If
privateKey
orprivateKeyFile
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 thetxtorcon.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?