proposals/104-short-descriptors.txt

   1 Filename: 104-short-descriptors.txt
   2 Title: Long and Short Router Descriptors
   3 Version: $Revision$
   4 Last-Modified: $Date$
   5 Author: Nick Mathewson
   6 Created:
   7 Status: Closed
   8 Implemented-In: 0.2.0.x
   9
  10 Overview:
  11
  12   This document proposes moving unused-by-clients information from regular
  13   router descriptors into a new "extra info" router descriptor.
  14
  15 Proposal:
  16
  17   Some of the costliest fields in the current directory protocol are ones
  18   that no client actually uses.  In particular, the "read-history" and
  19   "write-history" fields are used only by the authorities for monitoring the
  20   status of the network.  If we took them out, the size of a compressed list
  21   of all the routers would fall by about 60%.  (No other disposable field
  22   would save much more than 2%.)
  23
  24   We propose to remove these fields from descriptors, and and have them
  25   uploaded as a part of a separate signed "extra info" to the authorities.
  26   This document will be signed.  A hash of this document will be included in
  27   the regular descriptors.
  28
  29   (We considered another design, where routers would generate and upload a
  30   short-form and a long-form descriptor.  Only the short-form descriptor would
  31   ever be used by anybody for routing.  The long-form descriptor would be
  32   used only for analytics and other tools.   We decided against this because
  33   well-behaved tools would need to download short-form descriptors too (as
  34   these would be the only ones indexed), and hence get redundant info. Badly
  35   behaved tools would download only long-form descriptors, and expose
  36   themselves to partitioning attacks.)
  37
  38 Other disposable fields:
  39
  40   Clients don't need these fields, but removing them doesn't help bandwidth
  41   enough to be worthwhile.
  42     contact (save about 1%)
  43     fingerprint (save about 3%)
  44
  45   We could represent these fields more succinctly, but removing them would
  46   only save 1%.  (!)
  47     reject
  48     accept
  49   (Apparently, exit polices are highly compressible.)
  50
  51   [Does size-on-disk matter to anybody? Some clients and servers don't
  52    have much disk, or have really slow disk (e.g. USB). And we don't
  53    store caches compressed right now. -RD]
  54
  55 Specification:
  56
  57   1. Extra Info Format.
  58
  59     An "extra info" descriptor contains the following fields:
  60
  61     "extra-info" Nickname Fingerprint
  62         Identifies what router this is an extra info descriptor for.
  63         Fingerprint is encoded in hex (using upper-case letters), with
  64         no spaces.
  65
  66     "published" As currently documented in dir-spec.txt.  It MUST match the
  67         "published" field of the descriptor published at the same time.
  68
  69     "read-history"
  70     "write-history"
  71         As currently documented in dir-spec.txt.  Optional.
  72
  73     "router-signature" NL Signature NL
  74
  75         A signature of the PKCS1-padded hash of the entire extra info
  76         document, taken from the beginning of the "extra-info" line, through
  77         the newline after the "router-signature" line.  An extra info
  78         document is not valid unless the signature is performed with the
  79         identity key whose digest matches FINGERPRINT.
  80
  81     The "extra-info" field is required and MUST appear first.  The
  82     router-signature field is required and MUST appear last.  All others are
  83     optional.  As for other documents, unrecognized fields must be ignored.
  84
  85   2. Existing formats
  86
  87      Implementations that use "read-history" and "write-history" SHOULD
  88      continue accepting router descriptors that contain them.  (Prior to
  89      0.2.0.x, this information was encoded in ordinary router descriptors;
  90      in any case they have always been listed as opt, so they should be
  91      accepted anyway.)
  92
  93      Add these fields to router descriptors:
  94
  95        "extra-info-digest" Digest
  96           "Digest" is a hex-encoded digest (using upper-case characters)
  97           of the router's extra-info document, as signed in the router's
  98           extra-info.  (If this field is absent, no extra-info-digest
  99           exists.)
 100
 101        "caches-extra-info"
 102           Present if this router is a directory cache that provides
 103           extra-info documents, or an authority that handles extra-info
 104           documents.
 105
 106      (Since implementations before 0.1.2.5-alpha required that the "opt"
 107      keyword precede any unrecognized entry, these keys MUST be preceded
 108      with "opt" until 0.1.2.5-alpha is obsolete.)
 109
 110   3. New communications rules
 111
 112      Servers SHOULD generate and upload one extra-info document after each
 113      descriptor they generate and upload; no more, no less.  Servers MUST
 114      upload the new descriptor before they upload the new extra-info.
 115
 116      Authorities receiving an extra-info document SHOULD verify all of the
 117      following:
 118        * They have a router descriptor for some server with a matching
 119          nickname and identity fingerprint.
 120        * That server's identity key has been used to sign the extra-info
 121          document.
 122        * The extra-info-digest field in the router descriptor matches
 123          the digest of the extra-info document.
 124        * The published fields in the two documents match.
 125
 126      Authorities SHOULD drop extra-info documents that do not meet these
 127      criteria.
 128
 129      Extra-info documents MAY be uploaded as part of the same HTTP post as
 130      the router descriptor, or separately.  Authorities MUST accept both
 131      methods.
 132
 133      Authorities SHOULD try to fetch extra-info documents from one another if
 134      they do not have one matching the digest declared in a router
 135      descriptor.
 136
 137      Caches that are running locally with a tool that needs to use extra-info
 138      documents MAY download and store extra-info documents.  They should do
 139      so when they notice that the recommended descriptor has an
 140      extra-info-digest not matching any extra-info document they currently
 141      have.  (Caches not running on a host that needs to use extra-info
 142      documents SHOULD NOT download or cache them.)
 143
 144   4. New URLs
 145
 146      http://<hostname>/tor/extra/d/...
 147      http://<hostname>/tor/extra/fp/...
 148      http://<hostname>/tor/extra/all[.z]
 149         (As for /tor/server/ URLs: supports fetching extra-info documents
 150         by their digest, by the fingerprint of their servers, or all
 151         at once. When serving by fingerprint, we serve the extra-info
 152         that corresponds to the descriptor we would serve by that
 153         fingerprint. Only directory authorities are guaranteed to support
 154         these URLs.)
 155
 156      http://<hostname>/tor/extra/authority[.z]
 157         (The extra-info document for this router.)
 158
 159      Extra-info documents are uploaded to the same URLs as regular
 160      router descriptors.
 161
 162 Migration:
 163
 164   For extra info approach:
 165      * First:
 166        * Authorities should accept extra info, and support serving it.
 167        * Routers should upload extra info once authorities accept it.
 168        * Caches should support an option to download and cache it, once
 169          authorities serve it.
 170        * Tools should be updated to use locally cached information.
 171          These tools include:
 172            lefkada's exit.py script.
 173            tor26's noreply script and general directory cache.
 174            https://nighteffect.us/tns/ for its graphs
 175            and check with or-talk for the rest, once it's time.
 176
 177      * Set a cutoff time for including bandwidth in router descriptors, so
 178        that tools that use bandwidth info know that they will need to fetch
 179        extra info documents.
 180
 181      * Once tools that want bandwidth info support fetching extra info:
 182        * Have routers stop including bandwidth info in their router
 183          descriptors.