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.
- Archived descriptors provided by CollecTor.
- 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
For a great graphical overview see Jordan Wright's chart describing the anatomy of the consensus.
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
Bases: tuple
PackageVersion(name, version, url, digests)
- 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 0xb552b8f0>, 'network-status-version': <function _parse_header_network_status_version_line at 0xb552b4b0>, 'consensus-method': <function _parse_header_consensus_method_line at 0xb552b5f0>, 'known-flags': <function <lambda> at 0xb552b930>, 'voting-delay': <function _parse_header_voting_delay_line at 0xb552b630>, 'valid-until': <function _parse at 0xb552b870>, 'vote-status': <function _parse_header_vote_status_line at 0xb552b570>, 'consensus-methods': <function _parse_header_consensus_methods_line at 0xb552b5b0>, 'valid-after': <function _parse at 0xb552b7f0>, 'package': <function _parse_package_line at 0xb552b7b0>, 'fresh-until': <function _parse at 0xb552b830>, 'client-versions': <function _parse at 0xb552b8b0>, 'published': <function _parse at 0xb552b3f0>, 'params': <function _parse_header_parameters_line at 0xb552b6f0>, 'flag-thresholds': <function _parse_header_flag_thresholds_line at 0xb552b6b0>}¶
- FOOTER_PARSER_FOR_LINE = {'directory-signature': <function _parse_footer_directory_signature_line at 0xb552b770>, 'bandwidth-weights': <function <lambda> at 0xb552b970>, 'directory-footer': <function _parse_directory_footer_line at 0xb552b730>}¶
- 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: - legacy_dir_key (str) -- fingerprint of and obsolete identity key
- key_certificate (stem.descriptor.networkstatus.KeyCertificate) -- * authority's key certificate
* 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