Stem Docs

Hidden Service Descriptor

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[source]

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[source]

Bases: 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)[source]

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)[source]

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)[source]

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[source]

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