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...
- the 'cached-consensus' file in tor's data directory
- tor metrics, at https://metrics.torproject.org/data.html
- directory authorities and mirrors via their DirPort
... and contain the following sections...
- document header
- list of stem.descriptor.networkstatus.DirectoryAuthority
- list of stem.descriptor.router_status_entry.RouterStatusEntry
- document footer
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.
- 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: - legacy_dir_key (str) -- fingerprint of and obsolete identity key
- key_certificate (stem.descriptor.networkstatus.KeyCertificate) -- * authority's key certificate
* mandatory attribute
- 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
- 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