hidden services.

Our **ports** argument can be a single port...

::

  create_ephemeral_hidden_service(80)

... list of ports the service is available on...

::

  create_ephemeral_hidden_service([80, 443])

... or a mapping of hidden service ports to their targets...

::

  create_ephemeral_hidden_service({80: 80, 443: '173.194.33.133:443'})

If **basic_auth** is provided this service will require basic
authentication to access. This means users must set HidServAuth in their
torrc with credentials to access it.

**basic_auth** is a mapping of usernames to their credentials. If the
credential is **None** one is generated and returned as part of the
response. For instance, only bob can access using the given newly generated
credentials...

::

  >>> response = controller.create_ephemeral_hidden_service(80, basic_auth = {'bob': None})
  >>> print(response.client_auth)
  {'bob': 'nKwfvVPmTNr2k2pG0pzV4g'}

... while both alice and bob can access with existing credentials in the
following...

::

  controller.create_ephemeral_hidden_service(80, basic_auth = {
    'alice': 'l4BT016McqV2Oail+Bwe6w',
    'bob': 'vGnNRpWYiMBFTWD2gbBlcA',
  })

Please note that **basic_auth** only works for legacy (v2) hidden services.

To use client auth with a **version 3** service, pass the **client_auth_v3**
argument. The value must be a base32-encoded public key from a key pair you
have generated elsewhere.

To create a **version 3** service simply specify **ED25519-V3** as the
our key type, and to create a **version 2** service use **RSA1024**. The
default version of newly created hidden services is based on the
**HiddenServiceVersion** value in your torrc...

::

  response = controller.create_ephemeral_hidden_service(
    80,
    key_content = 'ED25519-V3',
    await_publication = True,
  )

  print('service established at %s.onion' % response.service_id)

.. versionadded:: 1.4.0

.. versionchanged:: 1.5.0
   Added the basic_auth argument.

.. versionchanged:: 1.5.0
   Added support for non-anonymous services. To do so set
   'HiddenServiceSingleHopMode 1' and 'HiddenServiceNonAnonymousMode 1' in
   your torrc.

.. versionchanged:: 1.7.0
   Added the timeout and max_streams arguments.

.. versionchanged:: 1.8.2
   Added the client_auth_v3 argument.

:param int,list,dict ports: hidden service port(s) or mapping of hidden
  service ports to their targets
:param str key_type: type of key being provided, generates a new key if
  'NEW' (options are: **NEW**, **RSA1024**, and **ED25519-V3**)
:param str key_content: key for the service to use or type of key to be
  generated (options when **key_type** is **NEW** are **BEST**,
  **RSA1024**, and **ED25519-V3**)
:param bool discard_key: avoid providing the key back in our response
:param bool detached: continue this hidden service even after this control
  connection is closed if **True**
:param bool await_publication: blocks until our descriptor is successfully
  published if **True**
:param float timeout: seconds to wait when **await_result** is **True**
:param dict basic_auth: required user credentials to access a v2 service
:param int max_streams: maximum number of streams the hidden service will
  accept, unlimited if zero or not set
:param str client_auth_v3: base32-encoded public key for **version 3**
  onion services that require client authentication

:returns: :class:`~stem.response.add_onion.AddOnionResponse` with the response

:raises:
  * :class:`stem.ControllerError` if the call fails
  * :class:`stem.Timeout` if **timeout** was reached
r