# 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.

## 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.

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.

## 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

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

## EphemeralAuthenticatedOnionService

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

## EphemeralAuthenticatedOnionServiceClient

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:

## FilesystemOnionService

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

## FilesystemAuthenticatedOnionService

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.

## FilesystemAuthenticatedOnionServiceClient

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:

## AuthBasic

class txtorcon.AuthBasic(clients)

  Authentication details for ‘basic’ auth.

## AuthStealth

class txtorcon.AuthStealth(clients)

  Authentication details for ‘stealth’ auth.