
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

class class stem.descriptor.networkstatus.NetworkStatusDocument(raw_content)

   Bases: "stem.descriptor.Descriptor"

   Common parent for network status documents.

   get_unrecognized_lines()

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

   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=True, 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

      * **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)

      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=True, 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

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

   get_unrecognized_lines()

      Returns any unrecognized lines.

      Returns:
         a list of unrecognized lines

class class stem.descriptor.networkstatus.KeyCertificate(raw_content, validate=True)

   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

   get_unrecognized_lines()

      Returns any unrecognized lines.

      Returns:
         **list** of unrecognized lines

class class stem.descriptor.networkstatus.DocumentSignature(method, identity, key_digest, signature, validate=True)

   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=True)

   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
