
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 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 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>}

   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
