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