attic/text_formats/dir-list-spec.txt

   1
   2                         Tor Directory List Format
   3                          Tim Wilson-Brown (teor)
   4
   5 Table of Contents
   6
   7     1. Scope and Preliminaries
   8         1.1. Format Overview
   9         1.2. Acknowledgements
  10         1.3. Format Versions
  11         1.4. Future Plans
  12     2. Format Details
  13         2.1. Nonterminals
  14         2.2. List Header
  15             2.2.1. List Header Format
  16         2.3. List Generation
  17             2.3.1. List Generation Format
  18         2.4. Directory Entry
  19             2.4.1. Directory Entry Format
  20     3. Usage Considerations
  21         3.1. Caching
  22         3.2. Retrieving Directory Information
  23         3.3. Fallback Reliability
  24     A.1. Sample Data
  25         A.1.1. Sample Fallback List Header
  26         A.1.2. Sample Fallback List Generation
  27         A.1.3. Sample Fallback Entries
  28
  29 1. Scope and Preliminaries
  30
  31    This document describes the format of Tor's directory lists, which are
  32    compiled and hard-coded into the tor binary. There is currently one
  33    list: the fallback directory mirrors. This list is also parsed by other
  34    libraries, like stem and metrics-lib. Alternate Tor implementations can
  35    use this list to bootstrap from the latest public Tor directory
  36    information.
  37
  38    The FallbackDir feature was introduced by proposal 210, and was first
  39    supported by Tor in Tor version 0.2.4.7-alpha. The first hard-coded
  40    list was shipped in 0.2.8.1-alpha.
  41
  42    The hard-coded fallback directory list is located in the tor source
  43    repository at:
  44
  45        src/app/config/fallback_dirs.inc
  46
  47    In Tor 0.3.4 and earlier, the list is located at:
  48
  49        src/or/fallback_dirs.inc
  50
  51    This document describes version 2.0.0 and later of the directory list
  52    format.
  53
  54    Legacy, semi-structured versions of the fallback list were released with
  55    Tor 0.2.8.1-alpha through Tor 0.3.1.9. We call this format version 1.
  56    Stem and Relay Search have parsers for this legacy format.
  57
  58 1.1. Format Overview
  59
  60    A directory list is a C code fragment containing an array of C string
  61    constants. Each double-quoted C string constant is a valid torrc
  62    FallbackDir entry. Each entry contains various data fields.
  63
  64    Directory lists do not include the C array's declaration, or the array's
  65    terminating NULL. Entries in directory lists do not include the
  66    FallbackDir torrc option. These are handled by the including C code.
  67
  68    Directory lists also include C-style comments and whitespace. The
  69    presence of whitespace may be significant, but the amount of whitespace
  70    is never significant. The type of whitespace is not significant to the
  71    C compiler or Tor C string parser. However, other parsers MAY rely on
  72    the distinction between newlines and spaces. (And that the only
  73    whitespace characters in the list are newlines and spaces.)
  74
  75    The directory entry C string constants are split over multiple lines for
  76    readability. Structured C-style comments are used to provide additional
  77    data fields. This information is not used by Tor, but may be of interest
  78    to other libraries.
  79
  80    The order of directory entries and data fields is not significant,
  81    except where noted below.
  82
  83 1.2. Acknowledgements
  84
  85    The original fallback directory script and format was created by
  86    weasel. The current script uses code written by gsathya & karsten.
  87
  88    This specification was revised after feedback from:
  89
  90      Damian Johnson ("atagar")
  91      Iain R. Learmonth ("irl")
  92
  93 1.3. Format Versions
  94
  95    The directory list format uses semantic versioning: https://semver.org
  96
  97    In particular:
  98      * major versions are used for incompatible changes, like
  99        removing non-optional fields
 100      * minor versions are used for compatible changes, like adding
 101        fields
 102      * patch versions are for bug fixes, like fixing an
 103        incorrectly-formatted Summary item
 104
 105    1.0.0 - The legacy fallback directory list format
 106
 107    2.0.0 - Adds name and extrainfo structured comments, and section separator
 108            comments to make the list easier to parses. Also adds a source list
 109            comment to the header.
 110
 111    3.0.0 - Modifies the format of the source list comment.
 112
 113 1.4. Future Plans
 114
 115    Tor also has an auth_dirs.inc file, but it is not yet in this format.
 116    Tor uses slightly different formats for authorities and fallback
 117    directory mirrors, so we will need to make some changes to tor so that
 118    it parses this format. (We will also need to add authority-specific
 119    information to this format.) See #24818 for details.
 120
 121    We want to add a torrc option so operators can opt-in their relays as
 122    fallback directory mirrors. This gives us a signed opt-in confirmation.
 123    (We can also continue to accept whitelist entries, and do other checks.)
 124    We need to write a short proposal, and make some changes to tor and the
 125    fallback update script. See #24839 for details.
 126
 127 2. Format Details
 128
 129    Directory lists contain the following sections:
 130
 131      - List Header (exactly once)
 132      - List Generation (exactly once, may be empty)
 133      - Directory Entry (zero or more times)
 134
 135    Each section (or entry) ends with a separator.
 136
 137 2.1. Nonterminals
 138
 139    The following nonterminals are defined in the Onionoo details document
 140    specification:
 141
 142      dir_address
 143      fingerprint
 144      nickname
 145
 146    See https://metrics.torproject.org/onionoo.html#details
 147
 148    The following nonterminals are defined in the "Tor directory protocol"
 149    specification in dir-spec.txt:
 150
 151      Keyword
 152      ArgumentChar
 153      NL      (newline)
 154      SP      (space)
 155      bool    (must not be confused with Onionoo's JSON "boolean")
 156
 157    We derive the following nonterminals from Onionoo and dir-spec.txt:
 158
 159      ipv4_or_port ::= port from an IPv4 or_addresses item
 160
 161        The ipv4_or_port is the port part of an IPv4 address from the
 162        Onionoo or_addresses list.
 163
 164      ipv6_or_address ::= an IPv6 or_addresses item
 165
 166        The ipv6_or_address is an IPv6 address and port from the Onionoo
 167        or_addresses list. The address MAY be in the canonical RFC 5952
 168        IPv6 address format.
 169
 170    A key-value pair:
 171
 172      value ::= Zero or more ArgumentChar, excluding the following strings:
 173                  * a double quotation mark (DQUOTE), and
 174                  * the C comment terminators ("/*" and "*/").
 175
 176                Note that the C++ comment ("//") and equals sign ("=") are
 177                not excluded, because they are reserved for future use in
 178                base64 values.
 179
 180      key_value ::= Keyword "=" value
 181
 182    We also define these additional nonterminals:
 183
 184      number ::= An optional negative sign ("-"), followed by one or more
 185                 numeric characters ([0-9]), with an optional decimal part
 186                 (".", followed by one or more numeric characters).
 187
 188      separator ::= "/*" SP+ "=====" SP+ "*/"
 189
 190 2.2. List Header
 191
 192    The list header consists of a number of key-value pairs, embedded in
 193    C-style comments.
 194
 195 2.2.1. List Header Format
 196
 197      "/*" SP+ "type=" Keyword SP+ "*/" SP* NL
 198
 199        [At start, exactly once.]
 200
 201        The type of directory entries in the list. Parsers SHOULD exit with
 202        an error if this is not the first line of the list, or if the value
 203        is anything other than "fallback".
 204
 205      "/*" SP+ "version=" version_number SP+ "*/" SP* NL
 206
 207        [In second position, exactly once.]
 208
 209        The version of the directory list format.
 210
 211        version_number is a semantic version, see the "Format Versions"
 212        section for details.
 213
 214        Version 1.0.0 represents the undocumented, legacy fallback list
 215        format(s). Version 2.0.0 and later are documented by this
 216        specification.
 217
 218      "/*" SP+ "timestamp=" number SP+ "*/" SP* NL
 219
 220        [Exactly once.]
 221
 222        A positive integer that indicates when this directory list was
 223        generated. This timestamp is guaranteed to increase for every
 224        version 2.0.0 and later directory list.
 225
 226        The current timestamp format is YYYYMMDDHHMMSS, as an integer.
 227
 228      "/*" SP+ "source=" Keyword ("," Keyword)* SP+ "*/" SP* NL
 229
 230        [Zero or one time.]
 231
 232        A list of the sources of the directory entries in the list.
 233
 234        As of version 3.0.0, the possible sources are:
 235          * "offer-list" - the fallback_offer_list file in the fallback-scripts
 236                           repository.
 237          * "descriptor" - one or more signed descriptors, each containing an
 238                           "offer-fallback-dir" line. This feature will be
 239                           implemented in ticket #24839.
 240          * "fallback"   - a fallback_dirs.inc file from a tor repository.
 241                           Used in check_existing mode.
 242
 243        Before #24839 is implemented, the default is "offer-list". During the
 244        transition to signed offers, it will be "descriptor,offer-list".
 245        Afterwards, it will be "descriptor".
 246
 247        In version 2.0.0, only one source name was allowed after "source=",
 248        and the deprecated "whitelist" source name was used instead of
 249        "offer-list".
 250
 251        This line was added in version 2.0.0 of this specification. The format
 252        of this line was modified in version 3.0.0 of this specification.
 253
 254      "/*" SP+ key_value SP+ "*/" SP* NL
 255
 256        [Zero or more times.]
 257
 258        Future releases may include additional header fields. Parsers MUST NOT
 259        rely on the order of these additional fields. Additional header fields
 260        will be accompanied by a minor version increment.
 261
 262      separator SP* NL
 263
 264        The list header ends with the section separator.
 265
 266 2.3. List Generation
 267
 268    The list generation information consists of human-readable prose
 269    describing the content and origin of this directory list. It is contained
 270    in zero or more C-style comments, and may contain multi-line comments and
 271    uncommented C code.
 272
 273    In particular, this section may contain C-style comments that contain
 274    an equals ("=") character. It may also be entirely empty.
 275
 276    Future releases may arbitrarily change the content of this section.
 277    Parsers MUST NOT rely on a version increment when the format changes.
 278
 279 2.3.1. List Generation Format
 280
 281    In general, parsers MUST NOT rely on the format of this section.
 282
 283    Parsers MAY rely on the following details:
 284
 285    The list generation section MUST NOT be a valid directory entry.
 286
 287    The list generation summary MUST end with a section separator:
 288
 289      separator SP* NL
 290
 291    There MUST NOT be any section separators in the list generation
 292    section, other than the terminating section separator.
 293
 294 2.4. Directory Entry
 295
 296    A directory entry consists of a C string constant, and one or more
 297    C-style comments. The C string constant is a valid argument to the
 298    DirAuthority or FallbackDir torrc option. The section also contains
 299    additional key-value fields in C-style comments.
 300
 301    The list of fallback entries does not include the directory
 302    authorities: they are in a separate list. (The Tor implementation combines
 303    these lists after parsing them, and applies the DirAuthorityFallbackRate
 304    to their weights.)
 305
 306 2.4.1. Directory Entry Format
 307
 308      If a directory entry does not conform to this format, the entry SHOULD
 309      be ignored by parsers.
 310
 311      DQUOTE dir_address SP+ "orport=" ipv4_or_port SP+
 312        "id=" fingerprint DQUOTE SP* NL
 313
 314        [At start, exactly once, on a single line.]
 315
 316        This line consists of the following fields:
 317
 318        dir_address
 319
 320          An IPv4 address and DirPort for this directory, as defined by
 321          Onionoo. In this format version, all IPv4 addresses and DirPorts
 322          are guaranteed to be non-zero. (For IPv4 addresses, this means
 323          that they are not equal to "0.0.0.0".)
 324
 325        ipv4_or_port
 326
 327          An IPv4 ORPort for this directory, derived from Onionoo. In this
 328          format version, all IPv4 ORPorts are guaranteed to be non-zero.
 329
 330        fingerprint
 331
 332          The relay fingerprint of this directory, as defined by Onionoo.
 333          All relay fingerprints are guaranteed to have one or more non-zero
 334          digits.
 335
 336      Note:
 337
 338        Each double-quoted C string line that occurs after the first line,
 339        starts with space inside the quotes. This is a requirement of the
 340        Tor implementation.
 341
 342      DQUOTE SP+ "ipv6=" ipv6_or_address DQUOTE SP* NL
 343
 344        [Zero or one time.]
 345
 346        The IPv6 address and ORPort for this directory, as defined by
 347        Onionoo. If present, IPv6 addresses and ORPorts are guaranteed to be
 348        non-zero. (For IPv6 addresses, this means that they are not equal to
 349        "[::]".)
 350
 351      DQUOTE SP+ "weight=" number DQUOTE SP* NL
 352
 353        [Zero or one time.]
 354
 355        A non-negative, real-numbered weight for this directory.
 356        The default fallback weight is 1.0, and the default
 357        DirAuthorityFallbackRate is 1.0 in legacy Tor versions, and 0.1 in
 358        recent Tor versions.
 359
 360        weight was removed in version 2.0.0, but is documented because it
 361        may be of interest to libraries implementing Tor's fallback
 362        behaviour.
 363
 364      DQUOTE SP+ key_value DQUOTE SP* NL
 365
 366        [Zero or more times.]
 367
 368        Future releases may include additional data fields in double-quoted
 369        C string constants. Parsers MUST NOT rely on the order of these
 370        additional fields. Additional data fields will be accompanied by a
 371        minor version increment.
 372
 373      "/*" SP+ "nickname=" nickname* SP+ "*/" SP* NL
 374
 375        [Exactly once.]
 376
 377        The nickname for this directory, as defined by Onionoo. An
 378        empty nickname indicates that the nickname is unknown.
 379
 380        The first fallback list in the 2.0.0 format had nickname lines, but
 381        they were all empty.
 382
 383      "/*" SP+ "extrainfo=" bool SP+ "*/" SP* NL
 384
 385        [Exactly once.]
 386
 387        An integer flag that indicates whether this directory caches
 388        extra-info documents. Set to 1 if the directory claimed that it
 389        cached extra-info documents in its descriptor when the list was
 390        created. 0 indicates that it did not, or its descriptor was not
 391        available.
 392
 393        The first fallback list in the 2.0.0 format had extrainfo lines, but
 394        they were all zero.
 395
 396      "/*" SP+ key_value SP+ "*/" SP* NL
 397
 398        [Zero or more times.]
 399
 400        Future releases may include additional data fields in C-style
 401        comments. Parsers MUST NOT rely on the order of these additional
 402        fields. Additional data fields will be accompanied by a minor version
 403        increment.
 404
 405      separator SP* NL
 406
 407        [Exactly once.]
 408
 409        Each directory entry ends with the section separator.
 410
 411      "," SP* NL
 412
 413        [Exactly once.]
 414
 415        The comma terminates the C string constant. (Multiple C string
 416        constants separated by whitespace or comments are coalesced by
 417        the C compiler.)
 418
 419 3. Usage Considerations
 420
 421    This section contains recommended library behaviours. It does not affect
 422    the format of directory lists.
 423
 424 3.1. Caching
 425
 426    The fallback list typically changes once every 6-12 months. The data in
 427    the list represents the state of the fallback directory entries when the
 428    list was created. Fallbacks can and do change their details over time.
 429
 430    Libraries SHOULD parse and cache the most recent version of these lists
 431    during their build or release processes. Libraries MUST NOT retrieve the
 432    lists by default every time they are deployed or executed.
 433
 434    The latest fallback list can be retrieved from:
 435
 436      https://gitweb.torproject.org/tor.git/plain/src/or/fallback_dirs.inc
 437
 438    Libraries MUST NOT rely on the availability of the server that hosts
 439    these lists.
 440
 441    The list can also be retrieved using:
 442
 443      git clone https://git.torproject.org/tor.git
 444
 445    If you just want the latest list, you may wish to perform a shallow
 446    clone.
 447
 448 3.2. Retrieving Directory Information
 449
 450    Some libraries retrieve directory documents directly from the Tor
 451    Directory Authorities. The directory authorities are designed to support
 452    Tor relay and client bootstrap, and MAY choose to rate-limit library
 453    access. Libraries MAY provide a user-agent in their requests, if they
 454    are not intended to support anonymous operation. (User agents are a
 455    fingerprinting vector.)
 456
 457    Libraries SHOULD consider the potential load on the authorities, and
 458    whether other sources can meet their needs.
 459
 460    Libraries that require high-uptime availability of Tor directory
 461    information should investigate the following options:
 462
 463      * OnionOO: https://metrics.torproject.org/onionoo.html
 464        * Third-party OnionOO mirrors are also available
 465      * CollecTor: https://collector.torproject.org/
 466      * Fallback Directory Mirrors
 467
 468    Onionoo and CollecTor are typically updated every hour on a regular
 469    schedule. Fallbacks update their own directory information at random
 470    intervals, see dir-spec for details.
 471
 472 3.3. Fallback Reliability
 473
 474    The fallback list is typically regenerated when the fallback failure
 475    rate exceeds 25%. Libraries SHOULD NOT rely on any particular fallback
 476    being available, or some proportion of fallbacks being available.
 477
 478    Libraries that use fallbacks MAY wish to query an authority after a
 479    few fallback queries fail. For example, Tor clients try 3-4 fallbacks
 480    before trying an authority.
 481
 482 A.1. Sample Data
 483
 484    A sample version 2.0.0 fallback list is available here:
 485
 486      https://trac.torproject.org/projects/tor/raw-attachment/ticket/22759/fallback_dirs_new_format_version.4.inc
 487
 488    A sample transitional version 2.0.0 fallback list is available here:
 489
 490      https://raw.githubusercontent.com/teor2345/tor/fallback-format-2-v4/src/or/fallback_dirs.inc
 491
 492 A.1.1. Sample Fallback List Header
 493
 494 /* type=fallback */
 495 /* version=2.0.0 */
 496 /* ===== */
 497
 498 A.1.2. Sample Fallback List Generation
 499
 500 /* Whitelist & blacklist excluded 1326 of 1513 candidates. */
 501 /* Checked IPv4 DirPorts served a consensus within 15.0s. */
 502 /*
 503 Final Count: 151 (Eligible 187, Target 392 (1963 * 0.20), Max 200)
 504 Excluded: 36 (Same Operator 27, Failed/Skipped Download 9, Excess 0)
 505 Bandwidth Range: 1.3 - 40.0 MByte/s
 506 */
 507 /*
 508 Onionoo Source: details Date: 2017-05-16 07:00:00 Version: 4.0
 509 URL: https:onionoo.torproject.orgdetails?fields=fingerprint%2Cnickname%2Ccontact%2Clast_changed_address_or_port%2Cconsensus_weight%2Cadvertised_bandwidth%2Cor_addresses%2Cdir_address%2Crecommended_version%2Cflags%2Ceffective_family%2Cplatform&flag=V2Dir&type=relay&last_seen_days=-0&first_seen_days=30-
 510 */
 511 /*
 512 Onionoo Source: uptime Date: 2017-05-16 07:00:00 Version: 4.0
 513 URL: https:onionoo.torproject.orguptime?first_seen_days=30-&flag=V2Dir&type=relay&last_seen_days=-0
 514 */
 515 /* ===== */
 516
 517 A.1.3. Sample Fallback Entries
 518
 519 "176.10.104.240:80 orport=443 id=0111BA9B604669E636FFD5B503F382A4B7AD6E80"
 520 /* nickname=foo */
 521 /* extrainfo=1 */
 522 /* ===== */
 523 ,
 524 "5.9.110.236:9030 orport=9001 id=0756B7CD4DFC8182BE23143FAC0642F515182CEB"
 525 " ipv6=[2a01:4f8:162:51e2::2]:9001"
 526 /* nickname= */
 527 /* extrainfo=0 */
 528 /* ===== */
 529 ,