
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 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 class stem.descriptor.networkstatus.NetworkStatusDocument(contents, lazy_load=False)

   Bases: "stem.descriptor.Descriptor"

   Common parent for network status documents.

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

   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 class stem.descriptor.networkstatus.NetworkStatusDocumentV3(raw_content, validate=False, default_params=True)

   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 0x343dde8>, 'network-status-version': <function _parse_header_network_status_version_line at 0x343d5f0>, 'consensus-method': <function _parse_header_consensus_method_line at 0x343d848>, 'known-flags': <function <lambda> at 0x343de60>, 'voting-delay': <function _parse_header_voting_delay_line at 0x343d8c0>, 'valid-until': <function _parse at 0x343dcf8>, 'vote-status': <function _parse_header_vote_status_line at 0x343d758>, 'consensus-methods': <function _parse_header_consensus_methods_line at 0x343d7d0>, 'valid-after': <function _parse at 0x343dc08>, 'package': <function _parse_package_line at 0x343db90>, 'fresh-until': <function _parse at 0x343dc80>, 'client-versions': <function _parse at 0x343dd70>, 'published': <function _parse at 0x343d488>, 'params': <function _parse_header_parameters_line at 0x343da28>, 'flag-thresholds': <function _parse_header_flag_thresholds_line at 0x343d9b0>}

   FOOTER_PARSER_FOR_LINE = {'directory-signature': <function _parse_footer_directory_signature_line at 0x343db18>, 'bandwidth-weights': <function <lambda> at 0x343ded8>, 'directory-footer': <function _parse_directory_footer_line at 0x343daa0>}

   get_unrecognized_lines()

   meets_consensus_method(method)

      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 class stem.descriptor.networkstatus.DirectoryAuthority(raw_content, validate=False, is_vote=False)

   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 class stem.descriptor.networkstatus.KeyCertificate(raw_content, validate=False)

   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 class stem.descriptor.networkstatus.DocumentSignature(method, identity, key_digest, signature, validate=False)

   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 class stem.descriptor.networkstatus.BridgeNetworkStatusDocument(raw_content, validate=False)

   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
