Stem Docs

Network Status Documents

Network Status Documents

Parsing for Tor network status documents. This supports both the v2 and v3 dir-spec. Documents can be obtained from a few sources...

... and contain the following sections...

Of these, the router status entry section can be quite large (on the order of hundreds of kilobytes). As such we provide a couple of methods for reading network status documents through parse_file(). For more information see DocumentHandler()...

from stem.descriptor import parse_file, DocumentHandler

with open('.tor/cached-consensus', 'rb') as consensus_file:
  # Processes the routers as we read them in. The routers refer to a document
  # with an unset 'routers' attribute.

  for router in parse_file(consensus_file, 'network-status-consensus-3 1.0', document_handler = DocumentHandler.ENTRIES):
    print router.nickname

Module Overview:

NetworkStatusDocument - Network status document
  |- NetworkStatusDocumentV2 - Version 2 network status document
  |- NetworkStatusDocumentV3 - Version 3 network status document
  +- BridgeNetworkStatusDocument - Version 3 network status document for bridges

KeyCertificate - Certificate used to authenticate an authority
DocumentSignature - Signature of a document by a directory authority
DirectoryAuthority - Directory authority as defined in a v3 network status document
stem.descriptor.networkstatus.PackageVersion

Latest recommended version of a package that's available.

Variables:
  • name (str) -- name of the package
  • version (str) -- latest recommended version
  • url (str) -- package's url
  • digests (dict) -- mapping of digest types to their value
class stem.descriptor.networkstatus.PackageVersion(name, version, url, digests)

Bases: tuple

digests

Alias for field number 3

name

Alias for field number 0

url

Alias for field number 2

version

Alias for field number 1

class stem.descriptor.networkstatus.NetworkStatusDocument(contents, lazy_load=False)[source]

Bases: stem.descriptor.Descriptor

Common parent for network status documents.

class stem.descriptor.networkstatus.NetworkStatusDocumentV2(raw_content, validate=False)[source]

Bases: stem.descriptor.networkstatus.NetworkStatusDocument

Version 2 network status document. These have been deprecated and are no longer generated by Tor.

Variables:
  • routers (dict) -- fingerprints to RouterStatusEntryV2 contained in the document
  • version (int) -- * document version
  • hostname (str) -- * hostname of the authority
  • address (str) -- * authority's IP address
  • dir_port (int) -- * authority's DirPort
  • fingerprint (str) -- * authority's fingerprint
  • contact (str) -- * authority's contact information
  • signing_key (str) -- * authority's public signing key
  • client_versions (list) -- list of recommended client tor version strings
  • server_versions (list) -- list of recommended server tor version strings
  • published (datetime) -- * time when the document was published
  • options (list) -- * list of things that this authority decides
  • signing_authority (str) -- * name of the authority signing the document
  • signature (str) -- * authority's signature for the document

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

class stem.descriptor.networkstatus.NetworkStatusDocumentV3(raw_content, validate=False, default_params=True)[source]

Bases: stem.descriptor.networkstatus.NetworkStatusDocument

Version 3 network status document. This could be either a vote or consensus.

Variables:
  • routers (tuple) -- RouterStatusEntryV3 contained in the document
  • version (int) -- * document version
  • version_flavor (str) -- * flavor associated with the document (such as 'microdesc')
  • is_consensus (bool) -- * True if the document is a consensus
  • is_vote (bool) -- * True if the document is a vote
  • is_microdescriptor (bool) -- * True if this is a microdescriptor flavored document, False otherwise
  • valid_after (datetime) -- * time when the consensus became valid
  • fresh_until (datetime) -- * time when the next consensus should be produced
  • valid_until (datetime) -- * time when this consensus becomes obsolete
  • vote_delay (int) -- * number of seconds allowed for collecting votes from all authorities
  • dist_delay (int) -- * number of seconds allowed for collecting signatures from all authorities
  • client_versions (list) -- list of recommended client tor versions
  • server_versions (list) -- list of recommended server tor versions
  • packages (list) -- * list of PackageVersion entries
  • known_flags (list) -- * list of Flag for the router's flags
  • params (dict) -- * dict of parameter(str) => value(int) mappings
  • directory_authorities (list) -- * list of DirectoryAuthority objects that have generated this document
  • signatures (list) -- * DocumentSignature of the authorities that have signed the document

Consensus Attributes:

Variables:
  • consensus_method (int) -- method version used to generate this consensus
  • bandwidth_weights (dict) -- dict of weight(str) => value(int) mappings

Vote Attributes:

Variables:
  • consensus_methods (list) -- list of ints for the supported method versions
  • published (datetime) -- time when the document was published
  • flag_thresholds (dict) -- * mapping of internal performance thresholds used while making the vote, values are ints or floats

* 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.4.0: Added the packages attribute.

HEADER_PARSER_FOR_LINE = {'server-versions': <function _parse at 0xf5f65b1c>, 'network-status-version': <function _parse_header_network_status_version_line at 0xf5f65764>, 'consensus-method': <function _parse_header_consensus_method_line at 0xf5f6587c>, 'known-flags': <function <lambda> at 0xf5f65b54>, 'voting-delay': <function _parse_header_voting_delay_line at 0xf5f658b4>, 'valid-until': <function _parse at 0xf5f65aac>, 'vote-status': <function _parse_header_vote_status_line at 0xf5f6580c>, 'consensus-methods': <function _parse_header_consensus_methods_line at 0xf5f65844>, 'valid-after': <function _parse at 0xf5f65a3c>, 'package': <function _parse_package_line at 0xf5f65a04>, 'fresh-until': <function _parse at 0xf5f65a74>, 'client-versions': <function _parse at 0xf5f65ae4>, 'published': <function _parse at 0xf5f656bc>, 'params': <function _parse_header_parameters_line at 0xf5f6595c>, 'flag-thresholds': <function _parse_header_flag_thresholds_line at 0xf5f65924>}
FOOTER_PARSER_FOR_LINE = {'directory-signature': <function _parse_footer_directory_signature_line at 0xf5f659cc>, 'bandwidth-weights': <function <lambda> at 0xf5f65b8c>, 'directory-footer': <function _parse_directory_footer_line at 0xf5f65994>}
get_unrecognized_lines()[source]
meets_consensus_method(method)[source]

Checks if we meet the given consensus-method. This works for both votes and consensuses, checking our 'consensus-method' and 'consensus-methods' entries.

Parameters:method (int) -- consensus-method to check for
Returns:True if we meet the given consensus-method, and False otherwise
class stem.descriptor.networkstatus.DirectoryAuthority(raw_content, validate=False, is_vote=False)[source]

Bases: stem.descriptor.Descriptor

Directory authority information obtained from a v3 network status document.

Authorities can optionally use a legacy format. These are no longer found in practice, but have the following differences...

  • The authority's nickname ends with '-legacy'.
  • There's no contact or vote_digest attribute.
Variables:
  • nickname (str) -- * authority's nickname
  • v3ident (str) -- * identity key fingerprint used to sign votes and consensus
  • hostname (str) -- * hostname of the authority
  • address (str) -- * authority's IP address
  • dir_port (int) -- * authority's DirPort
  • or_port (int) -- * authority's ORPort
  • is_legacy (bool) -- * if the authority's using the legacy format
  • contact (str) -- contact information, this is included if is_legacy is False

Consensus Attributes:

Variables:vote_digest (str) -- digest of the authority that contributed to the consensus, this is included if is_legacy is False

Vote Attributes:

Variables:

* mandatory attribute

Changed in version 1.4.0: Renamed our 'fingerprint' attribute to 'v3ident' (prior attribute exists for backward compatability, but is deprecated).

class stem.descriptor.networkstatus.KeyCertificate(raw_content, validate=False)[source]

Bases: stem.descriptor.Descriptor

Directory key certificate for a v3 network status document.

Variables:
  • version (int) -- * version of the key certificate
  • address (str) -- authority's IP address
  • dir_port (int) -- authority's DirPort
  • fingerprint (str) -- * authority's fingerprint
  • identity_key (str) -- * long term authority identity key
  • published (datetime) -- * time when this key was generated
  • expires (datetime) -- * time after which this key becomes invalid
  • signing_key (str) -- * directory server's public signing key
  • crosscert (str) -- signature made using certificate's signing key
  • certification (str) -- * signature of this key certificate signed with the identity key

* mandatory attribute

class stem.descriptor.networkstatus.DocumentSignature(method, identity, key_digest, signature, validate=False)[source]

Bases: object

Directory signature of a v3 network status document.

Variables:
  • method (str) -- algorithm used to make the signature
  • identity (str) -- fingerprint of the authority that made the signature
  • key_digest (str) -- digest of the signing key
  • signature (str) -- document signature
Parameters:

validate (bool) -- checks validity if True

Raises:

ValueError if a validity check fails

class stem.descriptor.networkstatus.BridgeNetworkStatusDocument(raw_content, validate=False)[source]

Bases: stem.descriptor.networkstatus.NetworkStatusDocument

Network status document containing bridges. This is only available through the metrics site.

Variables:
  • routers (tuple) -- RouterStatusEntryV2 contained in the document
  • published (datetime) -- time when the document was published