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 (https://collector.torproject.org/).
- 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
- 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 0x7f3261dc3848>, 'network-status-version': <function _parse_header_network_status_version_line at 0x7f3261dc3050>, 'consensus-method': <function _parse_header_consensus_method_line at 0x7f3261dc32a8>, 'known-flags': <function <lambda> at 0x7f3261dc38c0>, 'voting-delay': <function _parse_header_voting_delay_line at 0x7f3261dc3320>, 'valid-until': <function _parse at 0x7f3261dc3758>, 'vote-status': <function _parse_header_vote_status_line at 0x7f3261dc31b8>, 'consensus-methods': <function _parse_header_consensus_methods_line at 0x7f3261dc3230>, 'valid-after': <function _parse at 0x7f3261dc3668>, 'package': <function _parse_package_line at 0x7f3261dc35f0>, 'fresh-until': <function _parse at 0x7f3261dc36e0>, 'client-versions': <function _parse at 0x7f3261dc37d0>, 'published': <function _parse at 0x7f3261dcde60>, 'params': <function _parse_header_parameters_line at 0x7f3261dc3488>, 'flag-thresholds': <function _parse_header_flag_thresholds_line at 0x7f3261dc3410>}¶
- FOOTER_PARSER_FOR_LINE = {'directory-signature': <function _parse_footer_directory_signature_line at 0x7f3261dc3578>, 'bandwidth-weights': <function <lambda> at 0x7f3261dc3938>, 'directory-footer': <function _parse_directory_footer_line at 0x7f3261dc3500>}¶
- 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