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 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="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 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>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 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>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;
       &RFC8126;

       <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>