<p>This is a proposal for an extension to the BitTorrent DHT to allow
storing and retrieving of arbitrary data.</p>
<p>It supports both storing <em>immutable</em> items, where the key is
the SHA-1 hash of the data itself, and <em>mutable</em> items, where
the key is the public key of the key pair used to sign the data.</p>
<p>There are two new proposed messages, <ttclass="docutils literal"><spanclass="pre">put</span></tt> and <ttclass="docutils literal"><spanclass="pre">get</span></tt>.</p>
<divclass="section"id="terminology">
<h1>terminology</h1>
<p>In this document, a <em>storage node</em> refers to the node in the DHT to which
an item is being announced and stored on. A <em>subscribing node</em> refers to
a node which makes look-ups in the DHT to find the storage nodes, to
request items from them, and possibly re-announce those items to keep them
alive.</p>
</div>
<divclass="section"id="messages">
<h1>messages</h1>
<p>The proposed new messages <ttclass="docutils literal"><spanclass="pre">get</span></tt> and <ttclass="docutils literal"><spanclass="pre">put</span></tt> are similar to the existing <ttclass="docutils literal"><spanclass="pre">get_peers</span></tt>
and <ttclass="docutils literal"><spanclass="pre">announce_peer</span></tt>.</p>
<p>Responses to <ttclass="docutils literal"><spanclass="pre">get</span></tt> should always include <ttclass="docutils literal"><spanclass="pre">nodes</span></tt> and <ttclass="docutils literal"><spanclass="pre">nodes6</span></tt> has the same
semantics as in its <ttclass="docutils literal"><spanclass="pre">get_peers</span></tt> response. It should also include a write token,
<ttclass="docutils literal"><spanclass="pre">token</span></tt>, with the same semantics as <ttclass="docutils literal"><spanclass="pre">get_peers</span></tt>.</p>
<p>The <ttclass="docutils literal"><spanclass="pre">id</span></tt> field in these messages has the same semantics as the standard DHT messages,
i.e. the node ID of the node sending the message, to maintain the structure of the DHT
network.</p>
<p>The <ttclass="docutils literal"><spanclass="pre">token</span></tt> field also has the same semantics as the standard DHT message <ttclass="docutils literal"><spanclass="pre">get_peers</span></tt>
and <ttclass="docutils literal"><spanclass="pre">announce_peer</span></tt>, when requesting an item and to write an item respectively.</p>
<p>The distinction between storing mutable and immutable items is the inclusion
of a public key, a sequence number and signature (<ttclass="docutils literal"><spanclass="pre">k</span></tt>, <ttclass="docutils literal"><spanclass="pre">seq</span></tt> and <ttclass="docutils literal"><spanclass="pre">sig</span></tt>).
The distinction betwewn retrieving a mutable and immutable item is the inclusion of
the public key spill-over (<ttclass="docutils literal"><spanclass="pre">k</span></tt>) in the <ttclass="docutils literal"><spanclass="pre">get</span></tt> request.</p>
<p>The <ttclass="docutils literal"><spanclass="pre">v</span></tt> key is the <em>value</em> to be stored. It is allowed to be any bencoded type (list,
dict, string or integer). When it's being hashed (for verifying its signature or to calculate
its key), its flattened, bencoded, form is used.</p>
<p>Storing nodes are SHOULD reject <ttclass="docutils literal"><spanclass="pre">put</span></tt> requests where the bencoded form of <ttclass="docutils literal"><spanclass="pre">v</span></tt> is longer
than 767 bytes.</p>
</div>
<divclass="section"id="immutable-items">
<h1>immutable items</h1>
<p>Immutable items are stored under their SHA-1 hash, and since they cannot be modified,
there is no need to authenticate the origin of them. This makes immutable items simple.</p>
<divclass="section"id="put-message">
<h2>put message</h2>
<p>Request:</p>
<preclass="literal-block">
{
"a":
{
"id": <em><20 byte id of sending node (string)></em>,
"v": <em><any bencoded type whose SHA-1 hash matches 'target'></em>,
"nodes": <em><IPv4 nodes close to 'target'></em>
"nodes6": <em><IPv6 nodes close to 'target'></em>
},
"t": <em><transaction-id></em>,
"y": "r",
}
</pre>
</div>
</div>
<divclass="section"id="mutable-items">
<h1>mutable items</h1>
<p>Mutable items can be updated, without changing their DHT keys. To authenticate
that only the original publisher can update an item, it is signed by a private key
generated by the original publisher.</p>
<p>In order to avoid a malicious node to overwrite the list head with an old
version, the sequence number <ttclass="docutils literal"><spanclass="pre">seq</span></tt> must be monotonically increasing for each update,
and a node hosting the list node MUST not downgrade a list head from a higher sequence
number to a lower one, only upgrade.</p>
<p>The signature is a 2048 bit RSA signature of the SHA-1 hash of the bencoded sequence
number and <ttclass="docutils literal"><spanclass="pre">v</span></tt> key. e.g. something like this:: <ttclass="docutils literal"><spanclass="pre">3:seqi4e1:v12:Hello</span><spanclass="pre">world!</span></tt>.</p>
<divclass="section"id="id1">
<h2>put message</h2>
<p>Request:</p>
<preclass="literal-block">
{
"a":
{
"id": <em><20 byte id of sending node (string)></em>,
"k": <em><RSA-2048 public key (268 bytes string)></em>,
"seq": <em><monotonically increasing sequence number (integer)></em>,
<p>Storing nodes receiving a <ttclass="docutils literal"><spanclass="pre">put</span></tt> request where <ttclass="docutils literal"><spanclass="pre">seq</span></tt> is lower than what's already
stored on the node, MUST reject the request.</p>
<p>Response:</p>
<preclass="literal-block">
{
"r": { "id": <em><20 byte id of sending node (string)></em> },
