Onion APIs

See the Programming Guide for “prose” documentation of these (and other) APIs.

For non-authenticated services:

IOnionService

interface txtorcon.IOnionService

Encapsulates a single, ephemeral onion service.

If this instance happens to be a filesystem-based service (instead of ephemeral), it shall implement IFilesystemOnionService as well (which is a subclass of this).

If this object happens to represent an authenticated service, it shall implement IAuthenticatedOnionClients ONLY (not this interface too; IAuthenticatedOnionClients returns lists of IOnionClient instances which are a subclass of IOnionService; see txtorcon.IAuthenticatedOnionClients).

For non-authenticated services, there will be one of these per directory (i.e. HiddenServiceDir) if using non-ephemeral services, or one per ADD_ONION for ephemeral hidden services.

For authenticated services, there is an instance implementing this interface for each “client” of the authenticated service. In the “basic” case, the .onion URI happens to be the same for each one (with a different authethentication token) whereas for a “stealth” sevice the .onion URI is different.

hostname

hostname, including .onion

private_key

Private key blob (bytes)

ports

list of str; the ports lines like ‘public_port host:local_port’

IFilesystemOnionService

interface txtorcon.IFilesystemOnionService

Extends: txtorcon.onion.IOnionService

Encapsulates a single filesystem-based service.

Note this is a subclass of IOnionService; it just adds two attributes that ephemeral services lack: hidden_service_directory and group_readable.

hidden_service_directory

The directory where private data is kept

group_readable

set HiddenServiceGroupReadable if true

Both kinds of authenticated service (ephemeral or disk) implement these interfaces:

IAuthenticatedOnionClients

interface txtorcon.IAuthenticatedOnionClients

This encapsulates both ‘stealth’ and ‘basic’ authenticated Onion services, whether ephemeral or not.

Each client has an arbitrary (ASCII, no spaces) name. You may access the clients with get_client, which will all be txtorcon.IOnionClient instances.

get_permanent_id(self)
Returns:the service’s permanent id, in hex

(For authenticated services, this is not the same as the .onion URI of any of the clients). The Permanent ID is the base32 encoding of the first 10 bytes of the SHA1 hash of the public-key of the service.

client_names(self)
Returns:list of str instances, one for each client
get_client(self, name)
Returns:object implementing IOnionClient for the named client
add_client(self, name)

probably should return a Deferred?

del_client(self, name)

probably should return a Deferred?

IOnionClient

interface txtorcon.IOnionClient

Extends: txtorcon.onion.IOnionService

A single client from a ‘parent’ IAuthenticatedOnionClients. We do this because hidden services can have different URLs and/or auth_tokens on a per-client basis. So, the only way to access anything from an authenticated onion service is to list the cleints – which gives you one IOnionClient per client.

Note that this inherits from txtorcon.IOnionService and adds only those attributes required for authentication. For ‘stealth’ authentication, the hostnames of each client will be unique; for ‘basic’ authentication the hostname is the same. The auth_tokens are always unique – these are given to clients to include using the Tor option HidServAuth

auth_token

Some secret bytes

name
parent

the IAuthenticatedOnionClients instance who owns me

Concrete classes implementing specific variations of Onion services. First, ephemeral services (private keys do not live on disk). See Onion (Hidden) Services for an overview of the variations.

EphemeralOnionService

class txtorcon.EphemeralOnionService(config, ports, hostname=None, private_key=None, version=3, detach=False, await_all_uploads=None, **kwarg)

Bases: object

An Onion service whose keys live in memory and are not persisted by Tor.

It is up to the application developer to retrieve and store the private key if this service is ever to be brought online again.

Users should create instances of this class by using the async method txtorcon.EphemeralOnionService.create()

static create(*args, **kwargs)

returns a new EphemeralOnionService after adding it to the provided config and ensuring at least one of its descriptors is uploaded.

Parameters:
  • config – a txtorcon.TorConfig instance
  • ports – a list of ports to make available; any of these can be 2-tuples of (remote, local) if you want to expose a particular port locally (otherwise, an available one is chosen)
  • private_key – None, DISCARD, or a private key blob
  • detach – if True, tell Tor to NOT associate this control connection with the lifetime of the created service
  • version – 2 or 3, which kind of service to create
  • progress – a callable taking (percent, tag, description) that is called periodically to report progress.

See also txtorcon.Tor.create_onion_service() (which ultimately calls this).

remove(**kwargs)

Issues a DEL_ONION call to our tor, removing this service.

ports
version
hostname
private_key

EphemeralAuthenticatedOnionService

class txtorcon.EphemeralAuthenticatedOnionService(config, ports, hostname=None, private_key=None, auth=[], version=3, detach=False)

Bases: object

An onion service with either ‘stealth’ or ‘basic’ authentication and keys stored in memory only (Tor doesn’t store the private keys anywhere and erases them when shutting down).

Use the async class-method create to make instances of this.

Users should create instances of this class by using the async method txtorcon.EphemeralAuthenticatedOnionService.create()

static create(*args, **kwargs)

returns a new EphemeralAuthenticatedOnionService after adding it to the provided config and ensuring at least one of its descriptors is uploaded.

Parameters:
  • config – a txtorcon.TorConfig instance
  • ports – a list of ports to make available; any of these can be 2-tuples of (remote, local) if you want to expose a particular port locally (otherwise, an available one is chosen)
  • private_key – None, DISCARD, or a private key blob
  • detach – if True, tell Tor to NOT associate this control connection with the lifetime of the created service
  • version – 2 or 3, which kind of service to create
  • progress – a callable taking (percent, tag, description) that is called periodically to report progress.

See also txtorcon.Tor.create_onion_service() (which ultimately calls this).

get_permanent_id()

IAuthenticatedOnionClients API

client_names()
get_client(name)
hostname
ports
version
private_key
remove(**kwargs)

Issues a DEL_ONION call to our tor, removing this service.

EphemeralAuthenticatedOnionServiceClient

class txtorcon.EphemeralAuthenticatedOnionServiceClient(parent, name, token)

Bases: object

A single client of an EphemeralAuthenticatedOnionService

These are only created by and returned from the .clients property of an AuthenticatedOnionService instance.

name
ports
hostname
auth_token
parent
version

Onion services which store their secret keys on disk:

FilesystemOnionService

class txtorcon.FilesystemOnionService(config, thedir, ports, version=3, group_readable=0)

Bases: object

An Onion service whose keys are stored on disk.

Do not instantiate directly; use txtorcon.onion.FilesystemOnionService.create()

static create(*args, **kwargs)

returns a new FilesystemOnionService after adding it to the provided config and ensuring at least one of its descriptors is uploaded.

Parameters:
  • config – a txtorcon.TorConfig instance
  • ports – a list of ports to make available; any of these can be 2-tuples of (remote, local) if you want to expose a particular port locally (otherwise, an available one is chosen)
  • hsdir – the directory in which to store private keys
  • version – 2 or 3, which kind of service to create
  • group_readable – if True, the Tor option HiddenServiceDirGroupReadable is set to 1 for this service
  • progress – a callable taking (percent, tag, description) that is called periodically to report progress.

See also txtorcon.Tor.create_onion_service() (which ultimately calls this).

hostname
private_key
ports
directory
dir
group_readable
version
config_attributes()

Helper method used by TorConfig when generating a torrc file and SETCONF commands

FilesystemAuthenticatedOnionService

class txtorcon.FilesystemAuthenticatedOnionService(config, thedir, ports, auth, version=3, group_readable=0)

Bases: object

An Onion service whose keys are stored on disk by Tor and which does authentication.

static create(*args, **kwargs)

returns a new FilesystemAuthenticatedOnionService after adding it to the provided config and ensureing at least one of its descriptors is uploaded.

Parameters:
  • config – a txtorcon.TorConfig instance
  • ports – a list of ports to make available; any of these can be 2-tuples of (remote, local) if you want to expose a particular port locally (otherwise, an available one is chosen)
  • auth – an instance of txtorcon.AuthBasic or txtorcon.AuthStealth
  • version – 2 or 3, which kind of service to create
  • group_readable – if True, the Tor option HiddenServiceDirGroupReadable is set to 1 for this service
  • progress – a callable taking (percent, tag, description) that is called periodically to report progress.
hidden_service_directory
group_readable
ports
version
get_permanent_id()

IAuthenticatedOnionClients API

client_names()

IAuthenticatedOnionClients API

get_client(name)

IAuthenticatedOnionClients API

add_client(name, hostname, ports, token)
config_attributes()

Helper method used by TorConfig when generating a torrc file and SETCONF commands

FilesystemAuthenticatedOnionServiceClient

class txtorcon.FilesystemAuthenticatedOnionServiceClient(parent, name, hostname, ports, token)

Bases: object

A single client of an FilesystemAuthenticatedOnionService

These are only created by and returned from the .clients property of an FilesystemAuthenticatedOnionService instance.

name
parent
ports
private_key
group_readable
authorize_client
hidden_service_directory
version

Some utility-style classes:

AuthBasic

class txtorcon.AuthBasic(clients)

Bases: txtorcon.onion._AuthCommon

Authentication details for ‘basic’ auth.

auth_type = 'basic'

AuthStealth

class txtorcon.AuthStealth(clients)

Bases: txtorcon.onion._AuthCommon

Authentication details for ‘stealth’ auth.

auth_type = 'stealth'