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...
- control port via ‘GETINFO desc/*’ queries
- the ‘cached-descriptors’ file in tor’s data directory
- tor metrics, at https://metrics.torproject.org/data.html
- directory authorities and mirrors via their DirPort
Module Overview:
ServerDescriptor - Tor server descriptor.
|- RelayDescriptor - Server descriptor for a relay.
| +- is_valid - checks the signature against the descriptor content
|
|- 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_unrecognized_lines - lines with unrecognized 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=True, annotations=None)[source]¶
Bases: stem.descriptor.Descriptor
Common parent for server descriptors.
Variables: - 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
- 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
- eventdns (bool) – flag for evdns backend (deprecated, always unset)
- 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))
Deprecated, moved to extra-info descriptor...
Variables: - 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
- digest()[source]¶
Provides the hex encoded sha1 of our content. This value is part of the network status entry for this relay.
Returns: str with the upper-case hex digest value for this server descriptor
- get_annotations()[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 "173.254.216.66"
Returns: dict with the key/value pairs in our annotations
- get_annotation_lines()[source]¶
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=True, annotations=None)[source]¶
Bases: stem.descriptor.server_descriptor.ServerDescriptor
Server descriptor (descriptor specification)
Variables: - onion_key (str) – * key used to encrypt EXTEND cells
- ntor_onion_key (str) – base64 key used to encrypt EXTEND in the ntor protocol
- signing_key (str) – * relay’s long-term identity key
- signature (str) – * signature for this descriptor
* attribute is required when we’re parsed with validation
- class stem.descriptor.server_descriptor.BridgeDescriptor(raw_contents, validate=True, annotations=None)[source]¶
Bases: stem.descriptor.server_descriptor.ServerDescriptor
Bridge descriptor (bridge descriptor specification)
- is_scrubbed()[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