proposals/104-short-descriptors.txt

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