summaryrefslogtreecommitdiff
path: root/draft-schanzen-r5n.xml
diff options
context:
space:
mode:
Diffstat (limited to 'draft-schanzen-r5n.xml')
-rw-r--r--draft-schanzen-r5n.xml158
1 files changed, 80 insertions, 78 deletions
diff --git a/draft-schanzen-r5n.xml b/draft-schanzen-r5n.xml
index 01649ee..3bcc45c 100644
--- a/draft-schanzen-r5n.xml
+++ b/draft-schanzen-r5n.xml
@@ -156,108 +156,76 @@
156 when, they appear in all capitals, as shown here. 156 when, they appear in all capitals, as shown here.
157 </t> 157 </t>
158 </section> 158 </section>
159 <section> 159 <section anchor="terminology">
160 <name>Structure of This Document</name>
161 <t>
162 <xref target="terminology"/> gives an overview of the terminology used in
163 this document.
164 <xref target="architecture"/> then describes the overall architecture and
165 the scope of this specification.
166 <xref target="overlay"/> describes the application API, which clarifies
167 the semantics provided by R<sup>5</sup>N for applications
168 and thus is crucial as it motivates the rest of the design.
169 <xref target="underlay"/> describes the underlay interface. This is the
170 abstraction that applications must provide to R<sup>5</sup>N
171 and thus a prerequisite for using the DHT.
172 Before a DHT is usable, it must be bootstrapped.
173 Bootstrapping is described in <xref target="bootstrapping"/>.
174 Bloom filters, a key data structure used in various
175 places, are introduced in <xref target="bloom_filters" />
176 The central operation of a DHT is routing, which is
177 detailed in <xref target="routing"/>. The processing of the various
178 network messages is described in <xref target="p2p_messages"/>. Handling
179 of Blocks, including validation and storage are described
180 in <xref target="blockstorage"/>. General security considerations are detailed
181 in <xref target="security" />. IANA and GANA registry updates are listed
182 in <xref target="iana" /> and <xref target="gana"/>. The document concludes with test
183 vectors in <xref target="testvectors"/> and appendices with references.
184 </t>
185 </section>
186 </section>
187 <section anchor="terminology">
188 <name>Terminology</name> 160 <name>Terminology</name>
189 <dl> 161 <dl>
190 <dt>Peer:</dt> 162 <dt>Applications</dt>
191 <dd>
192 A host that is participating in the overlay. Peers are
193 responsible for holding some portion of the data that has been
194 stored in the overlay, and they are responsible for routing
195 messages on behalf of other hosts as needed by the Routing
196 Algorithm.
197 </dd>
198 <dt>Peer ID:</dt>
199 <dd>
200 The <tt>Peer ID</tt> is the public key which is used to authenticate
201 a peer in the underlay.
202 The Peer ID is the public key of the corresponding
203 Ed25519<xref target="ed25519" /> peer private key.
204
205 </dd>
206 <dt>Peer Address:</dt>
207 <dd>
208 The <tt>Peer Address</tt> is the identifier used on the Overlay
209 to address a peer.
210 It is a SHA-512 hash of the <tt>Peer ID</tt>.
211 </dd>
212 <dt>Key</dt>
213 <dd> 163 <dd>
214 512-bit identifier of a location in the DHT. Multiple <tt>Block</tt>s can be 164 Applications are components which directly use the DHT overlay
215 stored under the same key. <tt>Peer Addresses</tt> are valid keys. 165 interfaces. Possible applications include the GNU Name System
166 <xref target="I-D.draft-schanzen-gns"/> and the CADET transport system
167 <xref target="cadet"/>.
216 </dd> 168 </dd>
217 <dt>Neighbor:</dt> 169 <dt>Application API</dt>
218 <dd> 170 <dd>
219 A neighbor is a peer which is directly able to communicate 171 The application API exposes the core operations of the DHT overlay
220 with our peer via the <tt>Underlay Interface</tt>. 172 to applications.
173 This includes storing blocks in the DHT and retrieving blocks from the DHT.
221 </dd> 174 </dd>
222 <dt>Block:</dt> 175 <dt>Block</dt>
223 <dd> 176 <dd>
224 Variable-size unit of payload stored in the DHT 177 Variable-size unit of payload stored in the DHT
225 under a <tt>Key</tt>. Commonly also called a &quot;value&quot; when talking 178 under a <tt>Key</tt>. Commonly also called a &quot;value&quot; when talking
226 about a DHT as a &quot;key-value store&quot;. 179 about a DHT as a &quot;key-value store&quot;.
227 </dd> 180 </dd>
181 <dt>Block Storage</dt>
182 <dd>
183 The <tt>Block Storage</tt> component is used to persist and manage
184 <tt>Block</tt> data by peers.
185 It includes logic for enforcing storage quotas, caching strategies and
186 data validation.
187 </dd>
228 <dt>Block-Type:</dt> 188 <dt>Block-Type:</dt>
229 <dd> 189 <dd>
230 A unique 32-bit value identifying the data format of a <tt>Block</tt>. 190 A unique 32-bit value identifying the data format of a <tt>Block</tt>.
231 Block-Types are either private or allocated by GANA (see <xref target="gana"/>). 191 Block-Types are either private or allocated by GANA (see
192 <xref target="gana"/>).
232 </dd> 193 </dd>
233 <dt>Block Storage</dt> 194 <dt>Key</dt>
234 <dd> 195 <dd>
235 The <tt>Block Storage</tt> component is used to persist and manage <tt>Block</tt> data 196 512-bit identifier of a location in the DHT. Multiple <tt>Block</tt>s can be
236 by peers. It includes logic for enforcing storage quotas, caching strategies and 197 stored under the same key. <tt>Peer Addresses</tt> are valid keys.
237 data validation.
238 </dd> 198 </dd>
239 <dt>Responsible Peer:</dt> 199 <dt>Message Processing</dt>
240 <dd> 200 <dd>
241 The peer <tt>N</tt> that is responsible for a specific key <tt>K</tt>, as defined by 201 The Message Processing component processes requests from and
242 the <tt>SelectClosestPeer(K, P)</tt> algorithm (see <xref target="routing"/>. 202 generates responses to applications and the underlay network.
243 </dd> 203 </dd>
244 <dt>Applications</dt> 204 <dt>Neighbor</dt>
245 <dd> 205 <dd>
246 Applications are components which directly use the DHT overlay 206 A neighbor is a peer which is directly able to communicate
247 interfaces. Possible applications include the GNU Name System 207 with our peer via the <tt>Underlay Interface</tt>.
248 <xref target="I-D.draft-schanzen-gns"/> and the CADET transport system
249 <xref target="cadet"/>.
250 </dd> 208 </dd>
251 <dt>Application API</dt> 209 <dt>Peer</dt>
252 <dd> 210 <dd>
253 The application API exposes the core operations of the DHT overlay 211 A host that is participating in the overlay. Peers are
254 to applications. 212 responsible for holding some portion of the data that has been
255 This includes storing blocks in the DHT and retrieving blocks from the DHT. 213 stored in the overlay, and they are responsible for routing
214 messages on behalf of other hosts as needed by the Routing
215 Algorithm.
256 </dd> 216 </dd>
257 <dt>Message Processing</dt> 217 <dt>Peer Address</dt>
258 <dd> 218 <dd>
259 The Message Processing component processes requests from and 219 The <tt>Peer Address</tt> is the identifier used on the Overlay
260 generates responses to applications and the underlay network. 220 to address a peer.
221 It is a SHA-512 hash of the <tt>Peer ID</tt>.
222 </dd>
223 <dt>Peer ID</dt>
224 <dd>
225 The <tt>Peer ID</tt> is the public key which is used to authenticate
226 a peer in the underlay.
227 The Peer ID is the public key of the corresponding
228 Ed25519<xref target="ed25519" /> peer private key.
261 </dd> 229 </dd>
262 <dt>Routing</dt> 230 <dt>Routing</dt>
263 <dd> 231 <dd>
@@ -265,6 +233,12 @@
265 routing and peer selection logic. It facilitates the R<sup>5</sup>N routing 233 routing and peer selection logic. It facilitates the R<sup>5</sup>N routing
266 algorithm with required data structures and algorithms. 234 algorithm with required data structures and algorithms.
267 </dd> 235 </dd>
236 <dt>Responsible Peer</dt>
237 <dd>
238 The peer <tt>N</tt> that is responsible for a specific key <tt>K</tt>, as
239 defined by the <tt>SelectClosestPeer(K, P)</tt> algorithm (see
240 <xref target="routing"/>.
241 </dd>
268 <dt>Underlay Interface</dt> 242 <dt>Underlay Interface</dt>
269 <dd> 243 <dd>
270 The Underlay Interface is an abstraction layer on top of the 244 The Underlay Interface is an abstraction layer on top of the
@@ -273,6 +247,34 @@
273 TCP, UDP and TLS or advanced protocols such as GNUnet, I2P or Tor. 247 TCP, UDP and TLS or advanced protocols such as GNUnet, I2P or Tor.
274 </dd> 248 </dd>
275 </dl> 249 </dl>
250 </section>
251 <section>
252 <name>Structure of This Document</name>
253 <t>
254 <xref target="terminology"/> gives an overview of the terminology used in
255 this document.
256 <xref target="architecture"/> then describes the overall architecture and
257 the scope of this specification.
258 <xref target="overlay"/> describes the application API, which clarifies
259 the semantics provided by R<sup>5</sup>N for applications
260 and thus is crucial as it motivates the rest of the design.
261 <xref target="underlay"/> describes the underlay interface. This is the
262 abstraction that applications must provide to R<sup>5</sup>N
263 and thus a prerequisite for using the DHT.
264 Before a DHT is usable, it must be bootstrapped.
265 Bootstrapping is described in <xref target="bootstrapping"/>.
266 Bloom filters, a key data structure used in various
267 places, are introduced in <xref target="bloom_filters" />
268 The central operation of a DHT is routing, which is
269 detailed in <xref target="routing"/>. The processing of the various
270 network messages is described in <xref target="p2p_messages"/>. Handling
271 of Blocks, including validation and storage are described
272 in <xref target="blockstorage"/>. General security considerations are detailed
273 in <xref target="security" />. IANA and GANA registry updates are listed
274 in <xref target="iana" /> and <xref target="gana"/>. The document concludes with test
275 vectors in <xref target="testvectors"/> and appendices with references.
276 </t>
277 </section>
276 </section> 278 </section>
277 <section anchor="architecture" numbered="true" toc="default"> 279 <section anchor="architecture" numbered="true" toc="default">
278 <name>Architecture</name> 280 <name>Architecture</name>