summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMartin Schanzenbach <schanzen@gnunet.org>2022-01-03 18:37:15 +0100
committerMartin Schanzenbach <schanzen@gnunet.org>2022-01-03 18:37:15 +0100
commit836f41df677921b1d8f0c395fe470d2fa32b029a (patch)
tree45a2489b9fbda4afc7049d5616ff706da0a8ed77
parent12ab2d98a05bc8eaf4ef45ad7646669a54f4f1f7 (diff)
downloadlsd0004-836f41df677921b1d8f0c395fe470d2fa32b029a.tar.gz
lsd0004-836f41df677921b1d8f0c395fe470d2fa32b029a.zip
struggling with indent
Diffstat
-rw-r--r--draft-schanzen-r5n.xml2429
1 files changed, 1214 insertions, 1215 deletions
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index a1a20f2..7b88e35 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -28,122 +28,121 @@
28<?rfc compact="yes" ?> 28<?rfc compact="yes" ?>
29<?rfc subcompact="no" ?> 29<?rfc subcompact="no" ?>
30<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"> 30<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">
31<!-- xml2rfc v2v3 conversion 2.26.0 --> 31 <front>
32<front> 32 <title abbrev="The R5N Distributed Hash Table">
33<title abbrev="The R5N Distributed Hash Table"> 33 The R5N Distributed Hash Table
34The R5N Distributed Hash Table 34 </title>
35</title> 35 <seriesInfo name="Internet-Draft" value="draft-schanzen-r5n-00"/>
36<seriesInfo name="Internet-Draft" value="draft-schanzen-r5n-00"/> 36 <author fullname="Martin Schanzenbach" initials="M." surname="Schanzenbach">
37<author fullname="Martin Schanzenbach" initials="M." surname="Schanzenbach"> 37 <organization>GNUnet e.V.</organization>
38<organization>GNUnet e.V.</organization> 38 <address>
39<address> 39 <postal>
40<postal> 40 <street>Boltzmannstrasse 3</street>
41<street>Boltzmannstrasse 3</street> 41 <city>Garching</city>
42<city>Garching</city> 42 <code>85748</code>
43<code>85748</code> 43 <country>DE</country>
44<country>DE</country> 44 </postal>
45</postal> 45 <email>schanzen@gnunet.org</email>
46<email>schanzen@gnunet.org</email> 46 </address>
47</address> 47 </author>
48</author> 48 <author fullname="Christian Grothoff" initials="C." surname="Grothoff">
49<author fullname="Christian Grothoff" initials="C." surname="Grothoff"> 49 <organization>Berner Fachhochschule</organization>
50<organization>Berner Fachhochschule</organization> 50 <address>
51<address> 51 <postal>
52<postal> 52 <street>Hoeheweg 80</street>
53<street>Hoeheweg 80</street> 53 <city>Biel/Bienne</city>
54<city>Biel/Bienne</city> 54 <code>2501</code>
55<code>2501</code> 55 <country>CH</country>
56<country>CH</country> 56 </postal>
57</postal> 57 <email>grothoff@gnunet.org</email>
58<email>grothoff@gnunet.org</email> 58 </address>
59</address> 59 </author>
60</author> 60 <author fullname="Bernd Fix" initials="B." surname="Fix">
61<author fullname="Bernd Fix" initials="B." surname="Fix"> 61 <organization>GNUnet e.V.</organization>
62<organization>GNUnet e.V.</organization> 62 <address>
63<address> 63 <postal>
64<postal> 64 <street>Boltzmannstrasse 3</street>
65<street>Boltzmannstrasse 3</street> 65 <city>Garching</city>
66<city>Garching</city> 66 <code>85748</code>
67<code>85748</code> 67 <country>DE</country>
68<country>DE</country> 68 </postal>
69</postal> 69 <email>fix@gnunet.org</email>
70<email>fix@gnunet.org</email> 70 </address>
71</address> 71 </author>
72</author> 72 <!-- Meta-data Declarations -->
73<!-- Meta-data Declarations --> 73 <area>General</area>
74<area>General</area> 74 <workgroup>Independent Stream</workgroup>
75<workgroup>Independent Stream</workgroup> 75 <keyword>distributed hash tables</keyword>
76<keyword>distributed hash tables</keyword> 76 <abstract>
77<abstract> 77 <t>This document contains the R5N DHT technical specification.</t>
78<t>This document contains the R5N DHT technical specification.</t> 78 <t>
79<t> 79 This document defines the normative wire format of resource records,
80This document defines the normative wire format of resource records, 80 resolution processes, cryptographic routines and security considerations for
81resolution processes, cryptographic routines and security considerations for 81 use by implementers.
82use by implementers. 82 </t>
83</t> 83 <t>
84<t> 84 This specification was developed outside the IETF and does not have IETF
85This specification was developed outside the IETF and does not have IETF 85 consensus. It is published here to guide implementation of R5N and to
86consensus. It is published here to guide implementation of R5N and to 86 ensure interoperability among implementations.
87ensure interoperability among implementations. 87 </t>
88</t> 88 </abstract>
89</abstract> 89 </front>
90</front> 90 <middle>
91<middle> 91 <section anchor="introduction" numbered="true" toc="default">
92<section anchor="introduction" numbered="true" toc="default"> 92 <name>Introduction</name>
93<name>Introduction</name>
94<!-- FIXME: Here we should also cite and discuss RELOAD (https://datatracker.ietf.org/doc/html/rfc6940) 93<!-- FIXME: Here we should also cite and discuss RELOAD (https://datatracker.ietf.org/doc/html/rfc6940)
95and establish why we need this spec and are not a "Topology plugin" 94and establish why we need this spec and are not a "Topology plugin"
96in RELOAD. The argumentation revolves around the trust model (openness) and 95in RELOAD. The argumentation revolves around the trust model (openness) and
97security aspects (path signatures). 96security aspects (path signatures).
98--> 97-->
99<t> 98 <t>
100Distributed Hash Tables (DHTs) are a key data structure for the 99 Distributed Hash Tables (DHTs) are a key data structure for the
101construction of completely decentralized applications. 100 construction of completely decentralized applications.
102DHTs are important because they generally provide a robust and 101 DHTs are important because they generally provide a robust and
103efficient means to distribute the storage and retrieval of 102 efficient means to distribute the storage and retrieval of
104key-value pairs. 103 key-value pairs.
105</t> 104 </t>
106<t> 105 <t>
107While <xref target="RFC6940"/> already provides a peer-to-peer (P2P) 106 While <xref target="RFC6940"/> already provides a peer-to-peer (P2P)
108signaling protocol with extensible routing and topology mechanisms, 107 signaling protocol with extensible routing and topology mechanisms,
109it also relies on strict admission control through the use of either 108 it also relies on strict admission control through the use of either
110centralized enrollment servers or pre-shared keys. 109 centralized enrollment servers or pre-shared keys.
111Modern decentralized applications require a more open system that 110 Modern decentralized applications require a more open system that
112enables ad-hoc participation and other means to prevent common attacks 111 enables ad-hoc participation and other means to prevent common attacks
113on P2P overlays. 112 on P2P overlays.
114</t> 113 </t>
115<t> 114 <t>
116This document contains the technical specification 115 This document contains the technical specification
117of the R5N DHT <xref target="R5N"/>, a secure DHT routing algorithm 116 of the R5N DHT <xref target="R5N"/>, a secure DHT routing algorithm
118and data structure for decentralized applications. 117 and data structure for decentralized applications.
119R5N is an open P2P overlay routing mechanism which supports ad-hoc 118 R5N is an open P2P overlay routing mechanism which supports ad-hoc
120participation and security properties including support for 119 participation and security properties including support for
121topologies in restricted-route environments and path signatures. 120 topologies in restricted-route environments and path signatures.
122</t> 121 </t>
123<t> 122 <t>
124This document defines the normative wire format of peer-to-peer 123 This document defines the normative wire format of peer-to-peer
125messages, routing algorithms, cryptographic routines and security 124 messages, routing algorithms, cryptographic routines and security
126considerations for use by implementors. 125 considerations for use by implementors.
127</t> 126 </t>
128<section numbered="true" toc="default"> 127 <section numbered="true" toc="default">
129<name>Requirements Notation</name> 128 <name>Requirements Notation</name>
130<t> 129 <t>
131The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
132"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 131 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
133"OPTIONAL" in this document are to be interpreted as described in 132 "OPTIONAL" in this document are to be interpreted as described in
134BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only 133 BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only
135when, they appear in all capitals, as shown here. 134 when, they appear in all capitals, as shown here.
136</t> 135 </t>
137</section> 136 </section>
138</section> 137 </section>
139<section anchor="architecture" numbered="true" toc="default"> 138 <section anchor="architecture" numbered="true" toc="default">
140<name>Architecture</name> 139 <name>Architecture</name>
141<t> 140 <t>
142R5N is an overlay network with a pluggable transport layer. 141 R5N is an overlay network with a pluggable transport layer.
143The following figure shows the R5N architecture. 142 The following figure shows the R5N architecture.
144</t> 143 </t>
145<figure> 144 <figure>
146<artwork><![CDATA[ 145 <artwork><![CDATA[
147 | +-----------------+ +-------+ 146 | +-----------------+ +-------+
148Applications | | GNU Name System | | CADET | ... 147Applications | | GNU Name System | | CADET | ...
149 | +-----------------+ +-------+ 148 | +-----------------+ +-------+
@@ -166,466 +165,466 @@ Connectivity | |Underlay| |Underlay|
166 | |Link | |Link | 165 | |Link | |Link |
167 | +--------+ +--------+ 166 | +--------+ +--------+
168]]> 167]]>
169</artwork> 168 </artwork>
170</figure> 169 </figure>
171<dl> 170 <dl>
172<dt>Applications</dt> 171 <dt>Applications</dt>
173<dd> 172 <dd>
174Applications are components which directly use the DHT overlay 173 Applications are components which directly use the DHT overlay
175interfaces. Possible applications include the GNU Name System 174 interfaces. Possible applications include the GNU Name System
176<xref target="I-D.draft-schanzen-gns"/> or the CADET transport system 175 <xref target="I-D.draft-schanzen-gns"/> or the CADET transport system
177<xref target="cadet"/>. 176 <xref target="cadet"/>.
178</dd> 177 </dd>
179<dt>Overlay Interface</dt> 178 <dt>Overlay Interface</dt>
180<dd> 179 <dd>
181The Overlay Interface exposes the core operations of the DHT overlay 180 The Overlay Interface exposes the core operations of the DHT overlay
182to applications. 181 to applications.
183This includes querying and retrieving data from the DHT. 182 This includes querying and retrieving data from the DHT.
184</dd> 183 </dd>
185<dt>Block Storage</dt> 184 <dt>Block Storage</dt>
186<dd> 185 <dd>
187The Block Storage component is used to persist and manage data 186 The Block Storage component is used to persist and manage data
188by nodes. It includes logic for quotas, caching stragegies and 187 by nodes. It includes logic for quotas, caching stragegies and
189data validation. 188 data validation.
190</dd> 189 </dd>
191<dt>Message Processing</dt> 190 <dt>Message Processing</dt>
192<dd> 191 <dd>
193The Message Processing component processes requests from and responses 192 The Message Processing component processes requests from and responses
194to applications as well as messages from the underlay network. 193 to applications as well as messages from the underlay network.
195</dd> 194 </dd>
196<dt>Routing</dt> 195 <dt>Routing</dt>
197<dd> 196 <dd>
198The Routing component includes the routing table as well as 197 The Routing component includes the routing table as well as
199routing and node selection logic. It facilitates the R5N routing 198 routing and node selection logic. It facilitates the R5N routing
200algorithm with required data structures and algorithms. 199 algorithm with required data structures and algorithms.
201</dd> 200 </dd>
202<dt>Underlay Interface</dt> 201 <dt>Underlay Interface</dt>
203<dd> 202 <dd>
204The DHT Underlay Interface is an abstraction layer on top of the 203 The DHT Underlay Interface is an abstraction layer on top of the
205supported links of a node. Nodes may be linked by a variety of 204 supported links of a node. Nodes may be linked by a variety of
206different transports, including "classical" protocols such as 205 different transports, including "classical" protocols such as
207TCP, UDP and TLS or advanced protocols such as GNUnet, L2P or Tor. 206 TCP, UDP and TLS or advanced protocols such as GNUnet, L2P or Tor.
208</dd> 207 </dd>
209</dl> 208 </dl>
210<t> 209 <t>
211Other glossary 210 Other glossary
212</t> 211 </t>
213<dl> 212 <dl>
214<dt>Node</dt> 213 <dt>Node</dt>
215<dd> 214 <dd>
216A node is participant in the network and addressable through the 215 A node is participant in the network and addressable through the
217network overlay. 216 network overlay.
218</dd> 217 </dd>
219<dt>Node Address</dt> 218 <dt>Node Address</dt>
220<dd> 219 <dd>
221The <tt>Node Address</tt> is the identifier used on the Overlay 220 The <tt>Node Address</tt> is the identifier used on the Overlay
222to address a node. 221 to address a node.
223</dd> 222 </dd>
224<dt>Node ID</dt> 223 <dt>Node ID</dt>
225<dd> 224 <dd>
226The <tt>Node ID</tt> is the identity which is used to authenticate 225 The <tt>Node ID</tt> is the identity which is used to authenticate
227a node in the underlay. 226 a node in the underlay.
228The <tt>Node Address</tt> is derived from the <tt>Node ID</tt>. 227 The <tt>Node Address</tt> is derived from the <tt>Node ID</tt>.
229</dd> 228 </dd>
230<dt>Peer</dt> 229 <dt>Peer</dt>
231<dd> 230 <dd>
232A peer is a node which is directly connected to our peer. 231 A peer is a node which is directly connected to our peer.
233</dd> 232 </dd>
234</dl> 233 </dl>
235</section> 234 </section>
236<section anchor="overlay" numbered="true" toc="default"> 235 <section anchor="overlay" numbered="true" toc="default">
237<name>Overlay</name> 236 <name>Overlay</name>
238<t> 237 <t>
239In the DHT overlay, a node is addressable by its 238 In the DHT overlay, a node is addressable by its
240<tt>Node Address</tt>. 239 <tt>Node Address</tt>.
241The <tt>Node Address</tt> is a SHA-512 hash <xref target="RFC4634"/> 240 The <tt>Node Address</tt> is a SHA-512 hash <xref target="RFC4634"/>
242of the <tt>Node ID</tt>. 241 of the <tt>Node ID</tt>.
243<!-- FIXME should the node ID be agile? Should the signature then 242 <!-- FIXME should the node ID be agile? Should the signature then
244also be agile?--> 243 also be agile?-->
245<!--The node public key is the public key of the corresponding 244 <!--The node public key is the public key of the corresponding
246Ed25519<xref target="ed25519" /> node private key.--> 245 Ed25519<xref target="ed25519" /> node private key.-->
247</t> 246 </t>
248<t> 247 <t>
249Any implementation of this specification MUST expose the two API 248 Any implementation of this specification MUST expose the two API
250procedures "GET" and "PUT". 249 procedures "GET" and "PUT".
251</t> 250 </t>
252<section> 251 <section>
253<name>The GET procedure</name> 252 <name>The GET procedure</name>
254<t> 253 <t>
255The GET procedure is defined as follows: 254 The GET procedure is defined as follows:
256</t> 255 </t>
257<t> 256 <t>
258<tt>GET(Key[, GetParams]) -> Results as List</tt> 257 <tt>GET(Key[, GetParams]) -> Results as List</tt>
259</t> 258 </t>
260<t> 259 <t>
261The procedure takes a single additional <tt>QueryParams</tt> 260 The procedure takes a single additional <tt>QueryParams</tt>
262argument in order to specify detailed query parameters. 261 argument in order to specify detailed query parameters.
263The <tt>GetParams</tt> consist of the following parameters: 262 The <tt>GetParams</tt> consist of the following parameters:
264</t> 263 </t>
265<dl> 264 <dl>
266<dt>BlockType</dt> 265 <dt>BlockType</dt>
267<dd> 266 <dd>
268The default setting of this parameter is to request any type of 267 The default setting of this parameter is to request any type of
269block types under the key. 268 block types under the key.
270</dd> 269 </dd>
271<dt>ReplicationLevel</dt> 270 <dt>ReplicationLevel</dt>
272<dd>The default setting of this parameter is X (FIXME).</dd> 271 <dd>The default setting of this parameter is X (FIXME).</dd>
273<dt>RouteOptions</dt> 272 <dt>RouteOptions</dt>
274<dd> 273 <dd>
275are used in order to indicate certain 274 are used in order to indicate certain
276processing requirements for messages. 275 processing requirements for messages.
277Any combination of options as defined in <xref target="route_options"/> 276 Any combination of options as defined in <xref target="route_options"/>
278may be specificied. 277 may be specificied.
279The default setting of this parameter is that no option is set. 278 The default setting of this parameter is that no option is set.
280</dd> 279 </dd>
281<dt>XQuery</dt> 280 <dt>XQuery</dt>
282<dd> 281 <dd>
283is extended query medatadata which may be 282 is extended query medatadata which may be
284required depending on the respective <tt>BlockType</tt>. 283 required depending on the respective <tt>BlockType</tt>.
285A <tt>BlockType</tt> must define if the <tt>XQuery</tt> can or must 284 A <tt>BlockType</tt> must define if the <tt>XQuery</tt> can or must
286be used and what the specific format of its contents should be. 285 be used and what the specific format of its contents should be.
287See also <xref target="block_types"/>. 286 See also <xref target="block_types"/>.
288The default setting of this parameter is empty. 287 The default setting of this parameter is empty.
289</dd> 288 </dd>
290</dl> 289 </dl>
291<t> 290 <t>
292The <tt>RouteOptions</tt> consist of the following flags: 291 The <tt>RouteOptions</tt> consist of the following flags:
293</t> 292 </t>
294<dl anchor="route_options"> 293 <dl anchor="route_options">
295<dt>DemultiplexEverywhere</dt> 294 <dt>DemultiplexEverywhere</dt>
296<dd> 295 <dd>
297indicates that each node along the way should process the request. 296 indicates that each node along the way should process the request.
298</dd> 297 </dd>
299<dt>RecordRoute</dt> 298 <dt>RecordRoute</dt>
300<dd> 299 <dd>
301indicates to keep track of the route that the message takes 300 indicates to keep track of the route that the message takes
302in the P2P network. 301 in the P2P network.
303</dd> 302 </dd>
304<dt>FindNode</dt> 303 <dt>FindNode</dt>
305<dd> 304 <dd>
306indicates that this is a request used to find additional nodes. 305 indicates that this is a request used to find additional nodes.
307This is a special flag which modifies the message processing to 306 This is a special flag which modifies the message processing to
308allow approximate results. 307 allow approximate results.
309</dd> 308 </dd>
310</dl> 309 </dl>
311<t> 310 <t>
312As the time it takes for results to arrive may vary an implementation 311 As the time it takes for results to arrive may vary an implementation
313may either return a list of results after a timeout or allow the 312 may either return a list of results after a timeout or allow the
314caller to provide a callback function which is called for any result 313 caller to provide a callback function which is called for any result
315received from the DHT until the procedure is cancelled. 314 received from the DHT until the procedure is cancelled.
316</t> 315 </t>
317</section> 316 </section>
318<section> 317 <section>
319<name>The PUT procedure</name> 318 <name>The PUT procedure</name>
320<t> 319 <t>
321The PUT procedure is defined as follows: 320 The PUT procedure is defined as follows:
322</t> 321 </t>
323<t> 322 <t>
324<tt>PUT(Key, Block, BlockType[, PutParams])</tt> 323 <tt>PUT(Key, Block, BlockType[, PutParams])</tt>
325</t> 324 </t>
326<t> 325 <t>
327The procedure takes three mandatory arguments. 326 The procedure takes three mandatory arguments.
328The first argument is the query 327 The first argument is the query
329key under which the block is to be stored. 328 key under which the block is to be stored.
330The second parameter is the block payload. 329 The second parameter is the block payload.
331The third parameter is the type of the block payload. 330 The third parameter is the type of the block payload.
332Block types are defined in <xref target="block_types"/>. 331 Block types are defined in <xref target="block_types"/>.
333The PUT procedure also allows an optional <tt>PutParams</tt> 332 The PUT procedure also allows an optional <tt>PutParams</tt>
334parameter. 333 parameter.
335</t> 334 </t>
336<dl> 335 <dl>
337<dt>ReplicationLevel</dt> 336 <dt>ReplicationLevel</dt>
338<dd>The default setting of this parameter is X (FIXME).</dd> 337 <dd>The default setting of this parameter is X (FIXME).</dd>
339<dt>RouteOptions</dt> 338 <dt>RouteOptions</dt>
340<dd> 339 <dd>
341are used in order to indicate certain 340 are used in order to indicate certain
342processing requirements for messages. 341 processing requirements for messages.
343Any combination of options as defined in <xref target="route_options"/> 342 Any combination of options as defined in <xref target="route_options"/>
344may be specificied. 343 may be specificied.
345The default setting of this parameter is that no option is set. 344 The default setting of this parameter is that no option is set.
346</dd> 345 </dd>
347<dt>Expiration</dt> 346 <dt>Expiration</dt>
348<dd> 347 <dd>
349is the requested expiration date for the block payload. 348 is the requested expiration date for the block payload.
350</dd> 349 </dd>
351</dl> 350 </dl>
352</section> 351 </section>
353</section> 352 </section>
354<section anchor="underlay" numbered="true" toc="default"> 353 <section anchor="underlay" numbered="true" toc="default">
355<name>Underlay</name> 354 <name>Underlay</name>
356<t> 355 <t>
357In the network underlay, a node is addressable by traditional 356 In the network underlay, a node is addressable by traditional
358means out of scope of this document. For example, the node may 357 means out of scope of this document. For example, the node may
359have a TCP/IP address, or a HTTPS endpoint. 358 have a TCP/IP address, or a HTTPS endpoint.
360While the specific addressing options and mechanisms are out of scope 359 While the specific addressing options and mechanisms are out of scope
361for this document, it is necessary to define a universal addressing 360 for this document, it is necessary to define a universal addressing
362format in order to facilitate the distribution of connectivity 361 format in order to facilitate the distribution of connectivity
363information to other nodes in the DHT overlay. 362 information to other nodes in the DHT overlay.
364This format is the "HELLO" message. 363 This format is the "HELLO" message.
365</t> 364 </t>
366<!-- 365 <!--
3671) The current API is always fire+forget, it doesn't allow for flow 366 1) The current API is always fire+forget, it doesn't allow for flow
368control. I think we need to add that, possibly for sending and receiving. 367 control. I think we need to add that, possibly for sending and receiving.
369 368
370IDK. 369 IDK.
371 370
3722) I'm not sure what to do with the crypto: mandate EdDSA or allow the 371 2) I'm not sure what to do with the crypto: mandate EdDSA or allow the
373underlay to do whatever public keys it likes. 372 underlay to do whatever public keys it likes.
374 373
375We need keys in the overlay. (Path signatures). Do they need to 374 We need keys in the overlay. (Path signatures). Do they need to
376be the same keys??? 375 be the same keys???
377 376
3783) I think we may want to mandate that the lower layer at least 377 3) I think we may want to mandate that the lower layer at least
379authenticate the other node (i.e. every UDP message could be in 378 authenticate the other node (i.e. every UDP message could be in
380cleartext, but would need to come with an EdDSA signature, alas 92 byte 379 cleartext, but would need to come with an EdDSA signature, alas 92 byte
381overhead and a signature verification _required_). Otherwise, I don't 380 overhead and a signature verification _required_). Otherwise, I don't
382see how we can offer even the most minimal protections against node 381 see how we can offer even the most minimal protections against node
383impersonation attacks. WDYT? 382 impersonation attacks. WDYT?
384 383
385Security considerations? Prerequisites? 384 Security considerations? Prerequisites?
386--> 385 -->
387<t> 386 <t>
388It is expected that there are basic mechanisms available to 387 It is expected that there are basic mechanisms available to
389manage node connectivity and addressing. 388 manage node connectivity and addressing.
390The required functionality are abstracted through the following 389 The required functionality are abstracted through the following
391procedures and events: 390 procedures and events:
392</t> 391 </t>
393<dl> 392 <dl>
394<dt> 393 <dt>
395<tt>PEER_CONNECTED(P)</tt> 394 <tt>PEER_CONNECTED(P)</tt>
396</dt> 395 </dt>
397<dd> 396 <dd>
398is a signal that allows the DHT to react to a newly connected peer 397 is a signal that allows the DHT to react to a newly connected peer
399<tt>N</tt>. 398 <tt>N</tt>.
400Such an event triggers, for example, updates in the 399 Such an event triggers, for example, updates in the
401routing table. 400 routing table.
402</dd> 401 </dd>
403<dt> 402 <dt>
404<tt>PEER_DISCONNECTED(P)</tt> 403 <tt>PEER_DISCONNECTED(P)</tt>
405</dt> 404 </dt>
406<dd> 405 <dd>
407is a signal that allows the DHT to react to a recently disconnected 406 is a signal that allows the DHT to react to a recently disconnected
408peer. 407 peer.
409Such an event triggers, for example, updates in the 408 Such an event triggers, for example, updates in the
410routing table. 409 routing table.
411</dd> 410 </dd>
412<dt> 411 <dt>
413<tt>TRY_CONNECT(N, A)</tt> 412 <tt>TRY_CONNECT(N, A)</tt>
414</dt> 413 </dt>
415<dd> 414 <dd>
416A function which allows the local node to attempt the establishment of 415 A function which allows the local node to attempt the establishment of
417a connection to another node <tt>N</tt> using an address <tt>A</tt>. 416 a connection to another node <tt>N</tt> using an address <tt>A</tt>.
418When the connection attempt is successful, information on the new 417 When the connection attempt is successful, information on the new
419peer is offered through the <tt>PEER_CONNECTED</tt> signal. 418 peer is offered through the <tt>PEER_CONNECTED</tt> signal.
420</dd> 419 </dd>
421<dt> 420 <dt>
422<tt>HOLD(P)</tt> 421 <tt>HOLD(P)</tt>
423</dt> 422 </dt>
424<dd> 423 <dd>
425A function which tells the underlay to keep a hold on the connection 424 A function which tells the underlay to keep a hold on the connection
426to a peer <tt>P</tt>. FIXME what is this needed for? 425 to a peer <tt>P</tt>. FIXME what is this needed for?
427</dd> 426 </dd>
428<dt> 427 <dt>
429<tt>DROP(P)</tt> 428 <tt>DROP(P)</tt>
430</dt> 429 </dt>
431<dd> 430 <dd>
432A function which tells the underlay to drop the connection to a 431 A function which tells the underlay to drop the connection to a
433peer <tt>P</tt>. FIXME what is this needed for? 432 peer <tt>P</tt>. FIXME what is this needed for?
434</dd> 433 </dd>
435<dt> 434 <dt>
436<tt>RECEIVE(P, M)</tt> 435 <tt>RECEIVE(P, M)</tt>
437</dt> 436 </dt>
438<dd> 437 <dd>
439A function or event that allows the local node to receive a protocol 438 A function or event that allows the local node to receive a protocol
440message <tt>M</tt> as defined in this document from a peer <tt>P</tt>. 439 message <tt>M</tt> as defined in this document from a peer <tt>P</tt>.
441</dd> 440 </dd>
442<dt> 441 <dt>
443<tt>SEND(P, M)</tt> 442 <tt>SEND(P, M)</tt>
444</dt> 443 </dt>
445<dd> 444 <dd>
446A function that allows the local node to send a protocol message 445 A function that allows the local node to send a protocol message
447<tt>M</tt> as defined in this document to a peer <tt>P</tt>. 446 <tt>M</tt> as defined in this document to a peer <tt>P</tt>.
448If call to SEND fails, the message has not been sent. 447 If call to SEND fails, the message has not been sent.
449</dd> 448 </dd>
450<dt> 449 <dt>
451<tt>NETWORK_SIZE_ESTIMATE(S)</tt> 450 <tt>NETWORK_SIZE_ESTIMATE(S)</tt>
452</dt> 451 </dt>
453<dd> 452 <dd>
454A function or event that provides estimates on the network size 453 A function or event that provides estimates on the network size
455<tt>S</tt> for use in the DHT routing algorithms. 454 <tt>S</tt> for use in the DHT routing algorithms.
456FIXME: What is S and give an example. 455 FIXME: What is S and give an example.
457</dd> 456 </dd>
458<dt> 457 <dt>
459<tt>ADDRESS_ADDED(A)</tt> 458 <tt>ADDRESS_ADDED(A)</tt>
460</dt> 459 </dt>
461<dd> 460 <dd>
462The underlay signals us that an address <tt>A</tt> was added for our 461 The underlay signals us that an address <tt>A</tt> was added for our
463local node. 462 local node.
464This information is used to advertise 463 This information is used to advertise
465connectivity information to the local node. 464 connectivity information to the local node.
466<tt>A</tt> is a string suitable for inclusion in a HELLO payload 465 <tt>A</tt> is a string suitable for inclusion in a HELLO payload
467<xref target="hello_block"/>. 466 <xref target="hello_block"/>.
468</dd> 467 </dd>
469<dt> 468 <dt>
470<tt>ADDRESS_DELETED(A)</tt> 469 <tt>ADDRESS_DELETED(A)</tt>
471</dt> 470 </dt>
472<dd> 471 <dd>
473The underlay signals us that an address <tt>A</tt> was removed. 472 The underlay signals us that an address <tt>A</tt> was removed.
474This information is used, for example, to no longer advertise 473 This information is used, for example, to no longer advertise
475this address. 474 this address.
476</dd> 475 </dd>
477<dt> 476 <dt>
478<tt>VERIFY(blob)</tt> 477 <tt>VERIFY(blob)</tt>
479</dt> 478 </dt>
480<dd> 479 <dd>
481Signature verification by underlay. FIXME unclear. Required? 480 Signature verification by underlay. FIXME unclear. Required?
482</dd> 481 </dd>
483</dl> 482 </dl>
484</section> 483 </section>
485<section> 484 <section>
486<name>Bootstrapping</name> 485 <name>Bootstrapping</name>
487<t> 486 <t>
488It is assumed that the node is already connected to at least 487 It is assumed that the node is already connected to at least
489one other node. 488 one other node.
490First, those initial nodes are sorted into their respective buckets. 489 First, those initial nodes are sorted into their respective buckets.
491</t> 490 </t>
492<t> 491 <t>
493In order to find the closest nodes in the network to itself, an 492 In order to find the closest nodes in the network to itself, an
494implementation MUST now periodically send HELLO GET queries for its own 493 implementation MUST now periodically send HELLO GET queries for its own
495node address. 494 node address.
496Both the "record route" and "find node" message options are set in the 495 Both the "record route" and "find node" message options are set in the
497GET queries in order to learn nodes and network topology from the 496 GET queries in order to learn nodes and network topology from the
498message route and in order to receive approximate replies to the 497 message route and in order to receive approximate replies to the
499query key (the node address). 498 query key (the node address).
500</t> 499 </t>
501<t>FIXME: Periodically -&gt; more specific? No. Frequency may be adapted depending on network conditions, known nodes, busy/idle etc.</t> 500 <t>FIXME: Periodically -&gt; more specific? No. Frequency may be adapted depending on network conditions, known nodes, busy/idle etc.</t>
502<t> 501 <t>
503Any implementation encountering a HELLO GET request initially 502 Any implementation encountering a HELLO GET request initially
504sends its own node address if it. 503 sends its own node address if it.
505</t> 504 </t>
506</section> 505 </section>
507<section anchor="routing" numbered="true" toc="default"> 506 <section anchor="routing" numbered="true" toc="default">
508<name>Routing</name> 507 <name>Routing</name>
509<section anchor="peer_storage"> 508 <section anchor="peer_storage">
510<name>Peer Storage</name> 509 <name>Peer Storage</name>
511<t> 510 <t>
512A R5N implementation must store the information on connected nodes 511 A R5N implementation must store the information on connected nodes
513and update changes accordingly in a local persistance component such 512 and update changes accordingly in a local persistance component such
514as a database. 513 as a database.
515Upon receiving a connection notification from the Underlay through 514 Upon receiving a connection notification from the Underlay through
516<tt>NODE_CONNECTED</tt>, information on the new peer is added to the 515 <tt>NODE_CONNECTED</tt>, information on the new peer is added to the
517local peer storage. 516 local peer storage.
518When disconnect is indicated by the Underlay through 517 When disconnect is indicated by the Underlay through
519<tt>NODE_DISCONNECTED</tt> the peer MUST be removed from the local 518 <tt>NODE_DISCONNECTED</tt> the peer MUST be removed from the local
520peer storage. 519 peer storage.
521The data structure for managing connected nodes and their 520 The data structure for managing connected nodes and their
522metadata may be implemented using the k-buckets concept of 521 metadata may be implemented using the k-buckets concept of
523<xref target="Kademlia"/>. 522 <xref target="Kademlia"/>.
524In order to select nodes which are suitable destinations for 523 In order to select nodes which are suitable destinations for
525routing messages, R5N uses a hybrid approach: 524 routing messages, R5N uses a hybrid approach:
526Given an estimated network size N, the node selection for the 525 Given an estimated network size N, the node selection for the
527first N hops is random. After the initial N hops, node selection 526 first N hops is random. After the initial N hops, node selection
528follows an XOR-based node distance calculation. 527 follows an XOR-based node distance calculation.
529</t> 528 </t>
530</section> 529 </section>
531<section anchor="routing_table"> 530 <section anchor="routing_table">
532<name>Routing Table</name> 531 <name>Routing Table</name>
533<t> 532 <t>
534As the message traverses a random path through the network for the 533 As the message traverses a random path through the network for the
535first N hops, it is essential that routing loops are avoided. 534 first N hops, it is essential that routing loops are avoided.
536In R5N, a bloomfilter is used as part of the routing metadata in 535 In R5N, a bloomfilter is used as part of the routing metadata in
537messages. The bloomfilter is updates at each hop with the hops 536 messages. The bloomfilter is updates at each hop with the hops
538node identity. 537 node identity.
539For the next hop selection in both the random and the deterministic 538 For the next hop selection in both the random and the deterministic
540case, any node which is in the bloomfilter for the respective message 539 case, any node which is in the bloomfilter for the respective message
541is not included in the node selection process. 540 is not included in the node selection process.
542</t> 541 </t>
543<t> 542 <t>
544The R5N routing component MUST implement the following functions: 543 The R5N routing component MUST implement the following functions:
545</t> 544 </t>
546<dl> 545 <dl>
547<dt> 546 <dt>
548<tt>GetDistance(A, B) -&gt; Distance as Integer</tt> 547 <tt>GetDistance(A, B) -&gt; Distance as Integer</tt>
549</dt> 548 </dt>
550<dd> 549 <dd>
551this function calculates the binary XOR between A and B. 550 this function calculates the binary XOR between A and B.
552The resulting distance is interpreted as an integer where 551 The resulting distance is interpreted as an integer where
553the leftmost bit is the most significant bit. 552 the leftmost bit is the most significant bit.
554</dd> 553 </dd>
555<dt> 554 <dt>
556<tt>SelectClosestNode(K, B) -&gt; N</tt> 555 <tt>SelectClosestNode(K, B) -&gt; N</tt>
557</dt> 556 </dt>
558<dd> 557 <dd>
559This function selects the connected node <tt>N</tt> from our 558 This function selects the connected node <tt>N</tt> from our
560routing table with the shortest XOR-distance to the key <tt>K</tt>. 559 routing table with the shortest XOR-distance to the key <tt>K</tt>.
561This means that for all other nodes <tt>N'</tt> in the routing table 560 This means that for all other nodes <tt>N'</tt> in the routing table
562<tt>GetDistance(N, K) &lt; GetDistance(N',K)</tt>. 561 <tt>GetDistance(N, K) &lt; GetDistance(N',K)</tt>.
563Nodes in the bloomfilter <tt>B</tt> are not considered. 562 Nodes in the bloomfilter <tt>B</tt> are not considered.
564</dd> 563 </dd>
565<dt> 564 <dt>
566<tt>SelectRandomNode(B) -&gt; N</tt> 565 <tt>SelectRandomNode(B) -&gt; N</tt>
567</dt> 566 </dt>
568<dd> 567 <dd>
569This function selects a random node <tt>N</tt> from all connected 568 This function selects a random node <tt>N</tt> from all connected
570nodes. 569 nodes.
571Nodes in the bloomfilter <tt>B</tt> are not considered. 570 Nodes in the bloomfilter <tt>B</tt> are not considered.
572</dd> 571 </dd>
573<dt> 572 <dt>
574<tt>SelectNode(K, H, B) -&gt; N</tt> 573 <tt>SelectNode(K, H, B) -&gt; N</tt>
575</dt> 574 </dt>
576<dd> 575 <dd>
577This function selects a node <tt>N</tt> depending on the 576 This function selects a node <tt>N</tt> depending on the
578number of hops <tt>H</tt> parameter. 577 number of hops <tt>H</tt> parameter.
579If <tt>H &lt; NETWORK_SIZE_ESTIMATE</tt> 578 If <tt>H &lt; NETWORK_SIZE_ESTIMATE</tt>
580this function MUST return <tt>SelectRandomNode()</tt> and 579 this function MUST return <tt>SelectRandomNode()</tt> and
581<tt>SelectClosestnode(K)</tt> otherwise. 580 <tt>SelectClosestnode(K)</tt> otherwise.
582Nodes in the bloomfilter <tt>B</tt> are not considered. 581 Nodes in the bloomfilter <tt>B</tt> are not considered.
583</dd> 582 </dd>
584<dt> 583 <dt>
585<tt>IsClosestNode(N, K, B) -&gt; true | false</tt> 584 <tt>IsClosestNode(N, K, B) -&gt; true | false</tt>
586</dt> 585 </dt>
587<dd> 586 <dd>
588checks if <tt>N</tt> is the closest node for <tt>K</tt> 587 checks if <tt>N</tt> is the closest node for <tt>K</tt>
589(cf. <tt>SelectClosestNode(K)</tt>). 588 (cf. <tt>SelectClosestNode(K)</tt>).
590Nodes in the bloomfilter <tt>B</tt> are not considered. 589 Nodes in the bloomfilter <tt>B</tt> are not considered.
591</dd> 590 </dd>
592</dl> 591 </dl>
593</section> 592 </section>
594</section> 593 </section>
595<section anchor="p2p_messages" numbered="true" toc="default"> 594 <section anchor="p2p_messages" numbered="true" toc="default">
596<name>Message Processing</name> 595 <name>Message Processing</name>
597<t> 596 <t>
598The implementation MUST listen for <tt>RECEIVE(P, M)</tt> signals 597 The implementation MUST listen for <tt>RECEIVE(P, M)</tt> signals
599from the Underlay and respond to the respective messages sent by 598 from the Underlay and respond to the respective messages sent by
600the peer <tt>P</tt>. 599 the peer <tt>P</tt>.
601In the following, the wire formats of the messages and the required 600 In the following, the wire formats of the messages and the required
602processing are detailed. 601 processing are detailed.
603The local node address is referred to as <tt>N</tt>. 602 The local node address is referred to as <tt>N</tt>.
604</t> 603 </t>
605<section anchor="p2p_bf" numbered="true" toc="default"> 604 <section anchor="p2p_bf" numbered="true" toc="default">
606<name>Bloomfilter</name> 605 <name>Bloomfilter</name>
607<t> 606 <t>
608In order to prevent circular routes, GET and PUT messages contain 607 In order to prevent circular routes, GET and PUT messages contain
609a 128-bit Bloom filter (m=128). The Bloom filter is used to detect duplicate 608 a 128-bit Bloom filter (m=128). The Bloom filter is used to detect duplicate
610node addresses along the route. 609 node addresses along the route.
611A Bloom filter "bf" is initially empty, consisting only of zeroes. 610 A Bloom filter "bf" is initially empty, consisting only of zeroes.
612There are two functions which can be invoked on the Bloom filter: 611 There are two functions which can be invoked on the Bloom filter:
613BF-SET(bf, e) and BF-TEST(bf, e) where "e" is an element which is to 612 BF-SET(bf, e) and BF-TEST(bf, e) where "e" is an element which is to
614be added to the Bloom filter or queried against the set. 613 be added to the Bloom filter or queried against the set.
615Any bloom filter uses k=16 different hash functions each of which is 614 Any bloom filter uses k=16 different hash functions each of which is
616defined as follows: 615 defined as follows:
617</t> 616 </t>
618</section> 617 </section>
619<section anchor="p2p_xq" numbered="true" toc="default"> 618 <section anchor="p2p_xq" numbered="true" toc="default">
620<name>Extended query</name> 619 <name>Extended query</name>
621<t>TODO: Talk about XQuery in the context of messages.</t> 620 <t>TODO: Talk about XQuery in the context of messages.</t>
622</section> 621 </section>
623<section anchor="p2p_put" numbered="true" toc="default"> 622 <section anchor="p2p_put" numbered="true" toc="default">
624<name>PutMessage</name> 623 <name>PutMessage</name>
625<section anchor="p2p_put_wire"> 624 <section anchor="p2p_put_wire">
626<name>Wire Format</name> 625 <name>Wire Format</name>
627<figure anchor="figure_putmsg"> 626 <figure anchor="figure_putmsg">
628<artwork name="" type="" align="left" alt=""><![CDATA[ 627 <artwork name="" type="" align="left" alt=""><![CDATA[
6290 8 16 24 32 40 48 56 6280 8 16 24 32 40 48 56
630+-----+-----+-----+-----+-----+-----+-----+-----+ 629+-----+-----+-----+-----+-----+-----+-----+-----+
631| MSIZE | MTYPE | BTYPE | 630| MSIZE | MTYPE | BTYPE |
@@ -645,132 +644,132 @@ defined as follows:
645/ BLOCK (variable length) / 644/ BLOCK (variable length) /
646+-----+-----+-----+-----+-----+-----+-----+-----+ 645+-----+-----+-----+-----+-----+-----+-----+-----+
647]]></artwork> 646]]></artwork>
648</figure> 647 </figure>
649<t>where:</t> 648 <t>where:</t>
650<dl> 649 <dl>
651<dt>MSIZE</dt> 650 <dt>MSIZE</dt>
652<dd> 651 <dd>
653denotes the size of this message in network byte order. 652 denotes the size of this message in network byte order.
654</dd> 653 </dd>
655<dt>MTYPE</dt> 654 <dt>MTYPE</dt>
656<dd> 655 <dd>
657is the 16-bit message type. This type can be one of the DHT message 656 is the 16-bit message type. This type can be one of the DHT message
658types but for put messages it must be set to 657 types but for put messages it must be set to
659the value 146 in network byte order. 658 the value 146 in network byte order.
660</dd> 659 </dd>
661<dt>BTYPE</dt> 660 <dt>BTYPE</dt>
662<dd> 661 <dd>
663is a 32-bit block type field. The block type indicates the content 662 is a 32-bit block type field. The block type indicates the content
664type of the payload. In network byte order. 663 type of the payload. In network byte order.
665</dd> 664 </dd>
666<dt>OPTIONS</dt> 665 <dt>OPTIONS</dt>
667<dd> 666 <dd>
668is a 16-bit options field (see below). 667 is a 16-bit options field (see below).
669</dd> 668 </dd>
670<dt>HOPCOUNT</dt> 669 <dt>HOPCOUNT</dt>
671<dd> 670 <dd>
672is a 16-bit number indicating how many hops this message has 671 is a 16-bit number indicating how many hops this message has
673traversed to far. In network byte order. 672 traversed to far. In network byte order.
674</dd> 673 </dd>
675<dt>REPL_LVL</dt> 674 <dt>REPL_LVL</dt>
676<dd> 675 <dd>
677is a 16-bit number indicating the desired replication level of 676 is a 16-bit number indicating the desired replication level of
678the data. In network byte order. 677 the data. In network byte order.
679</dd> 678 </dd>
680<dt>PATH_LEN</dt> 679 <dt>PATH_LEN</dt>
681<dd> 680 <dd>
682is a 16-bit number indicating the length of the PUT path recorded 681 is a 16-bit number indicating the length of the PUT path recorded
683in PUTPATH. 682 in PUTPATH.
684As PUTPATH is optional, this value may be zero. 683 As PUTPATH is optional, this value may be zero.
685In network byte order. 684 In network byte order.
686</dd> 685 </dd>
687<dt>EXPIRATION</dt> 686 <dt>EXPIRATION</dt>
688<dd> 687 <dd>
689denotes the absolute 64-bit expiration date of the content. 688 denotes the absolute 64-bit expiration date of the content.
690In microseconds since midnight (0 hour), January 1, 1970 in network 689 In microseconds since midnight (0 hour), January 1, 1970 in network
691byte order. 690 byte order.
692</dd> 691 </dd>
693<dt>BLOOMFILTER</dt> 692 <dt>BLOOMFILTER</dt>
694<dd> 693 <dd>
695A bloomfilter (for node addresses) to stop circular routes. 694 A bloomfilter (for node addresses) to stop circular routes.
696</dd> 695 </dd>
697<dt>KEY</dt> 696 <dt>KEY</dt>
698<dd> 697 <dd>
699The key under which the PUT request wants to store content 698 The key under which the PUT request wants to store content
700under. 699 under.
701</dd> 700 </dd>
702<dt>PUTPATH</dt> 701 <dt>PUTPATH</dt>
703<dd> 702 <dd>
704the variable-length PUT path. 703 the variable-length PUT path.
705The path consists of a list of PATH_LEN node addresses. 704 The path consists of a list of PATH_LEN node addresses.
706</dd> 705 </dd>
707<dt>BLOCK</dt> 706 <dt>BLOCK</dt>
708<dd> 707 <dd>
709the variable-length block payload. The contents are determined 708 the variable-length block payload. The contents are determined
710by the BTYPE field. 709 by the BTYPE field.
711</dd> 710 </dd>
712</dl> 711 </dl>
713</section> 712 </section>
714<section anchor="p2p_put_processing"> 713 <section anchor="p2p_put_processing">
715<name>Processing</name> 714 <name>Processing</name>
716<t> 715 <t>
717Upon receiving a <tt>PutMessage</tt> from a peer <tt>P</tt>. 716 Upon receiving a <tt>PutMessage</tt> from a peer <tt>P</tt>.
718An implementation MUST process it step by step as follows: 717 An implementation MUST process it step by step as follows:
719</t> 718 </t>
720<ol> 719 <ol>
721<li> 720 <li>
722The <tt>EXPIRATION</tt> field is evaluated. 721 The <tt>EXPIRATION</tt> field is evaluated.
723If the message is expired, it MUST be discarded. 722 If the message is expired, it MUST be discarded.
724</li> 723 </li>
725<li> 724 <li>
726If the <tt>BTYPE</tt> is not supported by the implementation, 725 If the <tt>BTYPE</tt> is not supported by the implementation,
727no validation of the block payload is performed and processing 726 no validation of the block payload is performed and processing
728continues at (4). 727 continues at (4).
729Else, the block MUST be validated as defined in (3). 728 Else, the block MUST be validated as defined in (3).
730</li> 729 </li>
731<li> 730 <li>
732The block payload of the message is evaluated using according 731 The block payload of the message is evaluated using according
733to the <tt>BTYPE</tt> using the respective 732 to the <tt>BTYPE</tt> using the respective
734<tt>ValidateBlockStoreRequest</tt> procedure. 733 <tt>ValidateBlockStoreRequest</tt> procedure.
735If the block payload is invalid or does not match the key, 734 If the block payload is invalid or does not match the key,
736it MUST be discarded. 735 it MUST be discarded.
737</li> 736 </li>
738<li> 737 <li>
739The node address of the sender peer <tt>P</tt> SHOULD be in <tt>BLOOMFILTER</tt>. 738 The node address of the sender peer <tt>P</tt> SHOULD be in <tt>BLOOMFILTER</tt>.
740If not, the implementation MAY log an error, but MUST continue. 739 If not, the implementation MAY log an error, but MUST continue.
741</li> 740 </li>
742<li> 741 <li>
743If the <tt>RecordRoute</tt> flag is set in OPTIONS, 742 If the <tt>RecordRoute</tt> flag is set in OPTIONS,
744the local node address MUST be appended to the <tt>PUTPATH</tt> 743 the local node address MUST be appended to the <tt>PUTPATH</tt>
745of the message. 744 of the message.
746</li> 745 </li>
747<li> 746 <li>
748If the local node is the closest node 747 If the local node is the closest node
749(cf. <tt>IsClosestNode(N, Key)</tt>) or the <tt>DemultiplexEverywhere</tt> 748 (cf. <tt>IsClosestNode(N, Key)</tt>) or the <tt>DemultiplexEverywhere</tt>
750options flag ist set, the message MUST 749 options flag ist set, the message MUST
751be stored locally in the block storage. 750 be stored locally in the block storage.
752</li> 751 </li>
753<li> 752 <li>
754Given the value in <tt>REPL_LVL</tt>, the number of peers to 753 Given the value in <tt>REPL_LVL</tt>, the number of peers to
755forward to MUST be calculated. If there is at least one 754 forward to MUST be calculated. If there is at least one
756peers to forward to, the implementation SHOULD select up to this 755 peers to forward to, the implementation SHOULD select up to this
757number of peers to forward the message to. The implementation MAY 756 number of peers to forward the message to. The implementation MAY
758forward to fewer or no peers in order to handle resource constraints 757 forward to fewer or no peers in order to handle resource constraints
759such as bandwidth. 758 such as bandwidth.
760Finally, the local node address MUST be added to the 759 Finally, the local node address MUST be added to the
761<tt>BLOOMFILTER</tt> of the forwarded message. 760 <tt>BLOOMFILTER</tt> of the forwarded message.
762For all peers with node address <tt>P</tt> chosen to forward the message 761 For all peers with node address <tt>P</tt> chosen to forward the message
763to, <tt>SEND(P, PutMessage)</tt> is called. 762 to, <tt>SEND(P, PutMessage)</tt> is called.
764</li> 763 </li>
765</ol> 764 </ol>
766</section> 765 </section>
767</section> 766 </section>
768<section anchor="p2p_get" numbered="true" toc="default"> 767 <section anchor="p2p_get" numbered="true" toc="default">
769<name>GetMessage</name> 768 <name>GetMessage</name>
770<section anchor="p2p_get_wire"> 769 <section anchor="p2p_get_wire">
771<name>Wire Format</name> 770 <name>Wire Format</name>
772<figure anchor="figure_getmsg"> 771 <figure anchor="figure_getmsg">
773<artwork name="" type="" align="left" alt=""><![CDATA[ 772 <artwork name="" type="" align="left" alt=""><![CDATA[
7740 8 16 24 32 40 48 56 7730 8 16 24 32 40 48 56
775+-----+-----+-----+-----+-----+-----+-----+-----+ 774+-----+-----+-----+-----+-----+-----+-----+-----+
776| MSIZE | MTYPE | BTYPE | 775| MSIZE | MTYPE | BTYPE |
@@ -790,134 +789,134 @@ to, <tt>SEND(P, PutMessage)</tt> is called.
790/ BF_RESULT (variable length) / 789/ BF_RESULT (variable length) /
791+-----+-----+-----+-----+-----+-----+-----+-----+ 790+-----+-----+-----+-----+-----+-----+-----+-----+
792]]></artwork> 791]]></artwork>
793</figure> 792 </figure>
794<t>where:</t> 793 <t>where:</t>
795<dl> 794 <dl>
796<dt>MSIZE</dt> 795 <dt>MSIZE</dt>
797<dd> 796 <dd>
798denotes the size of this message in network byte order. 797 denotes the size of this message in network byte order.
799</dd> 798 </dd>
800<dt>MTYPE</dt> 799 <dt>MTYPE</dt>
801<dd> 800 <dd>
802is the 16-bit message type. It must be set to 801 is the 16-bit message type. It must be set to
803the value 147 in network byte order. 802 the value 147 in network byte order.
804</dd> 803 </dd>
805<dt>BTYPE</dt> 804 <dt>BTYPE</dt>
806<dd> 805 <dd>
807is a 32-bit block type field. The block type indicates the content 806 is a 32-bit block type field. The block type indicates the content
808type of the payload. In network byte order. 807 type of the payload. In network byte order.
809</dd> 808 </dd>
810<dt>OPTIONS</dt> 809 <dt>OPTIONS</dt>
811<dd> 810 <dd>
812is a 16-bit options field (see below). 811 is a 16-bit options field (see below).
813</dd> 812 </dd>
814<dt>HOPCOUNT</dt> 813 <dt>HOPCOUNT</dt>
815<dd> 814 <dd>
816is a 16-bit number indicating how many hops this message has 815 is a 16-bit number indicating how many hops this message has
817traversed to far. In network byte order. 816 traversed to far. In network byte order.
818</dd> 817 </dd>
819<dt>REPL_LVL</dt> 818 <dt>REPL_LVL</dt>
820<dd> 819 <dd>
821is a 16-bit number indicating the desired replication level of 820 is a 16-bit number indicating the desired replication level of
822the data. In network byte order. 821 the data. In network byte order.
823</dd> 822 </dd>
824<dt>XQ_SIZE</dt> 823 <dt>XQ_SIZE</dt>
825<dd> 824 <dd>
826is a 32-bit number indicating the length of the optional 825 is a 32-bit number indicating the length of the optional
827extended query XQUERY. In network byte order. 826 extended query XQUERY. In network byte order.
828</dd> 827 </dd>
829<dt>BLOOMFILTER</dt> 828 <dt>BLOOMFILTER</dt>
830<dd> 829 <dd>
831A bloomfilter (for node identities) to stop circular routes. 830 A bloomfilter (for node identities) to stop circular routes.
832</dd> 831 </dd>
833<dt>KEY</dt> 832 <dt>KEY</dt>
834<dd> 833 <dd>
835The key under which the PUT request wants to store content 834 The key under which the PUT request wants to store content
836under. 835 under.
837</dd> 836 </dd>
838<dt>XQUERY</dt> 837 <dt>XQUERY</dt>
839<dd> 838 <dd>
840the variable-length extended query. Optional. 839 the variable-length extended query. Optional.
841</dd> 840 </dd>
842<dt>BF_MUTATOR</dt> 841 <dt>BF_MUTATOR</dt>
843<dd> 842 <dd>
844The 32-bit bloomfilter mutator for the result bloomfilter. 843 The 32-bit bloomfilter mutator for the result bloomfilter.
845</dd> 844 </dd>
846<dt>RESULT_BF</dt> 845 <dt>RESULT_BF</dt>
847<dd> 846 <dd>
848the variable-length result bloomfilter. 847 the variable-length result bloomfilter.
849</dd> 848 </dd>
850</dl> 849 </dl>
851</section> 850 </section>
852<section anchor="p2p_get_processing"> 851 <section anchor="p2p_get_processing">
853<name>Processing</name> 852 <name>Processing</name>
854<t> 853 <t>
855Upon receiving a <tt>GetMmessage</tt> from a peer an 854 Upon receiving a <tt>GetMmessage</tt> from a peer an
856implementation MUST process it step by step as follows: 855 implementation MUST process it step by step as follows:
857</t> 856 </t>
858<ol> 857 <ol>
859<li> 858 <li>
860The <tt>KEY</tt> and <tt>XQUERY</tt> is validated against the 859 The <tt>KEY</tt> and <tt>XQUERY</tt> is validated against the
861requested <tt>BTYPE</tt> as defined by its respective 860 requested <tt>BTYPE</tt> as defined by its respective
862<tt>ValidateBlockQuery</tt> procedure. 861 <tt>ValidateBlockQuery</tt> procedure.
863If the <tt>BTYPE</tt> is not supported, or if the block key 862 If the <tt>BTYPE</tt> is not supported, or if the block key
864does not match or if the <tt>XQUERY</tt> is malformed, 863 does not match or if the <tt>XQUERY</tt> is malformed,
865the message MUST be discarded. 864 the message MUST be discarded.
866</li> 865 </li>
867<li> 866 <li>
868The node address of the sender peer <tt>P</tt> SHOULD be in the 867 The node address of the sender peer <tt>P</tt> SHOULD be in the
869BLOOMFILTER. If not, the 868 BLOOMFILTER. If not, the
870implementation MAY log an error, but MUST continue. 869 implementation MAY log an error, but MUST continue.
871</li> 870 </li>
872<li> 871 <li>
873<t> 872 <t>
874If the local node is the closest node 873 If the local node is the closest node
875(cf. <tt>IsClosestNode (N, Key)</tt>) or the 874 (cf. <tt>IsClosestNode (N, Key)</tt>) or the
876<tt>DemultiplexEverywhere</tt> options flag is set, a reply 875 <tt>DemultiplexEverywhere</tt> options flag is set, a reply
877MUST be produced: 876 MUST be produced:
878</t> 877 </t>
879<ol> 878 <ol>
880<li> 879 <li>
881If <tt>OPTIONS</tt> indicate a <tt>FindNode</tt> request, 880 If <tt>OPTIONS</tt> indicate a <tt>FindNode</tt> request,
882FIXME the node selection 881 FIXME the node selection
883foo from buckets that probably needs fixing. Take into account 882 foo from buckets that probably needs fixing. Take into account
884<tt>REPLY_BF</tt> 883 <tt>REPLY_BF</tt>
885</li> 884 </li>
886<li> 885 <li>
887Else, if there is a block in the local Block Storage which is 886 Else, if there is a block in the local Block Storage which is
888not already in the <tt>RESULT_BF</tt>, 887 not already in the <tt>RESULT_BF</tt>,
889a ResultMessage MUST be sent. 888 a ResultMessage MUST be sent.
890FIXME link to how the result is sent? 889 FIXME link to how the result is sent?
891</li> 890 </li>
892</ol> 891 </ol>
893</li> 892 </li>
894<li> 893 <li>
895FIXME: We only handle if not GNUNET_BLOCK_EVALUATION_OK_LAST. 894 FIXME: We only handle if not GNUNET_BLOCK_EVALUATION_OK_LAST.
896This means that we must evaluate the Reply produced in the 895 This means that we must evaluate the Reply produced in the
897previous step using <tt>ValidateBlockReply</tt> for this 896 previous step using <tt>ValidateBlockReply</tt> for this
898<tt>BTYPE</tt> 897 <tt>BTYPE</tt>
899</li> 898 </li>
900<li> 899 <li>
901Given the value in REPL_LVL, the number of nodes to forward to 900 Given the value in REPL_LVL, the number of nodes to forward to
902MUST be calculated (NUM-FORWARD-nodeS). If there is at least one 901 MUST be calculated (NUM-FORWARD-nodeS). If there is at least one
903node to forward to, the implementation SHOULD select up to this 902 node to forward to, the implementation SHOULD select up to this
904number of nodes to forward the message to. The implementation MAY 903 number of nodes to forward the message to. The implementation MAY
905forward to fewer or no nodes in order to handle resource constraints 904 forward to fewer or no nodes in order to handle resource constraints
906such as bandwidth. 905 such as bandwidth.
907The message BLOOMFILTER MUST be updated with the local node 906 The message BLOOMFILTER MUST be updated with the local node
908address <tt>N</tt>. 907 address <tt>N</tt>.
909For all peers with node address <tt>P'</tt> chosen to forward the message 908 For all peers with node address <tt>P'</tt> chosen to forward the message
910to, <tt>SEND(P', PutMessage)</tt> is called. 909 to, <tt>SEND(P', PutMessage)</tt> is called.
911</li> 910 </li>
912</ol> 911 </ol>
913</section> 912 </section>
914</section> 913 </section>
915<section anchor="p2p_result" numbered="true" toc="default"> 914 <section anchor="p2p_result" numbered="true" toc="default">
916<name>ResultMessage</name> 915 <name>ResultMessage</name>
917<section anchor="p2p_result_wire"> 916 <section anchor="p2p_result_wire">
918<name>Wire Format</name> 917 <name>Wire Format</name>
919<figure anchor="figure_resmsg"> 918 <figure anchor="figure_resmsg">
920<artwork name="" type="" align="left" alt=""><![CDATA[ 919 <artwork name="" type="" align="left" alt=""><![CDATA[
9210 8 16 24 32 40 48 56 9200 8 16 24 32 40 48 56
922+-----+-----+-----+-----+-----+-----+-----+-----+ 921+-----+-----+-----+-----+-----+-----+-----+-----+
923| MSIZE | MTYPE | BTYPE | 922| MSIZE | MTYPE | BTYPE |
@@ -939,229 +938,229 @@ to, <tt>SEND(P', PutMessage)</tt> is called.
939/ (variable length) / 938/ (variable length) /
940+-----+-----+-----+-----+-----+-----+-----+-----+ 939+-----+-----+-----+-----+-----+-----+-----+-----+
941]]></artwork> 940]]></artwork>
942</figure> 941 </figure>
943<t>where:</t> 942 <t>where:</t>
944<dl> 943 <dl>
945<dt>MSIZE</dt> 944 <dt>MSIZE</dt>
946<dd> 945 <dd>
947denotes the size of this message in network byte order. 946 denotes the size of this message in network byte order.
948</dd> 947 </dd>
949<dt>MTYPE</dt> 948 <dt>MTYPE</dt>
950<dd> 949 <dd>
951is the 16-bit message type. This type can be one of the DHT message 950 is the 16-bit message type. This type can be one of the DHT message
952types but for put messages it must be set to 951 types but for put messages it must be set to
953the value 148 in network byte order. 952 the value 148 in network byte order.
954</dd> 953 </dd>
955<dt>OPTIONS</dt> 954 <dt>OPTIONS</dt>
956<dd> 955 <dd>
957is a 16-bit options field (see below). 956 is a 16-bit options field (see below).
958</dd> 957 </dd>
959<dt>BTYPE</dt> 958 <dt>BTYPE</dt>
960<dd> 959 <dd>
961is a 32-bit block type field. The block type indicates the content 960 is a 32-bit block type field. The block type indicates the content
962type of the payload. In network byte order. 961 type of the payload. In network byte order.
963</dd> 962 </dd>
964<dt>PUTPATH_L</dt> 963 <dt>PUTPATH_L</dt>
965<dd> 964 <dd>
966is a 16-bit number indicating the length of the PUT path recorded 965 is a 16-bit number indicating the length of the PUT path recorded
967in PUTPATH. As PUTPATH is optiona, this value may be zero. 966 in PUTPATH. As PUTPATH is optiona, this value may be zero.
968In network byte order. 967 In network byte order.
969</dd> 968 </dd>
970<dt>GET_PATH_LEN</dt> 969 <dt>GET_PATH_LEN</dt>
971<dd> 970 <dd>
972is a 16-bit number indicating the length of the GET path recorded 971 is a 16-bit number indicating the length of the GET path recorded
973in GETPATH. As PUTPATH is optiona, this value may be zero. 972 in GETPATH. As PUTPATH is optiona, this value may be zero.
974In network byte order. 973 In network byte order.
975</dd> 974 </dd>
976<dt>EXPIRATION</dt> 975 <dt>EXPIRATION</dt>
977<dd> 976 <dd>
978denotes the absolute 64-bit expiration date of the content. 977 denotes the absolute 64-bit expiration date of the content.
979In microseconds since midnight (0 hour), January 1, 1970 in network 978 In microseconds since midnight (0 hour), January 1, 1970 in network
980byte order. 979 byte order.
981</dd> 980 </dd>
982<dt>KEY</dt> 981 <dt>KEY</dt>
983<dd> 982 <dd>
984The key under which the PUT request wants to store content 983 The key under which the PUT request wants to store content
985under. 984 under.
986</dd> 985 </dd>
987<dt>PUTPATH</dt> 986 <dt>PUTPATH</dt>
988<dd> 987 <dd>
989the variable-length PUT path. 988 the variable-length PUT path.
990The path consists of a list of PATH_LEN node addresses. 989 The path consists of a list of PATH_LEN node addresses.
991</dd> 990 </dd>
992<dt>GETPATH</dt> 991 <dt>GETPATH</dt>
993<dd> 992 <dd>
994the variable-length PUT path. 993 the variable-length PUT path.
995The path consists of a list of PATH_LEN node addresses. 994 The path consists of a list of PATH_LEN node addresses.
996</dd> 995 </dd>
997<dt>BLOCK</dt> 996 <dt>BLOCK</dt>
998<dd> 997 <dd>
999the variable-length resource record data payload. 998 the variable-length resource record data payload.
1000The contents are defined by the respective type of the resource record. 999 The contents are defined by the respective type of the resource record.
1001</dd> 1000 </dd>
1002</dl> 1001 </dl>
1003</section> 1002 </section>
1004<section anchor="p2p_result_processing"> 1003 <section anchor="p2p_result_processing">
1005<name>Processing</name> 1004 <name>Processing</name>
1006<t> 1005 <t>
1007Upon receiving a <tt>ResultMessage</tt> from a connected node. 1006 Upon receiving a <tt>ResultMessage</tt> from a connected node.
1008An implementation MUST process it step by step as follows: 1007 An implementation MUST process it step by step as follows:
1009</t> 1008 </t>
1010<ol> 1009 <ol>
1011<li> 1010 <li>
1012The <tt>EXPIRATION</tt> field is evaluated. 1011 The <tt>EXPIRATION</tt> field is evaluated.
1013If the message is expired, it MUST be discarded. 1012 If the message is expired, it MUST be discarded.
1014</li> 1013 </li>
1015<li> 1014 <li>
1016If the MTYPE of the message indicates a HELLO block, it 1015 If the MTYPE of the message indicates a HELLO block, it
1017must be validated according to <xref target="hello_block"/>. 1016 must be validated according to <xref target="hello_block"/>.
1018The payload MUST be considered for the local routing table by 1017 The payload MUST be considered for the local routing table by
1019trying to establish a connection to the node using the information 1018 trying to establish a connection to the node using the information
1020from the HELLO block. If a connection can be established, 1019 from the HELLO block. If a connection can be established,
1021the node is added to the <tt>KBuckets</tt> routing table. 1020 the node is added to the <tt>KBuckets</tt> routing table.
1022</li> 1021 </li>
1023<li> 1022 <li>
1024If the sender node of the message is already found in the 1023 If the sender node of the message is already found in the
1025GETPATH, the path MUST be truncated at this position. 1024 GETPATH, the path MUST be truncated at this position.
1026The implementation MAY log a warning in such a case. 1025 The implementation MAY log a warning in such a case.
1027</li> 1026 </li>
1028<li> 1027 <li>
1029If the <tt>KEY</tt> of this <tt>ResultMessage</tt> is found in the 1028 If the <tt>KEY</tt> of this <tt>ResultMessage</tt> is found in the
1030list of pending local queries, the <tt>KEY</tt> and <tt>XQUERY</tt> 1029 list of pending local queries, the <tt>KEY</tt> and <tt>XQUERY</tt>
1031are validated against the requested BTYPE using the respective 1030 are validated against the requested BTYPE using the respective
1032block type implementation of <tt>ValidateBlockReply</tt>. 1031 block type implementation of <tt>ValidateBlockReply</tt>.
1033If the BTYPE is not supported, or if the block key 1032 If the BTYPE is not supported, or if the block key
1034does not match the BTYPE or if the XQUERY is malformed, 1033 does not match the BTYPE or if the XQUERY is malformed,
1035the message MUST be discarded. 1034 the message MUST be discarded.
1036</li> 1035 </li>
1037<li> 1036 <li>
1038The implementation MAY cache RESULT messages. 1037 The implementation MAY cache RESULT messages.
1039</li> 1038 </li>
1040<li> 1039 <li>
1041<t> 1040 <t>
1042If requests by other nodes for this KEY or BTYPE are known, 1041 If requests by other nodes for this KEY or BTYPE are known,
1043the result block is validated against each request using 1042 the result block is validated against each request using
1044the respective <tt>ValidateBlockReply</tt> function. 1043 the respective <tt>ValidateBlockReply</tt> function.
1045</t> 1044 </t>
1046<t> 1045 <t>
1047If the request options include <tt>FindNode</tt> and the result 1046 If the request options include <tt>FindNode</tt> and the result
1048message block type is HELLO the block validation must use the 1047 message block type is HELLO the block validation must use the
1049key derived using <tt>DeriveBlockKey</tt> as the key included in 1048 key derived using <tt>DeriveBlockKey</tt> as the key included in
1050the request is only approximate. (FIXME: So we extract the key 1049 the request is only approximate. (FIXME: So we extract the key
1051to then check it again against the block? This does not make sense...) 1050 to then check it again against the block? This does not make sense...)
1052</t> 1051 </t>
1053<t> 1052 <t>
1054If the result message block cannot be verified against the 1053 If the result message block cannot be verified against the
1055<tt>KEY</tt> of the result message or if <tt>BLOCK</tt> is 1054 <tt>KEY</tt> of the result message or if <tt>BLOCK</tt> is
1056malformed, the message MUST be discarded. 1055 malformed, the message MUST be discarded.
1057</t> 1056 </t>
1058<t> 1057 <t>
1059For each pending request the reply is routed to the requesting 1058 For each pending request the reply is routed to the requesting
1060node <tt>N'</tt>. FIXME routed to node or forwarded to peer? 1059 node <tt>N'</tt>. FIXME routed to node or forwarded to peer?
1061</t> 1060 </t>
1062</li> 1061 </li>
1063</ol> 1062 </ol>
1064</section> 1063 </section>
1065</section> 1064 </section>
1066</section> 1065 </section>
1067<section anchor="blockstorage" numbered="true" toc="default"> 1066 <section anchor="blockstorage" numbered="true" toc="default">
1068<name>Block Storage</name> 1067 <name>Block Storage</name>
1069<section> 1068 <section>
1070<name>Block Processing</name> 1069 <name>Block Processing</name>
1071<t>RequestEvaluationResult</t> 1070 <t>RequestEvaluationResult</t>
1072<dl> 1071 <dl>
1073<dt>REQUEST_VALID</dt> 1072 <dt>REQUEST_VALID</dt>
1074<dd>Query is valid, no reply given.</dd> 1073 <dd>Query is valid, no reply given.</dd>
1075<dt>REQUEST_INVALID</dt> 1074 <dt>REQUEST_INVALID</dt>
1076<dd> 1075 <dd>
1077Query format does not match block type. For example, XQuery not 1076 Query format does not match block type. For example, XQuery not
1078given or of size of XQuery is not appropriate for type. 1077 given or of size of XQuery is not appropriate for type.
1079</dd> 1078 </dd>
1080</dl> 1079 </dl>
1081<t>ReplyEvaluationResult</t> 1080 <t>ReplyEvaluationResult</t>
1082<dl> 1081 <dl>
1083<dt>OK_MORE</dt> 1082 <dt>OK_MORE</dt>
1084<dd>Valid result, and there may be more.</dd> 1083 <dd>Valid result, and there may be more.</dd>
1085<dt>OK_LAST</dt> 1084 <dt>OK_LAST</dt>
1086<dd>Last possible valid result.</dd> 1085 <dd>Last possible valid result.</dd>
1087<dt>OK_DUPLICATE</dt> 1086 <dt>OK_DUPLICATE</dt>
1088<dd>Valid result, but duplicate.</dd> 1087 <dd>Valid result, but duplicate.</dd>
1089<dt>RESULT_INVALID</dt> 1088 <dt>RESULT_INVALID</dt>
1090<dd>Invalid result. Block does not match query. Value = 4.</dd> 1089 <dd>Invalid result. Block does not match query. Value = 4.</dd>
1091<dt>RESULT_IRRELEVANT</dt> 1090 <dt>RESULT_IRRELEVANT</dt>
1092<dd>Block does not match xquery. Valid result, but not relevant for the request.</dd> 1091 <dd>Block does not match xquery. Valid result, but not relevant for the request.</dd>
1093</dl> 1092 </dl>
1094</section> 1093 </section>
1095<section anchor="block_functions"> 1094 <section anchor="block_functions">
1096<name>Block Functions</name> 1095 <name>Block Functions</name>
1097<t> 1096 <t>
1098Any block type implementation MUST implement the following functions. 1097 Any block type implementation MUST implement the following functions.
1099</t> 1098 </t>
1100<dl> 1099 <dl>
1101<dt>ValidateBlockQuery(Key, XQuery) -&gt; RequestEvaluationResult</dt> 1100 <dt>ValidateBlockQuery(Key, XQuery) -&gt; RequestEvaluationResult</dt>
1102<dd> 1101 <dd>
1103is used to evaluate the request for a block. It is used as part of 1102 is used to evaluate the request for a block. It is used as part of
1104<tt>GetMessage</tt> processing, where the block payload is still unkown, 1103 <tt>GetMessage</tt> processing, where the block payload is still unkown,
1105but the block <tt>XQuery</tt> (FIXME: Undefined here) and <tt>Key</tt> can and 1104 but the block <tt>XQuery</tt> (FIXME: Undefined here) and <tt>Key</tt> can and
1106MUST be verified, if possible. 1105 MUST be verified, if possible.
1107</dd> 1106 </dd>
1108<dt>ValidateBlockStoreRequest(Block, Key) -&gt; RequestEvaluationResult</dt> 1107 <dt>ValidateBlockStoreRequest(Block, Key) -&gt; RequestEvaluationResult</dt>
1109<dd> 1108 <dd>
1110is used to evaluate a block including its key and payload. 1109 is used to evaluate a block including its key and payload.
1111It is used as part of <tt>PutMessage</tt> processing. 1110 It is used as part of <tt>PutMessage</tt> processing.
1112The validation MUST include a check of the block payload against the 1111 The validation MUST include a check of the block payload against the
1113<tt>Key</tt> under which it is requested to be stored. 1112 <tt>Key</tt> under which it is requested to be stored.
1114</dd> 1113 </dd>
1115<dt>ValidateBlockReply(Block, XQuery, Key) -&gt; ReplyEvaluationResult</dt> 1114 <dt>ValidateBlockReply(Block, XQuery, Key) -&gt; ReplyEvaluationResult</dt>
1116<dd> 1115 <dd>
1117is used to evaluate a block including its <tt>Key</tt> and payload. 1116 is used to evaluate a block including its <tt>Key</tt> and payload.
1118It is used as part <tt>ResultMessage</tt> processing. 1117 It is used as part <tt>ResultMessage</tt> processing.
1119The validation of the respective <tt>Block</tt> requires a pending local query 1118 The validation of the respective <tt>Block</tt> requires a pending local query
1120or a previously routed request of another node and its associated 1119 or a previously routed request of another node and its associated
1121XQuery data and Key. 1120 XQuery data and Key.
1122The validation MUST include a check of the block payload against the 1121 The validation MUST include a check of the block payload against the
1123key under which it is requested to be stored. 1122 key under which it is requested to be stored.
1124</dd> 1123 </dd>
1125<dt>DeriveBlockKey(Block) -&gt; Key</dt> 1124 <dt>DeriveBlockKey(Block) -&gt; Key</dt>
1126<dd> 1125 <dd>
1127is used to synthesize the block key from the block payload 1126 is used to synthesize the block key from the block payload
1128and metadata. It is used as part of FIND-node message processing. 1127 and metadata. It is used as part of FIND-node message processing.
1129</dd> 1128 </dd>
1130<dt>FilterResult(Block, XQuery, Key) -&gt; ReplyEvaluationResult</dt> 1129 <dt>FilterResult(Block, XQuery, Key) -&gt; ReplyEvaluationResult</dt>
1131<dd> 1130 <dd>
1132is used to filter results stored in the local block storage for local 1131 is used to filter results stored in the local block storage for local
1133queries. Locally stored blocks from previously observed 1132 queries. Locally stored blocks from previously observed
1134<tt>ResultMessages</tt> and <tt>PutMessages</tt> MAY use this 1133 <tt>ResultMessages</tt> and <tt>PutMessages</tt> MAY use this
1135function instead of <tt>ValidateBlockReply</tt> in order to 1134 function instead of <tt>ValidateBlockReply</tt> in order to
1136avoid revalidation of the block and only perform filtering based on 1135 avoid revalidation of the block and only perform filtering based on
1137request parameters. 1136 request parameters.
1138</dd> 1137 </dd>
1139</dl> 1138 </dl>
1140</section> 1139 </section>
1141<section anchor="block_types"> 1140 <section anchor="block_types">
1142<name>Block Types</name> 1141 <name>Block Types</name>
1143<t> 1142 <t>
1144Applications can and should define their own block types. 1143 Applications can and should define their own block types.
1145The block type determines the format and handling of the block 1144 The block type determines the format and handling of the block
1146payload by nodes in PUT and RESULT messages. 1145 payload by nodes in PUT and RESULT messages.
1147Block types MUST be registered with GANA <xref target="gana"/>. 1146 Block types MUST be registered with GANA <xref target="gana"/>.
1148</t> 1147 </t>
1149<t> 1148 <t>
1150For bootstrapping and node discovery, the DHT implementation uses 1149 For bootstrapping and node discovery, the DHT implementation uses
1151its own block type called "HELLO". A block with this block type 1150 its own block type called "HELLO". A block with this block type
1152contains the NodeID of the node initiating the GET request. 1151 contains the NodeID of the node initiating the GET request.
1153</t> 1152 </t>
1154<section anchor="hello_block"> 1153 <section anchor="hello_block">
1155<name>HELLO</name> 1154 <name>HELLO</name>
1156<t> 1155 <t>
1157The HELLO block type wire format is illustrated in 1156 The HELLO block type wire format is illustrated in
1158<xref target="figure_hello"/>. A query for block of type HELLO MUST 1157 <xref target="figure_hello"/>. A query for block of type HELLO MUST
1159NOT include extended query data (XQuery). Any implementation 1158 NOT include extended query data (XQuery). Any implementation
1160encountering a HELLO block with XQuery data MUST consider the 1159 encountering a HELLO block with XQuery data MUST consider the
1161block invalid and ignore it. 1160 block invalid and ignore it.
1162</t> 1161 </t>
1163<figure anchor="figure_hello"> 1162 <figure anchor="figure_hello">
1164<artwork name="" type="" align="left" alt=""><![CDATA[ 1163 <artwork name="" type="" align="left" alt=""><![CDATA[
11650 8 16 24 32 40 48 56 11640 8 16 24 32 40 48 56
1166+-----+-----+-----+-----+-----+-----+-----+-----+ 1165+-----+-----+-----+-----+-----+-----+-----+-----+
1167| TYPE | SIZE | NODEID / 1166| TYPE | SIZE | NODEID /
@@ -1172,98 +1171,98 @@ block invalid and ignore it.
1172/ (variable length) | 1171/ (variable length) |
1173+-----+-----+-----+-----+-----+-----+-----+-----+ 1172+-----+-----+-----+-----+-----+-----+-----+-----+
1174]]></artwork> 1173]]></artwork>
1175</figure> 1174 </figure>
1176<dl> 1175 <dl>
1177<dt>TYPE</dt> 1176 <dt>TYPE</dt>
1178<dd> 1177 <dd>
1179is the type of HELLO. A 16-bit number in network byte order. 1178 is the type of HELLO. A 16-bit number in network byte order.
1180This value determines the type of the NODEID field. 1179 This value determines the type of the NODEID field.
1181</dd> 1180 </dd>
1182<dt>SIZE</dt> 1181 <dt>SIZE</dt>
1183<dd> 1182 <dd>
1184is the SIZE of the following fields NODEID and ADDRESSES in bytes. 1183 is the SIZE of the following fields NODEID and ADDRESSES in bytes.
1185In network byte order. 1184 In network byte order.
1186</dd> 1185 </dd>
1187<dt>NODEID</dt> 1186 <dt>NODEID</dt>
1188<dd> 1187 <dd>
1189is the Node ID of the node which has generated this HELLO. 1188 is the Node ID of the node which has generated this HELLO.
1190The length content of this field is determined by the TYPE. 1189 The length content of this field is determined by the TYPE.
1191Usually, this is a cryptographic public key which allows the 1190 Usually, this is a cryptographic public key which allows the
1192Underlay to uniquely identify and authenticate the node. 1191 Underlay to uniquely identify and authenticate the node.
1193</dd> 1192 </dd>
1194<dt>ADDRESSES</dt> 1193 <dt>ADDRESSES</dt>
1195<dd> 1194 <dd>
1196is a list of UTF-8 strings <xref target="RFC3629"/> which can be 1195 is a list of UTF-8 strings <xref target="RFC3629"/> which can be
1197used as addresses to contact the node. 1196 used as addresses to contact the node.
1198The strings MUST be 0-terminated. 1197 The strings MUST be 0-terminated.
1199FIXME: Examples? Format determined? 1198 FIXME: Examples? Format determined?
1200</dd> 1199 </dd>
1201</dl> 1200 </dl>
1202<t> 1201 <t>
1203A HELLO reply block MAY be empty. Otherwise, it contains the 1202 A HELLO reply block MAY be empty. Otherwise, it contains the
1204HELLO of a node. 1203 HELLO of a node.
1205</t> 1204 </t>
1206<t> 1205 <t>
1207For the string representation of the node public key, 1206 For the string representation of the node public key,
1208the base-32 encoding "StringEncode" is used. 1207 the base-32 encoding "StringEncode" is used.
1209However, instead of following <xref target="RFC4648"/> the 1208 However, instead of following <xref target="RFC4648"/> the
1210character map is based on the optical character recognition friendly 1209 character map is based on the optical character recognition friendly
1211proposal of Crockford <xref target="CrockfordB32"/>. 1210 proposal of Crockford <xref target="CrockfordB32"/>.
1212The only difference to Crockford is that the letter 1211 The only difference to Crockford is that the letter
1213"U" decodes to the same base-32 value as the letter "V" (27). 1212 "U" decodes to the same base-32 value as the letter "V" (27).
1214</t> 1213 </t>
1215<t> 1214 <t>
1216The <tt>ADDRESSES</tt> part of the <tt>HELLO</tt> indicate endpoints 1215 The <tt>ADDRESSES</tt> part of the <tt>HELLO</tt> indicate endpoints
1217which can be used by the Underlay in order to establish a connection 1216 which can be used by the Underlay in order to establish a connection
1218with the node identified by <tt>NODEKEY</tt>. 1217 with the node identified by <tt>NODEKEY</tt>.
1219An example of an addressing scheme used throughout 1218 An example of an addressing scheme used throughout
1220this document is "ip+tcp", which refers to a standard TCP/IP socket 1219 this document is "ip+tcp", which refers to a standard TCP/IP socket
1221connection. The "hier"-part of the URI must provide a suitable 1220 connection. The "hier"-part of the URI must provide a suitable
1222address for the given addressing scheme. 1221 address for the given addressing scheme.
1223The following is a non-normative example of address strings: 1222 The following is a non-normative example of address strings:
1224</t> 1223 </t>
1225<figure> 1224 <figure>
1226<artwork name="" type="" align="left" alt=""><![CDATA[ 1225 <artwork name="" type="" align="left" alt=""><![CDATA[
1227ip+tcp://1.2.3.4:6789 \ 1226ip+tcp://1.2.3.4:6789 \
1228gnunet+tcp://12.3.4.5/ \ 1227gnunet+tcp://12.3.4.5/ \
1229i2p+udp://1.2.4.5:424/ \ 1228i2p+udp://1.2.4.5:424/ \
1230tor+onionv3://rasdflkjasdfliasduf.onion/ 1229tor+onionv3://rasdflkjasdfliasduf.onion/
1231]]></artwork> 1230]]></artwork>
1232</figure> 1231 </figure>
1233</section> 1232 </section>
1234</section> 1233 </section>
1235</section> 1234 </section>
1236<section anchor="security" numbered="true" toc="default"> 1235 <section anchor="security" numbered="true" toc="default">
1237<name>Security Considerations</name> 1236 <name>Security Considerations</name>
1238<!-- FIXME: Here we should (again) discuss how the system is open and 1237 <!-- FIXME: Here we should (again) discuss how the system is open and
1239does not have/require a trust anchor a priori. This is (again) in contrast 1238 does not have/require a trust anchor a priori. This is (again) in contrast
1240to RELOAD --> 1239 to RELOAD -->
1241</section> 1240 </section>
1242<section anchor="gana" numbered="true" toc="default"> 1241 <section anchor="gana" numbered="true" toc="default">
1243<name>GANA Considerations</name> 1242 <name>GANA Considerations</name>
1244<t> 1243 <t>
1245GANA <xref target="GANA"/> 1244 GANA <xref target="GANA"/>
1246is requested to create a "DHT Block Types" registry. 1245 is requested to create a "DHT Block Types" registry.
1247The registry shall record for each entry: 1246 The registry shall record for each entry:
1248</t> 1247 </t>
1249<ul> 1248 <ul>
1250<li>Name: The name of the block type (case-insensitive ASCII 1249 <li>Name: The name of the block type (case-insensitive ASCII
1251string, restricted to alphanumeric characters</li> 1250 string, restricted to alphanumeric characters</li>
1252<li>Number: 32-bit</li> 1251 <li>Number: 32-bit</li>
1253<li>Comment: Optionally, a brief English text describing the purpose of 1252 <li>Comment: Optionally, a brief English text describing the purpose of
1254the block type (in UTF-8)</li> 1253 the block type (in UTF-8)</li>
1255<li>Contact: Optionally, the contact information of a person to contact for 1254 <li>Contact: Optionally, the contact information of a person to contact for
1256further information</li> 1255 further information</li>
1257<li>References: Optionally, references describing the record type 1256 <li>References: Optionally, references describing the record type
1258(such as an RFC)</li> 1257 (such as an RFC)</li>
1259</ul> 1258 </ul>
1260<t> 1259 <t>
1261The registration policy for this sub-registry is "First Come First 1260 The registration policy for this sub-registry is "First Come First
1262Served", as described in <xref target="RFC8126"/>. 1261 Served", as described in <xref target="RFC8126"/>.
1263GANA is requested to populate this registry as follows: 1262 GANA is requested to populate this registry as follows:
1264</t> 1263 </t>
1265<figure anchor="figure_btypenums"> 1264 <figure anchor="figure_btypenums">
1266<artwork name="" type="" align="left" alt=""><![CDATA[ 1265 <artwork name="" type="" align="left" alt=""><![CDATA[
1267Number | Name | Contact | References | Description 1266Number | Name | Contact | References | Description
1268-------+--------+---------+------------+------------------------- 1267-------+--------+---------+------------+-------------------------
12690 ANY N/A [This.I-D] Reserved 12680 ANY N/A [This.I-D] Reserved
@@ -1271,98 +1270,98 @@ Number | Name | Contact | References | Description
1271a HELLO for a node 1270a HELLO for a node
127211 GNS N/A GNS Block for storing record data 127111 GNS N/A GNS Block for storing record data
1273]]></artwork> 1272]]></artwork>
1274</figure> 1273 </figure>
1275<t> 1274 <t>
1276GANA is requested to amend the "GNUnet Signature Purpose" registry 1275 GANA is requested to amend the "GNUnet Signature Purpose" registry
1277as follows: 1276 as follows:
1278</t> 1277 </t>
1279<figure anchor="figure_purposenums"> 1278 <figure anchor="figure_purposenums">
1280<artwork name="" type="" align="left" alt=""><![CDATA[ 1279 <artwork name="" type="" align="left" alt=""><![CDATA[
1281Purpose | Name | References | Description 1280Purpose | Name | References | Description
1282--------+-----------------+------------+-------------------------- 1281--------+-----------------+------------+--------------------------
1283]]></artwork> 1282]]></artwork>
1284</figure> 1283 </figure>
1285</section> 1284 </section>
1286<!-- gana --> 1285 <!-- gana -->
1287<section> 1286 <section>
1288<name>Test Vectors</name> 1287 <name>Test Vectors</name>
1289</section> 1288 </section>
1290</middle> 1289 </middle>
1291<back> 1290 <back>
1292<references><name>Normative References</name> 1291 <references><name>Normative References</name>
1293 1292
1294&RFC2119; 1293 &RFC2119;
1295&RFC3629; 1294 &RFC3629;
1296&RFC4634; 1295 &RFC4634;
1297&RFC4648; 1296 &RFC4648;
1298&RFC6940; 1297 &RFC6940;
1299&RFC8126; 1298 &RFC8126;
1300&RFC8174; 1299 &RFC8174;
1301 1300
1302<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> 1301 <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>
1303 1302
1304<reference anchor="CrockfordB32" target="https://www.crockford.com/base32.html"><front><title>Base32</title><author initials="D." surname="Douglas" fullname="Crockford"> 1303 <reference anchor="CrockfordB32" target="https://www.crockford.com/base32.html"><front><title>Base32</title><author initials="D." surname="Douglas" fullname="Crockford">
1305</author><date year="2019" month="March"/></front></reference> 1304 </author><date year="2019" month="March"/></front></reference>
1306 1305
1307<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> 1306 <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>
1308 1307
1309 1308
1310 1309
1311</references> 1310 </references>
1312<references> 1311 <references>
1313<name>Informative References</name> 1312 <name>Informative References</name>
1314<reference anchor="R5N" target="https://doi.org/10.1109/ICNSS.2011.6060022"> 1313 <reference anchor="R5N" target="https://doi.org/10.1109/ICNSS.2011.6060022">
1315<front> 1314 <front>
1316<title>R5N: Randomized recursive routing for restricted-route networks</title> 1315 <title>R5N: Randomized recursive routing for restricted-route networks</title>
1317<author initials="N. S." surname="Evans" fullname="Nathan S. Evans"> 1316 <author initials="N. S." surname="Evans" fullname="Nathan S. Evans">
1318<organization>Technische Universität München</organization> 1317 <organization>Technische Universität München</organization>
1319</author> 1318 </author>
1320<author initials="C." surname="Grothoff" fullname="Christian Grothoff"> 1319 <author initials="C." surname="Grothoff" fullname="Christian Grothoff">
1321<organization>Technische Universität München</organization> 1320 <organization>Technische Universität München</organization>
1322</author> 1321 </author>
1323<date year="2011"/> 1322 <date year="2011"/>
1324</front> 1323 </front>
1325</reference> 1324 </reference>
1326<reference anchor="Kademlia" target="http://css.csail.mit.edu/6.824/2014/papers/kademlia.pdf"> 1325 <reference anchor="Kademlia" target="http://css.csail.mit.edu/6.824/2014/papers/kademlia.pdf">
1327<front> 1326 <front>
1328<title>Kademlia: A peer-to-peer information system based on the xor metric.</title> 1327 <title>Kademlia: A peer-to-peer information system based on the xor metric.</title>
1329<author initials="P." surname="Maymounkov" fullname="Petar Maymounkov"> 1328 <author initials="P." surname="Maymounkov" fullname="Petar Maymounkov">
1330</author> 1329 </author>
1331<author initials="D." surname="Mazieres" fullname="David Mazieres"> 1330 <author initials="D." surname="Mazieres" fullname="David Mazieres">
1332</author> 1331 </author>
1333<date year="2002"/> 1332 <date year="2002"/>
1334</front> 1333 </front>
1335</reference> 1334 </reference>
1336<reference anchor="cadet" target="https://doi.org/10.1109/MedHocNet.2014.6849107"> 1335 <reference anchor="cadet" target="https://doi.org/10.1109/MedHocNet.2014.6849107">
1337<front> 1336 <front>
1338<title>CADET: Confidential ad-hoc decentralized end-to-end transport</title> 1337 <title>CADET: Confidential ad-hoc decentralized end-to-end transport</title>
1339<author initials="B." surname="Polot" fullname="Bartlomiej Polot"> 1338 <author initials="B." surname="Polot" fullname="Bartlomiej Polot">
1340<organization>Technische Universität München</organization> 1339 <organization>Technische Universität München</organization>
1341</author> 1340 </author>
1342<author initials="C." surname="Grothoff" fullname="Christian Grothoff"> 1341 <author initials="C." surname="Grothoff" fullname="Christian Grothoff">
1343<organization>Technische Universität München</organization> 1342 <organization>Technische Universität München</organization>
1344</author> 1343 </author>
1345<date year="2014"/> 1344 <date year="2014"/>
1346</front> 1345 </front>
1347</reference> 1346 </reference>
1348<reference anchor="I-D.draft-schanzen-gns" target="https://datatracker.ietf.org/doc/draft-schanzen-gns/"> 1347 <reference anchor="I-D.draft-schanzen-gns" target="https://datatracker.ietf.org/doc/draft-schanzen-gns/">
1349<front> 1348 <front>
1350<title>The GNU Name System</title> 1349 <title>The GNU Name System</title>
1351<author initials="M." surname="Schanzenbach" fullname="Martin Schanzenbach"> 1350 <author initials="M." surname="Schanzenbach" fullname="Martin Schanzenbach">
1352<organization>GNUnet e.V.</organization> 1351 <organization>GNUnet e.V.</organization>
1353</author> 1352 </author>
1354<author initials="C." surname="Grothoff" fullname="Christian Grothoff"> 1353 <author initials="C." surname="Grothoff" fullname="Christian Grothoff">
1355<organization>GNUnet e.V.</organization> 1354 <organization>GNUnet e.V.</organization>
1356</author> 1355 </author>
1357<author initials="B." surname="Fix" fullname="Bernd Fix"> 1356 <author initials="B." surname="Fix" fullname="Bernd Fix">
1358<organization>GNUnet e.V.</organization> 1357 <organization>GNUnet e.V.</organization>
1359</author> 1358 </author>
1360<date year="2021"/> 1359 <date year="2021"/>
1361</front> 1360 </front>
1362</reference> 1361 </reference>
1363</references> 1362 </references>
1364<!-- Change Log 1363 <!-- Change Log
1365v00 2017-07-23 MS Initial version 1364 v00 2017-07-23 MS Initial version
1366--> 1365 -->
1367</back> 1366 </back>
1368</rfc> 1367 </rfc>
generated by cgit v1.2.3 (git 2.39.1) at 2025-03-25 11:37:44 +0000