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
class stem.descriptor.networkstatus.NetworkStatusDocument(raw_content)[source]

Bases: stem.descriptor.Descriptor

Common parent for network status documents.

get_unrecognized_lines()[source]
class stem.descriptor.networkstatus.NetworkStatusDocumentV2(raw_content, validate=True)[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=True, 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
  • 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

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=True, 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
  • fingerprint (str) – * authority’s fingerprint
  • 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

get_unrecognized_lines()[source]

Returns any unrecognized lines.

Returns:a list of unrecognized lines
class stem.descriptor.networkstatus.KeyCertificate(raw_content, validate=True)[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

get_unrecognized_lines()[source]

Returns any unrecognized lines.

Returns:list of unrecognized lines
class stem.descriptor.networkstatus.DocumentSignature(method, identity, key_digest, signature, validate=True)[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=True)[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