Ticket #24774: 279-naming-layer-api.txt.patch

File 279-naming-layer-api.txt.patch, 7.4 KB (added by nullius, 22 months ago)

Patch on 279-naming-layer-api.txt (13cbcbc..3ad5b94)

  • proposals/279-naming-layer-api.txt

    diff --git a/proposals/279-naming-layer-api.txt b/proposals/279-naming-layer-api.txt
    index 13cbcbc..3ad5b94 100644
    a b Status: Draft 
    169169
    170170   where <priority> is a positive integer denoting the priority with which this
    171171   name plugin should be consulted. <tld> is a string which restricts the scope
    172    of this plugin to a particular tld.  Finally, <path> is a filesystem path to
     172   of this plugin to a particular tld. It MAY be '*', in restricted
     173   circumstances; see [GLOBALWILDCARD]. Finally, <path> is a filesystem path to
    173174   an executable that speaks the Tor Name System API and can act as an
    174175   intermediary between Tor and the name system.
    175176
    Status: Draft 
    179180       OnionNamePlugin 2 .bit        /usr/local/bin/namecoin-tor-wrapper
    180181       OnionNamePlugin 3 .scallion   /usr/local/bin/community-hosts-file
    181182
    182 2.3.1. Tor name resolution logic
     1832.3.1. Tor name resolution logic [RESLOGIC]
    183184
    184185   When Tor receives a SOCKS request to an address that has a name
    185186   plugin assigned to it, it needs to perform a query for that address
    Status: Draft 
    187188
    188189   If there are multiple name plugins that correspond to the requested
    189190   address, Tor queries all relevant plugins sorted by their priority
    190    value, until one of them returns a successful result. If two plugins
    191    have the same priority value, Tor MUST abort.
     191   value, until one of them either returns a successful result, or returns
     192   either of status code 3 or 5 [STATUSCODES]. If two plugins have the
     193   same priority value, Tor MUST abort.
    192194
    193195   If all plugins fail to successfuly perform the name resolution, Tor SHOULD
    194196   default to using the exit node for name resolution.
    Status: Draft 
    247249
    248250   XXX Should <RESULT> be optional in the case of failure?
    249251
    250 2.5.2. RESOLVED status codes
     2522.5.2. RESOLVED status codes [STATUSCODES]
    251253
    252254   Name plugins can deliver the following status codes:
    253255
    Status: Draft 
    255257
    256258   1 -- Name resolution generic failure.
    257259
    258    2 -- Name tld not recognized.
     260   2 -- Name tld or syntax not recognized.
    259261
    260262   3 -- Name not registered.
    261263
    262264   4 -- Name resolution timeout exceeded.
    263265
     266   5 -- Name invalid.
     267
    264268   XXX add more status codes here as needed
    265269
     270   XXX subdivide status codes by type, as HTTP, SMTP, etc.  Some
     271       failure codes (3, 5) provide a hard-failure which should
     272       break the priority cascade in [RESLOGIC]; cf. SMTP 5yx,
     273       HTTP 4xx.  2 directly implies that Tor should ask elsewhere.
     274       4 indicates it may be permissible to ask again, as SMTP 4yx,
     275       HTTP 5xx.
     276
    2662772.5.3. Further name resolution behavior
    267278
    268279   Tor and name plugins MAY cache name resolution results in memory as
    Status: Draft 
    342353   Name plugins follow the following workflow:
    343354
    344355     1) Tor sets the required environment values and launches the name plugin
    345         as a sub-process (fork()/exec()). See [INITENVVARS].
     356        as a sub-process (fork()/exec()). See [INITENVVARS].  If a plugin is
     357        registered for the tld '*', then Tor MAY sandbox it without network
     358        or filesystem access.  See [GLOBALWILDCARD].
    346359
    347360     2) The name plugin checks its environment, and determines the supported NS
    348361        API versions using the env variable TOR_NS_PROTO_VERSION.
    Status: Draft 
    391404      <KeyWordChar> ::= <any US-ASCII alphanumeric, dash, and underscore>
    392405      <OptArgs> ::= <Args>*
    393406      <Args> ::= <SP> <ArgChar> | <Args> <ArgChar>
    394       <ArgChar> ::= <any US-ASCII character but NUL or NL>
     407      <ArgChar> ::= <any UTF-8 character but NUL or NL>
    395408      <SP> ::= <US-ASCII whitespace symbol (32)>
    396409      <NL> ::= <US-ASCII newline (line feed) character (10)>
    397410
    398411   Tor MUST ignore lines with keywords that it doesn't recognize.
    399412
     413   XXX UTF-8 should only be specified in NAME_STRING.  It MUST be allowed
     414   there, if the "pet name" system is not to be restricted exclusively to
     415   users of American English.  But non-ASCII belongs nowhere else in this
     416   protocol.  Note that Tor MAY send the plugin non-ASCII NAME_STRING
     417   characters, but the plugin MUST never send Tor anything but US-ASCII.
     418
    4004193. Discussion
    401420
    4024213.1. Using second-level domains instead of tld
    Status: Draft 
    415434
    416435   We should consider the concerns here and take the right decision.
    417436
    418 3.2. Name plugins handling all tlds '*'
    419 
    420    In [TORRC], we assigned a single tld to each name plugin.  Should we also
    421    accept catch-all tlds using '*'? I'm afraid that this way a name system
    422    could try to resolve even normal domains like reddit.com .
    423 
    424    Perhaps we trust the name plugin itself, but maybe the name system
    425    network could exploit this? Also, the catch-all tld will probably
    426    cause some engineering complications in this proposal (as it did for PTs).
     4373.2. Name plugins handling all tlds '*' [GLOBALWILDCARD]
     438
     439   A name plugin assigned to a catch-all tld of '*' could inadvertently
     440   attempt to resolve ordinary DNS names; and there are concerns that even
     441   if the plugin be trusted, a name system network may attempt to exploit
     442   misdirected name queries.  Therefore, for plugins designed to be registered
     443   with a global wildcard tld of '*', the Tor process MAY sandbox the plugin
     444   by using operating system features to deny all network and filesystem
     445   access after calling fork(), but before exec().
     446
     447   A plugin designed to accept a '*' tld assignment MUST NOT expect
     448   or require access to the network or filesystem.  Such a plugin MUST
     449   be capable of performing its function while its only means of I/O
     450   are the stdio descriptors it uses to talk to the Tor process itself.
     451
     452   Such an arrangement is not suitable for name system networks or
     453   databases.  However, it is perfectly suited to self-contained
     454   Alternative Name Representations which encode the binary data
     455   for a .onion address using a human-friendly transformation format.
     456   Potential examples include plugins which encode a .onion address as
     457   a mnemonic phrase using natural-language words, or add error-correcting
     458   codes to their representation of an address.  Such representations may
     459   not be in quasi-DNS format, and may not contain a "tld".
     460
     461   XXX  Should the plugin still be permitted to access the provided
     462   TOR_NS_STATE_LOCATION?  On some platforms, this could be accomplished
     463   by leaving the plugin a file descriptor for a directory; however,
     464   that creates the problem of informing the plugin of its descriptor.
     465   Perhaps somehow specify a descriptor number in TOR_NS_STATE_LOCATION
     466   for sandboxed plugins?  See [INITENVVARS].
    427467
    4284683.3. Deployment strategy
    429469
    Status: Draft 
    468508   Yawning, David and me. Thanks to Lunar and indolering for more
    469509   discussion and feedback.
    470510
     511   nullius made technical suggestions for support of self-contained
     512   alternative representations without a tld format, and of non-ASCII languages.
     513
    471514   This research was supported in part by NSF grants CNS-1111539,
    472515   CNS-1314637, CNS-1526306, CNS-1619454, and CNS-1640548.
    473516
    Appendix A.2: Example plugins [PLUGINEXAMPLES] 
    522565   f) OnioNS
    523566
    524567   g) Namecoin/Blockstart
     568
     569   h) A Bech32 plugin for a name encoding with strong error correction and
     570      detection properties.
     571
     572   i) A plugin which reconstructs .onion addresses from mnemonic phrases
     573      made using natural-language words, in various different languages.