Onion APIs

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

For non-authenticated services:


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.


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.

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


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.


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

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.


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

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()


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

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()


class txtorcon.EphemeralAuthenticatedOnionServiceClient(parent, name, token)

A single client of an EphemeralAuthenticatedOnionService

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

Onion services which store their secret keys on disk:


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

An Onion service whose keys are stored on disk.

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


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

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


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

A single client of an FilesystemAuthenticatedOnionService

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

Some utility-style classes:


class txtorcon.AuthBasic(clients)

Authentication details for ‘basic’ auth.


class txtorcon.AuthStealth(clients)

Authentication details for ‘stealth’ auth.