path: root/draft-schanzen-r5n.xml

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent" [
<!ENTITY RFC2119 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2782 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2782.xml">
<!ENTITY RFC3629 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3629.xml">
<!ENTITY RFC3686 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3686.xml">
<!ENTITY RFC3826 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3826.xml">
<!ENTITY RFC3912 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3912.xml">
<!ENTITY RFC3986 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC4648 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4648.xml">
<!ENTITY RFC5869 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5869.xml">
<!ENTITY RFC5890 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5890.xml">
<!ENTITY RFC5891 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5891.xml">
<!ENTITY RFC6781 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6781.xml">
<!ENTITY RFC6895 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6895.xml">
<!ENTITY RFC6979 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6979.xml">
<!ENTITY RFC7748 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7748.xml">
<!ENTITY RFC8032 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8032.xml">
<!ENTITY RFC8126 PUBLIC '' "http://xml.resource.org/public/rfc/bibxml/reference.RFC.8126.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes" ?>
<?rfc toc="yes" ?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="info" docName="draft-schanzen-r5n-00" ipr="trust200902" obsoletes="" updates="" submissionType="IETF" xml:lang="en" version="3">
 <!-- xml2rfc v2v3 conversion 2.26.0 -->
 <front>
  <title abbrev="The R5N Distributed Hash Table">
   The R5N Distributed Hash Table
  </title>
  <seriesInfo name="Internet-Draft" value="draft-schanzen-r5n-00"/>
  <author fullname="Martin Schanzenbach" initials="M." surname="Schanzenbach">
   <organization>GNUnet e.V.</organization>
   <address>
    <postal>
     <street>Boltzmannstrasse 3</street>
     <city>Garching</city>
     <code>85748</code>
     <country>DE</country>
    </postal>
    <email>schanzen@gnunet.org</email>
   </address>
  </author>
  <author fullname="Christian Grothoff" initials="C." surname="Grothoff">
   <organization>Berner Fachhochschule</organization>
   <address>
    <postal>
     <street>Hoeheweg 80</street>
     <city>Biel/Bienne</city>
     <code>2501</code>
     <country>CH</country>
    </postal>
    <email>grothoff@gnunet.org</email>
   </address>
  </author>
  <author fullname="Bernd Fix" initials="B." surname="Fix">
   <organization>GNUnet e.V.</organization>
   <address>
    <postal>
     <street>Boltzmannstrasse 3</street>
     <city>Garching</city>
     <code>85748</code>
     <country>DE</country>
    </postal>
    <email>fix@gnunet.org</email>
   </address>
  </author>

  <!-- Meta-data Declarations -->
  <area>General</area>
  <workgroup>Independent Stream</workgroup>
  <keyword>distributed hash tables</keyword>
  <abstract>
   <t>This document contains the R5N DHT technical specification.</t>
  </abstract>
 </front>
 <middle>
   <section anchor="introduction" numbered="true" toc="default">
     <name>Introduction</name>
     <t>
       Distributed Hash Tables (DHTs) are a key data structure for the
       construction of completely decentralized applications.
       DHTs are important because they generally provide a robust and
       efficient means to distribute the storage and retrieval of
       key-value pairs.
     </t>
     <t>
       This document contains the technical specification
       of the R5N DHT <xref target="R5N" />, a secure DHT routing algorithm
       and data structure for decentralized applications.
     </t>
     <t>
       This document defines the normative wire format of peer-to-peer
       messages, routing algorithms, cryptographic routines and security
       considerations for use by implementors.
     </t>
     <t>
       The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
       NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
       "OPTIONAL" in this document are to be interpreted as described
       in <xref target="RFC2119"/>.
     </t>
     <t>

     </t>
   </section>
   <section anchor="connectivity" numbered="true" toc="default">
     <name>Connectivity and addressing</name>
     <t>
       In the DHT overlay, a peer is addressable by its Peer ID.
       The Peer ID is the 256-bit hash of the peer public key.
       The peer public key is the public key of the corresponding
       Ed25519<xref target="ed25519" /> peer private key.
     </t>
     <t>
       In the network underlay, a peer is addressable by traditional
       means out of scope of this document. For example, the peer may
       have a TCP/IP address, or a HTTPS endpoint.
       While the specific addressing options and mechanisms are out of scope
       for this document, it is necessary to define a universal addressing
       format in order to facilitate the distribution of connectivity
       information to other peers in the DHT overlay.
       This format is the "HELLO" message. A "HELLO" is a human-readable
       UTF-8  <xref target="RFC3629" /> string consisting of the peer
       public key and the HELLO URI <xref target="RFC3986" />.
     </t>
       <figure>
         <artwork name="" type="" align="left" alt=""><![CDATA[
hello-format := <peer-public-key> <hello-uri>
peer-public-key := [A-HJ-NP-Z1-9]+
         ]]></artwork>
     </figure>
     <t>
       For the string representation of the peer public key,
       the base-32 encoding "StringEncode" is used.
       However, instead of following <xref target="RFC4648"/> the
       character map is based on the optical character recognition friendly
       proposal of Crockford <xref target="CrockfordB32"/>.
       The only difference to Crockford is that the letter
       "U" decodes to the same base-32 value as the letter "V" (27).
     </t>
     <t>
       The "scheme" part of the HELLO URI defined the addressing scheme
       which is used. An example of an addressing scheme used throughout
       this document is "ip+tcp", which refers to a standard TCP/IP socket
       connection. The "hier"-part of the URI must provide a suitable
       address for the given addressing scheme.
       The following is a non-normative example of a HELLO containing three
       HELLO URIs:
     </t>
       <figure>
         <artwork name="" type="" align="left" alt=""><![CDATA[
Y924NSHMMZ1N1SQCE5TXF93ED6S6JY311K0QT86G9WJC68F6XVZ0 \
        ip+tcp://1.2.3.4:6789 \
        gnunet+tcp://12.3.4.5/ \
        i2p+udp://1.2.4.5:424/ \
        tor+onionv3://rasdflkjasdfliasduf.onion/
         ]]></artwork>
     </figure>
     <!--
       1) The current API is always fire+forget, it doesn't allow for flow
       control. I think we need to add that, possibly for sending and receiving.

       IDK.

2) I'm not sure what to do with the crypto: mandate EdDSA or allow the
       underlay to do whatever public keys it likes.

       We need keys in the overlay. (Path signatures). Do they need to
       be the same keys???

3) I think we may want to mandate that the lower layer at least
authenticate the other peer (i.e. every UDP message could be in
cleartext, but would need to come with an EdDSA signature, alas 92 byte
overhead and a signature verification _required_).  Otherwise, I don't
see how we can offer even the most minimal protections against peer
       impersonation attacks. WDYT?

       Security considerations? Prerequisites?
     -->
     <t>
       It is expected that there are basic mechanisms available to
       manage peer connectivity and addressing.
       The required functionality are abstracted through the following
       procedures and events:
     </t>
     <dl>
       <dt>PEER_CONNECTED(phash,address)</dt>
       <dd>
         is a signal that allows the DHT to react to peers which connect.
         Such an event triggers, for example, updates in the
         routing table.
       </dd>
       <dt>PEER_DISCONNECTED(phash,address)</dt>
       <dd>
         is a signal that allows the DHT to react to peers which disconnect.
         Such an event triggers, for example, updates in the
         routing table.
       </dd>
       <dt>TRY_CONNECT(pid, address)</dt>
       <dd>
         A function which allows a peer to attempt the establishment of
         a connection to another peer using an address.
       </dd>
       <dt>HOLD(pash)</dt>
       <dd>
         A function which tells the underlay to keep a hold on the connection
         to another peer.
       </dd>
       <dt>DROP(pash)</dt>
       <dd>
         A function which tells the underlay to drop the connection to another
         peer.
       </dd>
       <dt>RECEIVE(source, message)</dt>
       <dd>
         A function or event that allows the peer to receive protocol
         messages as defined in this document from a connected peer.
       </dd>
       <dt>SEND(target, message)</dt>
       <dd>
         A function that allows a peer to send protocol messages as defined
         in this document to a connected peer. If call to SEND fails,
         the message has not been sent.
       </dd>
       <dt>NETWORK_SIZE_ESTIMATE(N)</dt>
       <dd>
         A function or event that provides estimates on the network size
         for use in the DHT routing algorithms.
       </dd>
       <dt>ADDRESS_ADD(pk, address)</dt>
       <dd>
         The underlay signals us that an address was added.
         This information is used, for example, to publish
         connectivity as part of the bootstrapping and overlay creation.
       </dd>
       <dt>ADDRESS_DELETE(pk, address)</dt>
       <dd>
         The underlay signals us that an address was removed.
         This information is used, for example, to publish
         connectivity as part of the bootstrapping and overlay creation.
       </dd>
       <dt>VERIFY(blob)</dt>
       <dd>
         Signature verification by underlay.
       </dd>
     </dl>
   </section>
   <section anchor="routing" numbered="true" toc="default">
     <name>Routing</name>
     <section anchor="peer_distance" numbered="true" toc="default">
       <name>Peer distance</name>
     </section>
     <section anchor="peer_selection" numbered="true" toc="default">
       <name>Peer selection</name>
     </section>
   </section>
   <section anchor="p2p_messages" numbered="true" toc="default">
     <name>Peer-to-peer wire formats</name>
      <section anchor="p2p_bf" numbered="true" toc="default">
        <name>Bloomfilter</name>
      </section>
      <section anchor="p2p_opts" numbered="true" toc="default">
        <name>Processing options</name>
      </section>
      <section anchor="p2p_xq" numbered="true" toc="default">
        <name>Extended query</name>
      </section>
     <section anchor="p2p_put" numbered="true" toc="default">
       <name>PUT message</name>
     <figure anchor="figure_putmsg">
       <artwork name="" type="" align="left" alt=""><![CDATA[
0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|  MSIZE    |   MTYPE   |       OPTIONS         |
+-----+-----+-----+-----+-----+-----+-----+-----+
|       BTYPE           |       HOPCOUNT        |
+-----+-----+-----+-----+-----+-----+-----+-----+
|    REPLICATIONLVL     |       PATH_LEN        |
+-----+-----+-----+-----+-----+-----+-----+-----+
|     EXPIRATION        |     BLOOMFILTER       /
+-----+-----+-----+-----+                       /
/                 (128 byte)                    /
/                       +-----+-----+-----+-----+
/                       |       KEY             /
+-----+-----+-----+-----+                       /
/                 (64 byte)                     /
/                       +-----+-----+-----+-----+
/                       |   PUTPATH             /
+-----+-----+-----+-----+                       /
/                 (variable length)             /
+-----+-----+-----+-----+-----+-----+-----+-----+
/              PAYLOAD (variable length)        /
+-----+-----+-----+-----+-----+-----+-----+-----+
         ]]></artwork>
     </figure>
     <t>where:</t>
     <dl>
       <dt>MSIZE</dt>
       <dd>
         denotes the size of this message in network byte order.
       </dd>
       <dt>MTYPE</dt>
       <dd>
         is the 16-bit message type. This type can be one of the DHT message
         types but for put messages it must be set to
         the value 146 in network byte order.
       </dd>
       <dt>OPTIONS</dt>
       <dd>
         is a 32-bit options field (see below).
       </dd>
       <dt>BTYPE</dt>
       <dd>
         is a 32-bit block type field. The block type indicates the content
         type of the payload. In network byte order.
       </dd>
       <dt>HOPCOUNT</dt>
       <dd>
         is a 32-bit number indicating how many hops this message has
         traversed to far. In network byte order.
       </dd>
       <dt>REPLICATIONLVL</dt>
       <dd>
         is a 32-bit number indicating the desired replication level of
         the data. In network byte order.
       </dd>
       <dt>PATH_LEN</dt>
       <dd>
         is a 32-bit number indicating the length of the PUT path recorded
         in PUTPATH. As PUTPATH is optiona, this value may be zero.
         In network byte order.
       </dd>
       <dt>EXPIRATION</dt>
       <dd>
         denotes the absolute 64-bit expiration date of the content.
         In microseconds since midnight (0 hour), January 1, 1970 in network
         byte order.
       </dd>
       <dt>BLOOMFILTER</dt>
       <dd>
         A bloomfilter (for peer identities) to stop circular routes.
       </dd>
       <dt>KEY</dt>
       <dd>
         The key under which the PUT request wants to store content
         under.
       </dd>
       <dt>PUTPATH</dt>
       <dd>
         the variable-length PUT path.
         The path consists of a list of PATH_LEN peer IDs.
       </dd>
       <dt>PAYLOAD</dt>
       <dd>
         the variable-length resource record data payload. The contents are defined
         by the
         respective type of the resource record.
       </dd>
     </dl>

     </section>
     <section anchor="p2p_get" numbered="true" toc="default">
       <name>GET message</name>
     <figure anchor="figure_getmsg">
       <artwork name="" type="" align="left" alt=""><![CDATA[
0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|  MSIZE    |   MTYPE   |       OPTIONS         |
+-----+-----+-----+-----+-----+-----+-----+-----+
|       BTYPE           |       HOPCOUNT        |
+-----+-----+-----+-----+-----+-----+-----+-----+
|    REPLICATIONLVL     |       XQUERY_SIZE     |
+-----+-----+-----+-----+-----+-----+-----+-----+
|     BF_MUTATOR        |     BLOOMFILTER       /
+-----+-----+-----+-----+                       /
/                 (128 byte)                    /
/                       +-----+-----+-----+-----+
/                       |       KEY             /
+-----+-----+-----+-----+                       /
/                 (64 byte)                     /
/                       +-----+-----+-----+-----+
/                       |   XQUERY              /
+-----+-----+-----+-----+                       /
/                 (variable length)             /
+-----+-----+-----+-----+-----+-----+-----+-----+
/              BF_RESULT (variable length)      /
+-----+-----+-----+-----+-----+-----+-----+-----+
         ]]></artwork>
     </figure>
     <t>where:</t>
     <dl>
       <dt>MSIZE</dt>
       <dd>
         denotes the size of this message in network byte order.
       </dd>
       <dt>MTYPE</dt>
       <dd>
         is the 16-bit message type. This type can be one of the DHT message
         types but for put messages it must be set to
         the value 147 in network byte order.
       </dd>
       <dt>OPTIONS</dt>
       <dd>
         is a 32-bit options field (see below).
       </dd>
       <dt>BTYPE</dt>
       <dd>
         is a 32-bit block type field. The block type indicates the content
         type of the payload. In network byte order.
       </dd>
       <dt>HOPCOUNT</dt>
       <dd>
         is a 32-bit number indicating how many hops this message has
         traversed to far. In network byte order.
       </dd>
       <dt>REPLICATIONLVL</dt>
       <dd>
         is a 32-bit number indicating the desired replication level of
         the data. In network byte order.
       </dd>
       <dt>XQUERY_SIZE</dt>
       <dd>
         is a 32-bit number indicating the length of the optional
         extended query XQUERY. In network byte order.
       </dd>
       <dt>BF_MUTATOR</dt>
       <dd>
         The bloomfilter mutator.
       </dd>
       <dt>BLOOMFILTER</dt>
       <dd>
         A bloomfilter (for peer identities) to stop circular routes.
       </dd>
       <dt>KEY</dt>
       <dd>
         The key under which the PUT request wants to store content
         under.
       </dd>
       <dt>XQUERY</dt>
       <dd>
         the variable-length extended query. Optional.
       </dd>
       <dt>BF_RESULT</dt>
       <dd>
         the variable-length result bloomfilter.
       </dd>
     </dl>
     </section>
     <section anchor="p2p_result" numbered="true" toc="default">
       <name>RESULT message</name>
     <figure anchor="figure_resmsg">
       <artwork name="" type="" align="left" alt=""><![CDATA[
0     8     16    24    32    40    48    56
+-----+-----+-----+-----+-----+-----+-----+-----+
|  MSIZE    |   MTYPE   |       OPTIONS         |
+-----+-----+-----+-----+-----+-----+-----+-----+
|       BTYPE           |     PUT_PATH_LEN      |
+-----+-----+-----+-----+-----+-----+-----+-----+
|    GET_PATH_LEN       |       EXPIRATION      |
+-----+-----+-----+-----+-----+-----+-----+-----+
|                      KEY                      /
/                 (64 byte)                     |
+-----+-----+-----+-----+-----+-----+-----+-----+
/                    PUTPATH                    /
/                 (variable length)             /
+-----+-----+-----+-----+-----+-----+-----+-----+
/                    GETPATH                    /
/                 (variable length)             /
+-----+-----+-----+-----+-----+-----+-----+-----+
/                   PAYLOAD                     /
/              (variable length)                /
+-----+-----+-----+-----+-----+-----+-----+-----+
         ]]></artwork>
     </figure>
     <t>where:</t>
     <dl>
       <dt>MSIZE</dt>
       <dd>
         denotes the size of this message in network byte order.
       </dd>
       <dt>MTYPE</dt>
       <dd>
         is the 16-bit message type. This type can be one of the DHT message
         types but for put messages it must be set to
         the value 148 in network byte order.
       </dd>
       <dt>OPTIONS</dt>
       <dd>
         is a 32-bit options field (see below).
       </dd>
       <dt>BTYPE</dt>
       <dd>
         is a 32-bit block type field. The block type indicates the content
         type of the payload. In network byte order.
       </dd>
       <dt>PUT_PATH_LEN</dt>
       <dd>
         is a 32-bit number indicating the length of the PUT path recorded
         in PUTPATH. As PUTPATH is optiona, this value may be zero.
         In network byte order.
       </dd>
       <dt>GET_PATH_LEN</dt>
       <dd>
         is a 32-bit number indicating the length of the GET path recorded
         in GETPATH. As PUTPATH is optiona, this value may be zero.
         In network byte order.
       </dd>
       <dt>EXPIRATION</dt>
       <dd>
         denotes the absolute 64-bit expiration date of the content.
         In microseconds since midnight (0 hour), January 1, 1970 in network
         byte order.
       </dd>
       <dt>KEY</dt>
       <dd>
         The key under which the PUT request wants to store content
         under.
       </dd>
       <dt>PUTPATH</dt>
       <dd>
         the variable-length PUT path.
         The path consists of a list of PATH_LEN peer IDs.
       </dd>
       <dt>GETPATH</dt>
       <dd>
         the variable-length PUT path.
         The path consists of a list of PATH_LEN peer IDs.
       </dd>
       <dt>PAYLOAD</dt>
       <dd>
         the variable-length resource record data payload.
         The contents are defined by the respective type of the resource record.
       </dd>
     </dl>
     </section>
   </section>
   <section anchor="security" numbered="true" toc="default">
       <name>Security Considerations</name>
   </section>
   <section anchor="gana" numbered="true" toc="default">
       <name>GANA Considerations</name>
       <t>
         GANA <xref target="GANA" />
         is requested to create a "DHT Block Types" registry.
         The registry shall record for each entry:
       </t>
       <ul>
         <li>Name: The name of the record type (case-insensitive ASCII
           string, restricted to alphanumeric characters</li>
         <li>Number: 32-bit, above 65535</li>
         <li>Comment: Optionally, a brief English text describing the purpose of
           the record type (in UTF-8)</li>
         <li>Contact: Optionally, the contact information of a person to contact for
           further information</li>
         <li>References: Optionally, references describing the record type
           (such as an RFC)</li>
       </ul>
       <t>
         The registration policy for this sub-registry is "First Come First
         Served", as described in <xref target="RFC8126"/>.
         GANA is requested to populate this registry as follows:
       </t>
       <figure anchor="figure_btypenums">
         <artwork name="" type="" align="left" alt=""><![CDATA[
Number | Name    | Contact | References | Description
-------+---------+---------+------------+-------------------------

           ]]></artwork>
       </figure>
       <t>
         GANA is requested to amend the "GNUnet Signature Purpose" registry
         as follows:
       </t>
       <figure anchor="figure_purposenums">
         <artwork name="" type="" align="left" alt=""><![CDATA[
Purpose | Name            | References | Description
--------+-----------------+------------+--------------------------
           ]]></artwork>
       </figure>
     </section>
     <!-- gana -->
     <section>
       <name>Test Vectors</name>
   </section>
   </middle>
   <back>
     <references>
       <name>Normative References</name>

         &RFC2119;
         &RFC3629;
         &RFC3986;
         &RFC4648;
         &RFC8126;
 
      <reference anchor="ed25519" target="http://link.springer.com/chapter/10.1007/978-3-642-23951-9_9">
         <front>
           <title>High-Speed High-Security Signatures</title>
          <author initials="D." surname="Bernstein" fullname="Daniel Bernstein">
            <organization>University of Illinois at Chicago</organization>
          </author>

          <author initials="N." surname="Duif"
            fullname="Niels Duif">
          <organization>Technische Universiteit Eindhoven</organization>

        </author>
          <author initials="T." surname="Lange"
            fullname="Tanja Lange">
          <organization>Technische Universiteit Eindhoven</organization>

          </author>
          <author initials="P." surname="Schwabe"
            fullname="Peter Schwabe">
          <organization>National Taiwan University</organization>

          </author>
          <author initials="B." surname="Yang"
            fullname="Bo-Yin Yang">
          <organization>Academia Sinica</organization>

          </author>
           <date year="2011"/>
         </front>
       </reference>

       <reference anchor="CrockfordB32" target="https://www.crockford.com/base32.html">
         <front>
           <title>Base32</title>
          <author initials="D." surname="Douglas" fullname="Crockford">
          </author>

           <date year="2019" month="March"/>
         </front>
       </reference>

       <reference anchor="GANA" target="https://gana.gnunet.org/">
         <front>
           <title>GNUnet Assigned Numbers Authority (GANA)</title>
           <author><organization>GNUnet e.V.</organization>
           </author>
           <date month="April" year="2020" />
         </front>
       </reference>
      <reference anchor="R5N" target="https://doi.org/10.1109/ICNSS.2011.6060022">
         <front>
           <title>R5N: Randomized recursive routing for restricted-route networks</title>
          <author initials="N. S." surname="Evans" fullname="Nathan S. Evans">
            <organization>Technische Universität München</organization>
          </author>

          <author initials="C." surname="Grothoff"
            fullname="Christian Grothoff">
          <organization>Technische Universität München</organization>
          </author>
           <date year="2011"/>
         </front>
       </reference>



     </references>
     <!-- Change Log
       v00 2017-07-23  MS   Initial version
     -->
   </back>
 </rfc>