Stem Docs

Server Descriptor

Server Descriptor

Parsing for Tor server descriptors, which contains the infrequently changing information about a Tor relay (contact information, exit policy, public keys, etc). This information is provided from a few sources...

Module Overview:

ServerDescriptor - Tor server descriptor.
  |- RelayDescriptor - Server descriptor for a relay.
  |  +- make_router_status_entry - Creates a router status entry for this descriptor.
  |- BridgeDescriptor - Scrubbed server descriptor for a bridge.
  |  |- is_scrubbed - checks if our content has been properly scrubbed
  |  +- get_scrubbing_issues - description of issues with our scrubbing
  |- digest - calculates the upper-case hex digest value for our content
  |- get_annotations - dictionary of content prior to the descriptor entry
  +- get_annotation_lines - lines that provided the annotations
class stem.descriptor.server_descriptor.ServerDescriptor(raw_contents, validate=False, annotations=None)[source]

Bases: stem.descriptor.Descriptor

Common parent for server descriptors.

  • nickname (str) -- * relay's nickname
  • fingerprint (str) -- identity key fingerprint
  • published (datetime) -- * time in UTC when this descriptor was made
  • address (str) -- * IPv4 address of the relay
  • or_port (int) -- * port used for relaying
  • socks_port (int) -- * port used as client (deprecated, always None)
  • dir_port (int) -- * port used for descriptor mirroring
  • platform (bytes) -- line with operating system and tor version
  • tor_version (stem.version.Version) -- version of tor
  • operating_system (str) -- operating system
  • uptime (int) -- uptime when published in seconds
  • contact (bytes) -- contact information
  • exit_policy (stem.exit_policy.ExitPolicy) -- * stated exit policy
  • exit_policy_v6 (stem.exit_policy.MicroExitPolicy) -- * exit policy for IPv6
  • family (set) -- * nicknames or fingerprints of declared family
  • average_bandwidth (int) -- * average rate it's willing to relay in bytes/s
  • burst_bandwidth (int) -- * burst rate it's willing to relay in bytes/s
  • observed_bandwidth (int) -- * estimated capacity based on usage in bytes/s
  • link_protocols (list) -- link protocols supported by the relay
  • circuit_protocols (list) -- circuit protocols supported by the relay
  • hibernating (bool) -- * hibernating when published
  • allow_single_hop_exits (bool) -- * flag if single hop exiting is allowed
  • allow_tunneled_dir_requests (bool) -- * flag if tunneled directory requests are accepted
  • extra_info_cache (bool) -- * flag if a mirror for extra-info documents
  • extra_info_digest (str) -- upper-case hex encoded digest of our extra-info document
  • extra_info_sha256_digest (str) -- base64 encoded sha256 digest of our extra-info document
  • eventdns (bool) -- flag for evdns backend (deprecated, always unset)
  • ntor_onion_key (str) -- base64 key used to encrypt EXTEND in the ntor protocol
  • or_addresses (list) -- * alternative for our address/or_port attributes, each entry is a tuple of the form (address (str), port (int), is_ipv6 (bool))
  • protocols (dict) -- mapping of protocols to their supported versions

Deprecated, moved to extra-info descriptor...

  • read_history_end (datetime) -- end of the sampling interval
  • read_history_interval (int) -- seconds per interval
  • read_history_values (list) -- bytes read during each interval
  • write_history_end (datetime) -- end of the sampling interval
  • write_history_interval (int) -- seconds per interval
  • write_history_values (list) -- bytes written during each interval

* 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.5.0: Added the allow_tunneled_dir_requests attribute.

Changed in version 1.6.0: Added the extra_info_sha256_digest and protocols attributes.


Provides the hex encoded sha1 of our content. This value is part of the network status entry for this relay.

Returns:unicode with the upper-case hex digest value for this server descriptor
get_annotations(*args, **kwds)[source]

Provides content that appeared prior to the descriptor. If this comes from the cached-descriptors file then this commonly contains content like...

@downloaded-at 2012-03-18 21:18:29
@source ""
Returns:dict with the key/value pairs in our annotations

Provides the lines of content that appeared prior to the descriptor. This is the same as the get_annotations() results, but with the unparsed lines and ordering retained.

Returns:list with the lines of annotation that came before this descriptor
class stem.descriptor.server_descriptor.RelayDescriptor(raw_contents, validate=False, annotations=None, skip_crypto_validation=False)[source]

Bases: stem.descriptor.server_descriptor.ServerDescriptor

Server descriptor (descriptor specification)

  • certificate (stem.certificate.Ed25519Certificate) -- ed25519 certificate
  • ed25519_certificate (str) -- base64 encoded ed25519 certificate
  • ed25519_master_key (str) -- base64 encoded master key for our ed25519 certificate
  • ed25519_signature (str) -- signature of this document using ed25519
  • onion_key (str) -- * key used to encrypt EXTEND cells
  • onion_key_crosscert (str) -- signature generated using the onion_key
  • ntor_onion_key_crosscert (str) -- signature generated using the ntor-onion-key
  • ntor_onion_key_crosscert_sign (str) -- sign of the corresponding ed25519 public key
  • signing_key (str) -- * relay's long-term identity key
  • signature (str) -- * signature for this descriptor

* attribute is required when we're parsed with validation

Changed in version 1.5.0: Added the ed25519_certificate, ed25519_master_key, ed25519_signature, onion_key_crosscert, ntor_onion_key_crosscert, and ntor_onion_key_crosscert_sign attributes.

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 certificate attribute.

Deprecated since version 1.6.0: Our ed25519_certificate is deprecated in favor of our new certificate attribute. The base64 encoded certificate is available via the certificate's encoded attribute.

Changed in version 1.6.0: Added the skip_crypto_validation constructor argument.

classmethod content(attr=None, exclude=(), sign=False, signing_key=None)[source]
classmethod create(attr=None, exclude=(), validate=True, sign=False, signing_key=None)[source]
digest(*args, **kwds)[source]

Provides the digest of our descriptor's content.

Returns:the digest string encoded in uppercase hex
Raises :ValueError if the digest cannot be calculated

Provides a RouterStatusEntryV3 for this descriptor content.

New in version 1.6.0.

Returns:RouterStatusEntryV3 that would be in the consensus
class stem.descriptor.server_descriptor.BridgeDescriptor(raw_contents, validate=False, annotations=None)[source]

Bases: stem.descriptor.server_descriptor.ServerDescriptor

Bridge descriptor (bridge descriptor specification)

  • ed25519_certificate_hash (str) -- sha256 hash of the original identity-ed25519
  • router_digest_sha256 (str) -- sha256 digest of this document

Changed in version 1.5.0: Added the ed25519_certificate_hash and router_digest_sha256 attributes. Also added ntor_onion_key (previously this only belonged to unsanitized descriptors).

classmethod content(attr=None, exclude=(), sign=False)[source]

Checks if we've been properly scrubbed in accordance with the bridge descriptor specification. Validation is a moving target so this may not be fully up to date.

Returns:True if we're scrubbed, False otherwise
get_scrubbing_issues(*args, **kwds)[source]

Provides issues with our scrubbing.

Returns:list of strings which describe issues we have with our scrubbing, this list is empty if we're properly scrubbed