331 lines
11 KiB
ReStructuredText
331 lines
11 KiB
ReStructuredText
============================================
|
|
BitTorrent extension for arbitrary DHT store
|
|
============================================
|
|
|
|
:Author: Arvid Norberg, arvid@rasterbar.com
|
|
:Version: 1.0.0
|
|
|
|
.. contents:: Table of contents
|
|
:depth: 2
|
|
:backlinks: none
|
|
|
|
This is a proposal for an extension to the BitTorrent DHT to allow
|
|
storing and retrieving of arbitrary data.
|
|
|
|
It supports both storing *immutable* items, where the key is
|
|
the SHA-1 hash of the data itself, and *mutable* items, where
|
|
the key is the public key of the key pair used to sign the data.
|
|
|
|
There are two new proposed messages, ``put`` and ``get``.
|
|
|
|
terminology
|
|
-----------
|
|
|
|
In this document, a *storage node* refers to the node in the DHT to which
|
|
an item is being announced and stored on. A *requesting node* 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.
|
|
|
|
messages
|
|
--------
|
|
|
|
The proposed new messages ``get`` and ``put`` are similar to the existing ``get_peers``
|
|
and ``announce_peer``.
|
|
|
|
Responses to ``get`` should always include ``nodes`` and ``nodes6``. Those fields
|
|
have the same semantics as in its ``get_peers`` response. It should also include a write token,
|
|
``token``, with the same semantics as int ``get_peers``. The write token MAY be tied
|
|
specifically to the key which ``get`` requested. i.e. the ``token`` can only be used
|
|
to store values under that one key.
|
|
|
|
The ``id`` 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.
|
|
|
|
The ``token`` field also has the same semantics as the standard DHT message ``get_peers``
|
|
and ``announce_peer``, when requesting an item and to write an item respectively.
|
|
|
|
The ``k`` field is the 32 byte ed25519 public key, which the signature
|
|
can be authenticated with. When looking up a mutable item, the ``target`` field
|
|
MUST be the SHA-1 hash of this key.
|
|
|
|
The distinction between storing mutable and immutable items is the inclusion
|
|
of a public key, a sequence number and signature (``k``, ``seq`` and ``sig``).
|
|
|
|
``get`` requests for mutable items and immutable items cannot be distinguished from
|
|
eachother. An implementation can either store mutable and immutable items in the same
|
|
hash table internally, or in separate ones and potentially do two lookups for ``get``
|
|
requests.
|
|
|
|
The ``v`` field is the *value* 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. It is important to use the exact
|
|
bencoded representation as it appeared in the message. decoding and then re-encoding
|
|
bencoded structures is not necessarily an identity operation.
|
|
|
|
Storing nodes SHOULD reject ``put`` requests where the bencoded form of ``v`` is longer
|
|
than 1000 bytes.
|
|
|
|
immutable items
|
|
---------------
|
|
|
|
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.
|
|
|
|
A node making a lookup SHOULD verify the data it receives from the network, to verify
|
|
that its hash matches the target that was looked up.
|
|
|
|
put message
|
|
...........
|
|
|
|
Request:
|
|
|
|
.. parsed-literal::
|
|
|
|
{
|
|
"a":
|
|
{
|
|
"id": *<20 byte id of sending node (string)>*,
|
|
"v": *<any bencoded type, whose encoded size <= 1000>*
|
|
},
|
|
"t": *<transaction-id (string)>*,
|
|
"y": "q",
|
|
"q": "put"
|
|
}
|
|
|
|
Response:
|
|
|
|
.. parsed-literal::
|
|
|
|
{
|
|
"r": { "id": *<20 byte id of sending node (string)>* },
|
|
"t": *<transaction-id (string)>*,
|
|
"y": "r",
|
|
}
|
|
|
|
get message
|
|
...........
|
|
|
|
Request:
|
|
|
|
.. parsed-literal::
|
|
|
|
{
|
|
"a":
|
|
{
|
|
"id": *<20 byte id of sending node (string)>*,
|
|
"target": *<SHA-1 hash of item (string)>*,
|
|
},
|
|
"t": *<transaction-id (string)>*,
|
|
"y": "q",
|
|
"q": "get"
|
|
}
|
|
|
|
Response:
|
|
|
|
.. parsed-literal::
|
|
|
|
{
|
|
"r":
|
|
{
|
|
"id": *<20 byte id of sending node (string)>*,
|
|
"token": *<write token (string)>*,
|
|
"v": *<any bencoded type whose SHA-1 hash matches 'target'>*,
|
|
"nodes": *<IPv4 nodes close to 'target'>*,
|
|
"nodes6": *<IPv6 nodes close to 'target'>*
|
|
},
|
|
"t": *<transaction-id>*,
|
|
"y": "r",
|
|
}
|
|
|
|
|
|
mutable items
|
|
-------------
|
|
|
|
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. The target ID mutable items are stored under
|
|
is the SHA-1 hash of the public key (as it appears in the ``put`` message).
|
|
|
|
In order to avoid a malicious node to overwrite the list head with an old
|
|
version, the sequence number ``seq`` 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. The sequence number SHOULD not exceed ``MAX_INT64``,
|
|
(i.e. ``0x7fffffffffffffff``. A client MAY reject any message with a sequence number
|
|
exceeding this.
|
|
|
|
The signature is a 64 byte ed25519 signature of the bencoded sequence
|
|
number concatenated with the ``v`` key. e.g. something like this:: ``3:seqi4e1:v12:Hello world!``.
|
|
|
|
put message
|
|
...........
|
|
|
|
Request:
|
|
|
|
.. parsed-literal::
|
|
|
|
{
|
|
"a":
|
|
{
|
|
"cas": *<optional 20 byte hash (string)>*,
|
|
"id": *<20 byte id of sending node (string)>*,
|
|
"k": *<ed25519 public key (32 bytes string)>*,
|
|
"seq": *<monotonically increasing sequence number (integer)>*,
|
|
"sig": *<ed25519 signature (64 bytes string)>*,
|
|
"token": *<write-token (string)>*,
|
|
"v": *<any bencoded type, whose encoded size < 1000>*
|
|
},
|
|
"t": *<transaction-id (string)>*,
|
|
"y": "q",
|
|
"q": "put"
|
|
}
|
|
|
|
Storing nodes receiving a ``put`` request where ``seq`` is lower than or equal
|
|
to what's already stored on the node, MUST reject the request. If the sequence
|
|
number is equal, and the value is also the same, the node SHOULD reset its timeout
|
|
counter.
|
|
|
|
If the sequence number in the ``put`` message is lower than the sequence number
|
|
associated with the currently stored value, the storing node MAY return an error
|
|
message with code 302 (see error codes below).
|
|
|
|
Note that this request does not contain a target hash. The target hash under
|
|
which this blob is stored is implied by the ``k`` argument. The key is
|
|
the SHA-1 hash of the key (``k``).
|
|
|
|
The ``cas`` field is optional. If present it is interpreted of the sha-1 hash of
|
|
the sequence number and ``v`` field that is expected to be replaced. The buffer
|
|
to hash is the same as the one signed when storing. ``cas`` is short for *compare
|
|
and swap*, it has similar semantics as CAS CPU instructions. If specified as part
|
|
of the put command, and the current value stored under the public key differs from
|
|
the expected value, the store fails. The ``cas`` field only applies to mutable puts.
|
|
|
|
Response:
|
|
|
|
.. parsed-literal::
|
|
|
|
{
|
|
"r": { "id": *<20 byte id of sending node (string)>* },
|
|
"t": *<transaction-id (string)>*,
|
|
"y": "r",
|
|
}
|
|
|
|
If the store fails for any reason an error message is returned instead of the message
|
|
template above, i.e. one where "y" is "e" and "e" is a tuple of [error-code, message]).
|
|
Failures include where the ``cas`` hash mismatches and the sequence number is outdated.
|
|
|
|
If no ``cas`` field is included in the ``put`` message, the value of the current ``v``
|
|
field should be disregarded when determining whether or not to save the item.
|
|
|
|
The error message (as specified by BEP5_) looks like this:
|
|
|
|
.. _BEP5: http://www.bittorrent.org/beps/bep_0005.html
|
|
|
|
.. parsed-literal::
|
|
|
|
{
|
|
"e": [ *<error-code (integer)>*, *<error-string (string)>* ],
|
|
"t": *<transaction-id (string)>*,
|
|
"y": "e",
|
|
}
|
|
|
|
In addition to the error codes defined in BEP5_, this specification defines
|
|
some additional error codes.
|
|
|
|
+------------+-----------------------------+
|
|
| error-code | description |
|
|
+============+=============================+
|
|
| 205 | message (i.e. ``v`` field) |
|
|
| | too big. |
|
|
+------------+-----------------------------+
|
|
| 206 | invalid signature |
|
|
+------------+-----------------------------+
|
|
| 301 | the CAS hash mismatched, |
|
|
| | re-read value and try |
|
|
| | again. |
|
|
+------------+-----------------------------+
|
|
| 302 | sequence number less than |
|
|
| | current. |
|
|
+------------+-----------------------------+
|
|
|
|
An implementation MUST emit 301 errors if the cas-hash mismatches. This is
|
|
a critical feature in synchronization of multiple agents sharing an immutable item.
|
|
|
|
get message
|
|
...........
|
|
|
|
Request:
|
|
|
|
.. parsed-literal::
|
|
|
|
{
|
|
"a":
|
|
{
|
|
"id": *<20 byte id of sending node (string)>*,
|
|
"target:" *<20 byte SHA-1 hash of public key (string)>*
|
|
},
|
|
"t": *<transaction-id (string)>*,
|
|
"y": "q",
|
|
"q": "get"
|
|
}
|
|
|
|
Response:
|
|
|
|
.. parsed-literal::
|
|
|
|
{
|
|
"r":
|
|
{
|
|
"id": *<20 byte id of sending node (string)>*,
|
|
"k": *<ed25519 public key (32 bytes string)>*,
|
|
"nodes": *<IPv4 nodes close to 'target'>*,
|
|
"nodes6": *<IPv6 nodes close to 'target'>*,
|
|
"seq": *<monotonically increasing sequence number (integer)>*,
|
|
"sig": *<ed25519 signature (64 bytes string)>*,
|
|
"token": *<write-token (string)>*,
|
|
"v": *<any bencoded type, whose encoded size <= 1000>*
|
|
},
|
|
"t": *<transaction-id (string)>*,
|
|
"y": "r",
|
|
}
|
|
|
|
signature verification
|
|
----------------------
|
|
|
|
The signature, private and public keys are in the format as produced by this derivative `ed25519 library`_.
|
|
|
|
.. _`ed25519 library`: https://github.com/nightcracker/ed25519
|
|
|
|
In order to make it maximally difficult to attack the bencoding parser, signing and verification of the
|
|
value and sequence number should be done as follows:
|
|
|
|
1. encode value and sequence number separately
|
|
2. concatenate *"3:seqi"* ``seq`` *"e1:v"* ``len`` *":"* and the encoded value.
|
|
sequence number 1 of value "Hello World!" would be converted to: "3:seqi1e1:v12:Hello World!"
|
|
In this way it is not possible to convince a node that part of the length is actually part of the
|
|
sequence number even if the parser contains certain bugs. Furthermore it is not possible to have a
|
|
verification failure if a bencoding serializer alters the order of entries in the dictionary.
|
|
3. sign or verify the concatenated string
|
|
|
|
On the storage node, the signature MUST be verified before accepting the store command. The data
|
|
MUST be stored under the SHA-1 hash of the public key (as it appears in the bencoded dict).
|
|
|
|
On the requesting nodes, the key they get back from a ``get`` request MUST be verified to hash
|
|
to the target ID the lookup was made for, as well as verifying the signature. If any of these fail,
|
|
the response SHOULD be considered invalid.
|
|
|
|
expiration
|
|
----------
|
|
|
|
Without re-announcement, these items MAY expire in 2 hours. In order
|
|
to keep items alive, they SHOULD be re-announced once an hour.
|
|
|
|
Any node that's interested in keeping a blob in the DHT alive may announce it. It would simply
|
|
repeat the signature for a mutable put without having the private key.
|
|
|
|
test vectors
|
|
------------
|
|
|
|
|