Hidden Service Descriptor
*************************

Parsing for Tor hidden service descriptors as described in Tor’s rend-
spec.

Unlike other descriptor types these describe a hidden service rather
than a relay. They’re created by the service, and can only be fetched
via relays with the HSDir flag.

These are only available through the Controller’s
"get_hidden_service_descriptor()" method.

**Module Overview:**

   HiddenServiceDescriptor - Tor hidden service descriptor.

New in version 1.4.0.

class stem.descriptor.hidden_service_descriptor.IntroductionPoints

   Bases:
   "stem.descriptor.hidden_service_descriptor.IntroductionPoints"

   Variables:
      * **identifier** (*str*) – hash of this introduction point’s
        identity key

      * **address** (*str*) – address of this introduction point

      * **port** (*int*) – port where this introduction point is
        listening

      * **onion_key** (*str*) – public key for communicating with
        this introduction point

      * **service_key** (*str*) – public key for communicating with
        this hidden service

      * **intro_authentication** (*list*) – tuples of the form
        (auth_type, auth_data) for establishing a connection

exception stem.descriptor.hidden_service_descriptor.DecryptionFailure

   Bases: "exceptions.Exception"

   Failure to decrypt the hidden service descriptor’s introduction-
   points.

class stem.descriptor.hidden_service_descriptor.HiddenServiceDescriptor(raw_contents, validate=False, skip_crypto_validation=False)

   Bases: "stem.descriptor.Descriptor"

   Hidden service descriptor.

   Variables:
      * **descriptor_id** (*str*) – ***** identifier for this
        descriptor, this is a base32 hash of several fields

      * **version** (*int*) – ***** hidden service descriptor
        version

      * **permanent_key** (*str*) – ***** long term key of the
        hidden service

      * **secret_id_part** (*str*) – ***** hash of the time period,
        cookie, and replica values so our descriptor_id can be
        validated

      * **published** (*datetime*) – ***** time in UTC when this
        descriptor was made

      * **protocol_versions** (*list*) – ***** list of **int**
        versions that are supported when establishing a connection

      * **introduction_points_encoded** (*str*) – raw introduction
        points blob

      * **introduction_points_auth** (*list*) – ***** tuples of the
        form (auth_method, auth_data) for our
        introduction_points_content (**deprecated**, always **[]**)

      * **introduction_points_content** (*bytes*) – decoded
        introduction-points content without authentication data, if
        using cookie authentication this is encrypted

      * **signature** (*str*) – signature of the descriptor content

   ***** attribute is either required when we’re parsed with
   validation or has a default value, others are left as **None** if
   undefined

   Changed in version 1.6.0: Moved from the deprecated pycrypto module
   to cryptography for validating signatures.

   Changed in version 1.6.0: Added the **skip_crypto_validation**
   constructor argument.

   classmethod content(attr=None, exclude=(), sign=False)

      Creates descriptor content with the given attributes. Mandatory
      fields are filled with dummy information unless data is
      supplied. This doesn’t yet create a valid signature.

      New in version 1.6.0.

      Parameters:
         * **attr** (*dict*) – keyword/value mappings to be included
           in the descriptor

         * **exclude** (*list*) – mandatory keywords to exclude from
           the descriptor, this results in an invalid descriptor

         * **sign** (*bool*) – includes cryptographic signatures and
           digests if True

      Returns:
         **str** with the content of a descriptor

      Raises:
         * **ImportError** if cryptography is unavailable and sign
           is True

         * **NotImplementedError** if not implemented for this
           descriptor type

   classmethod create(attr=None, exclude=(), validate=True, sign=False)

      Creates a descriptor with the given attributes. Mandatory fields
      are filled with dummy information unless data is supplied. This
      doesn’t yet create a valid signature.

      New in version 1.6.0.

      Parameters:
         * **attr** (*dict*) – keyword/value mappings to be included
           in the descriptor

         * **exclude** (*list*) – mandatory keywords to exclude from
           the descriptor, this results in an invalid descriptor

         * **validate** (*bool*) – checks the validity of the
           descriptor’s content if **True**, skips these checks
           otherwise

         * **sign** (*bool*) – includes cryptographic signatures and
           digests if True

      Returns:
         "Descriptor" subclass

      Raises:
         * **ValueError** if the contents is malformed and validate
           is True

         * **ImportError** if cryptography is unavailable and sign
           is True

         * **NotImplementedError** if not implemented for this
           descriptor type

   introduction_points(**kwds)

      Provided this service’s introduction points.

      Returns:
         **list** of "IntroductionPoints"

      Raises:
         * **ValueError** if the our introduction-points is
           malformed

         * **DecryptionFailure** if unable to decrypt this field
