
Server Descriptor
*****************

Parsing for Tor server descriptors, which contains the infrequently
changing information about a Tor relay (contact information, exit
policy, public keys, etc). This information is provided from a few
sources...

* The control port via 'GETINFO desc/*' queries.

* The 'cached-descriptors' file in Tor's data directory.

* Archived descriptors provided by CollecTor.

* Directory authorities and mirrors via their DirPort.

**Module Overview:**

   ServerDescriptor - Tor server descriptor.
     |- RelayDescriptor - Server descriptor for a relay.
     |  +- make_router_status_entry - Creates a router status entry for this descriptor.
     |
     |- BridgeDescriptor - Scrubbed server descriptor for a bridge.
     |  |- is_scrubbed - checks if our content has been properly scrubbed
     |  +- get_scrubbing_issues - description of issues with our scrubbing
     |
     |- digest - calculates the upper-case hex digest value for our content
     |- get_annotations - dictionary of content prior to the descriptor entry
     +- get_annotation_lines - lines that provided the annotations

stem.descriptor.server_descriptor.BridgeDistribution(enum)

   Preferred method of distributing this relay if a bridge.

   New in version 1.6.0.

   +-----------------------+---------------------------------------------------------------------+
   | BridgeDistribution    | Description                                                         |
   +=======================+=====================================================================+
   | **ANY**               | No proference, BridgeDB will pick how the bridge is distributed.    |
   +-----------------------+---------------------------------------------------------------------+
   | **HTTPS**             | Provided via the web interface.                                     |
   +-----------------------+---------------------------------------------------------------------+
   | **EMAIL**             | Provided in response to emails to bridges@torproject.org.           |
   +-----------------------+---------------------------------------------------------------------+
   | **MOAT**              | Provided in interactive menus within Tor Browser.                   |
   +-----------------------+---------------------------------------------------------------------+
   | **HYPHAE**            | Provided via a cryptographic invitation-based system.               |
   +-----------------------+---------------------------------------------------------------------+

class class stem.descriptor.server_descriptor.ServerDescriptor(raw_contents, validate=False, annotations=None)

   Bases: "stem.descriptor.Descriptor"

   Common parent for server descriptors.

   Variables:
      * **nickname** (*str*) -- ***** relay's nickname

      * **fingerprint** (*str*) -- identity key fingerprint

      * **published** (*datetime*) -- ***** time in UTC when this
        descriptor was made

      * **address** (*str*) -- ***** IPv4 address of the relay

      * **or_port** (*int*) -- ***** port used for relaying

      * **socks_port** (*int*) -- ***** port used as client
        (**deprecated**, always **None**)

      * **dir_port** (*int*) -- ***** port used for descriptor
        mirroring

      * **platform** (*bytes*) -- line with operating system and tor
        version

      * **tor_version** (*stem.version.Version*) -- version of tor

      * **operating_system** (*str*) -- operating system

      * **uptime** (*int*) -- uptime when published in seconds

      * **contact** (*bytes*) -- contact information

      * **exit_policy** (*stem.exit_policy.ExitPolicy*) -- *****
        stated exit policy

      * **exit_policy_v6** (*stem.exit_policy.MicroExitPolicy*) --
        ***** exit policy for IPv6

      * **bridge_distribution** (*BridgeDistribution*) -- *****
        preferred method of providing this relay's address if a bridge

      * **family** (*set*) -- ***** nicknames or fingerprints of
        declared family

      * **average_bandwidth** (*int*) -- ***** average rate it's
        willing to relay in bytes/s

      * **burst_bandwidth** (*int*) -- ***** burst rate it's willing
        to relay in bytes/s

      * **observed_bandwidth** (*int*) -- ***** estimated capacity
        based on usage in bytes/s

      * **link_protocols** (*list*) -- link protocols supported by the
        relay

      * **circuit_protocols** (*list*) -- circuit protocols supported
        by the relay

      * **is_hidden_service_dir** (*bool*) -- ***** indicates if the
        relay serves hidden service descriptors

      * **hibernating** (*bool*) -- ***** hibernating when published

      * **allow_single_hop_exits** (*bool*) -- ***** flag if single
        hop exiting is allowed

      * **allow_tunneled_dir_requests** (*bool*) -- ***** flag if
        tunneled directory requests are accepted

      * **extra_info_cache** (*bool*) -- ***** flag if a mirror for
        extra-info documents

      * **extra_info_digest** (*str*) -- upper-case hex encoded digest
        of our extra-info document

      * **extra_info_sha256_digest** (*str*) -- base64 encoded sha256
        digest of our extra-info document

      * **eventdns** (*bool*) -- flag for evdns backend
        (**deprecated**, always unset)

      * **ntor_onion_key** (*str*) -- base64 key used to encrypt
        EXTEND in the ntor protocol

      * **or_addresses** (*list*) -- ***** alternative for our
        address/or_port attributes, each entry is a tuple of the form
        (address (**str**), port (**int**), is_ipv6 (**bool**))

      * **protocols** (*dict*) -- mapping of protocols to their
        supported versions

   **Deprecated**, moved to extra-info descriptor...

   Variables:
      * **read_history_end** (*datetime*) -- end of the sampling
        interval

      * **read_history_interval** (*int*) -- seconds per interval

      * **read_history_values** (*list*) -- bytes read during each
        interval

      * **write_history_end** (*datetime*) -- end of the sampling
        interval

      * **write_history_interval** (*int*) -- seconds per interval

      * **write_history_values** (*list*) -- bytes written during each
        interval

   ***** 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.5.0: Added the allow_tunneled_dir_requests
   attribute.

   Changed in version 1.6.0: Added the extra_info_sha256_digest,
   protocols, and bridge_distribution attributes.

   Changed in version 1.7.0: Added the is_hidden_service_dir
   attribute.

   Changed in version 1.7.0: Deprecated the hidden_service_dir field,
   it's never been populated (spec). This field will be removed in
   Stem 2.0.

   digest()

      Provides the hex encoded sha1 of our content. This value is part
      of the network status entry for this relay.

      Returns:
         **unicode** with the upper-case hex digest value for this
         server descriptor

   get_annotations(*args, **kwds)

      Provides content that appeared prior to the descriptor. If this
      comes from the cached-descriptors file then this commonly
      contains content like...

         @downloaded-at 2012-03-18 21:18:29
         @source "173.254.216.66"

      Returns:
         **dict** with the key/value pairs in our annotations

   get_annotation_lines()

      Provides the lines of content that appeared prior to the
      descriptor. This is the same as the "get_annotations()" results,
      but with the unparsed lines and ordering retained.

      Returns:
         **list** with the lines of annotation that came before this
         descriptor

class class stem.descriptor.server_descriptor.RelayDescriptor(raw_contents, validate=False, annotations=None, skip_crypto_validation=False)

   Bases: "stem.descriptor.server_descriptor.ServerDescriptor"

   Server descriptor (descriptor specification)

   Variables:
      * **certificate** (*stem.certificate.Ed25519Certificate*) --
        ed25519 certificate

      * **ed25519_certificate** (*str*) -- base64 encoded ed25519
        certificate

      * **ed25519_master_key** (*str*) -- base64 encoded master key
        for our ed25519 certificate

      * **ed25519_signature** (*str*) -- signature of this document
        using ed25519

      * **onion_key** (*str*) -- ***** key used to encrypt EXTEND
        cells

      * **onion_key_crosscert** (*str*) -- signature generated using
        the onion_key

      * **ntor_onion_key_crosscert** (*str*) -- signature generated
        using the ntor-onion-key

      * **ntor_onion_key_crosscert_sign** (*str*) -- sign of the
        corresponding ed25519 public key

      * **signing_key** (*str*) -- ***** relay's long-term identity
        key

      * **signature** (*str*) -- ***** signature for this descriptor

   ***** attribute is required when we're parsed with validation

   Changed in version 1.5.0: Added the ed25519_certificate,
   ed25519_master_key, ed25519_signature, onion_key_crosscert,
   ntor_onion_key_crosscert, and ntor_onion_key_crosscert_sign
   attributes.

   Changed in version 1.6.0: Moved from the deprecated pycrypto module
   to cryptography for validating signatures.

   Changed in version 1.6.0: Added the certificate attribute.

   Deprecated since version 1.6.0: Our **ed25519_certificate** is
   deprecated in favor of our new **certificate** attribute. The
   base64 encoded certificate is available via the certificate's
   **encoded** attribute.

   Changed in version 1.6.0: Added the **skip_crypto_validation**
   constructor argument.

   classmethod content(attr=None, exclude=(), sign=False, signing_key=None)

   classmethod create(attr=None, exclude=(), validate=True, sign=False, signing_key=None)

   digest(*args, **kwds)

      Provides the digest of our descriptor's content.

      Returns:
         the digest string encoded in uppercase hex

      Raises :
         ValueError if the digest cannot be calculated

   make_router_status_entry()

      Provides a RouterStatusEntryV3 for this descriptor content.

      New in version 1.6.0.

      Returns:
         "RouterStatusEntryV3" that would be in the consensus

class class stem.descriptor.server_descriptor.BridgeDescriptor(raw_contents, validate=False, annotations=None)

   Bases: "stem.descriptor.server_descriptor.ServerDescriptor"

   Bridge descriptor (bridge descriptor specification)

   Variables:
      * **ed25519_certificate_hash** (*str*) -- sha256 hash of the
        original identity-ed25519

      * **router_digest_sha256** (*str*) -- sha256 digest of this
        document

   Changed in version 1.5.0: Added the ed25519_certificate_hash and
   router_digest_sha256 attributes. Also added ntor_onion_key
   (previously this only belonged to unsanitized descriptors).

   classmethod content(attr=None, exclude=(), sign=False)

   digest()

   is_scrubbed()

      Checks if we've been properly scrubbed in accordance with the
      bridge descriptor specification. Validation is a moving target
      so this may not be fully up to date.

      Returns:
         **True** if we're scrubbed, **False** otherwise

   get_scrubbing_issues(*args, **kwds)

      Provides issues with our scrubbing.

      Returns:
         **list** of strings which describe issues we have with our
         scrubbing, this list is empty if we're properly scrubbed
