kopia lustrzana https://github.com/markqvist/reticulum
Updated docs
Mark Qvist
rodzic
aa93e475a4
commit
87a2c6b1fc
|
|
@ -18,3 +18,5 @@ help:
|
|||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
rm -rf html
|
||||
cp -r build/html ./
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
*************************************
|
||||
Reticulum Network Stack Documentation
|
||||
*************************************
|
||||
Welcome to the documentation for Reticulum. This document aims to provide you
|
||||
******************************
|
||||
Reticulum Network Stack Manual
|
||||
******************************
|
||||
Welcome to the manual for Reticulum. This document aims to provide you
|
||||
with all the information you need to understand Reticulum, develop programs
|
||||
using it, or to participate in the development of Reticulum itself.
|
||||
|
||||
|
|
|
|||
|
|
@ -403,11 +403,12 @@ of hops, where information will be exchanged between two nodes.
|
|||
|
||||
|
||||
* | When a node in the network wants to establish verified connectivity with another node, it
|
||||
will create a *link request* packet, and broadcast it.
|
||||
will randomly generate a new X25519 private/public key pair. It then creates a *link request*
|
||||
packet, and broadcast it.
|
||||
|
||||
* | The *link request* packet contains the destination hash *Hd* , and an asymmetrically encrypted
|
||||
part containing the following data: The source hash *Hs* , a symmetric key *Lk* , a truncated
|
||||
hash of a random number *Hr* , and a signature *S* of the plaintext values of *Hd* , *Hs* , *Lk* and *Hr*.
|
||||
* | The *link request* is addressed to the destination hash of the desired destination, and
|
||||
contains the following data: The newly generated X25519 public key *LKi*. The contents
|
||||
are encrypted with the RSA public key of the destination and tramsitted over the network.
|
||||
|
||||
* | The broadcasted packet will be directed through the network according to the rules laid out
|
||||
previously.
|
||||
|
|
@ -415,69 +416,51 @@ of hops, where information will be exchanged between two nodes.
|
|||
* | Any node that forwards the link request will store a *link id* in it’s *link table* , along with the
|
||||
amount of hops the packet had taken when received. The link id is a hash of the entire link
|
||||
request packet. If the path is not *proven* within some set amount of time, the entry will be
|
||||
dropped from the table again.
|
||||
dropped from the *link table* again.
|
||||
|
||||
* | When the destination receives the link request packet, it will decide whether to accept the
|
||||
request. If it is accepted, it will create a special packet called a *proof*. A *proof* is a simple
|
||||
construct, consisting of a truncated hash of the message that needs to be proven, and a
|
||||
signature (made by the destination’s private key) of this hash. This *proof* effectively verifies
|
||||
that the intended recipient got the packet, and also serves to verify the discovered path
|
||||
through the network. Since the *proof* hash matches the *path id* in the intermediary nodes’
|
||||
*path tables* , the intermediary nodes can forward the proof all the way back to the source.
|
||||
* | When the destination receives the link request packet, it will decrypt it and decide whether to
|
||||
accept the request. If it is accepted, the destination will also generate a new X25519 private/public
|
||||
key pair, and perform a Diffie Hellman Key Exchange, deriving a new symmetric key that will be used
|
||||
to encrypt the channel, once it has been established.
|
||||
|
||||
* | A *link proof* packet is now constructed and transmitted over the network. This packet is
|
||||
addressed to the *link id* of the *link*. It contains the following data: The newly generated X25519
|
||||
public key *LKr* and an RSA-1024 signature of the *link id* and *LKr*.
|
||||
|
||||
* | By verifying this *link proof* packet, all nodes that originally transported the *link request*
|
||||
packet to the destination from the originator can now verify that the intended destination received
|
||||
the request and accepted it, and that the path they chose for forwarding the request was valid.
|
||||
In sucessfully carrying out this verification, the transporting nodes marks the link as active.
|
||||
An abstract bi-directional communication channel has now been established along a path in the network.
|
||||
|
||||
* | When the source receives the *proof* , it will know unequivocally that a verified path has been
|
||||
established to the destination, and that information can now be exchanged reliably and
|
||||
securely.
|
||||
established to the destination. It can now also use the X25519 public key contained in the
|
||||
*link proof* to perform it's own Diffie Hellman Key Exchange and derive the symmetric key
|
||||
that is used to encrypt the channel. Information can now be exchanged reliably and securely.
|
||||
|
||||
It’s important to note that this methodology ensures that the source of the request does not need to
|
||||
reveal any identifying information. Only the intended destination will know “who called”, so to
|
||||
speak. This is a huge improvement to protocols like IP, where by design, you have to reveal your
|
||||
own address to communicate with anyone, unless you jump through a lot of hoops to hide it.
|
||||
Reticulum offers initiator anonymity by design.
|
||||
reveal any identifying information about itself. The link initiator remains completely anonymous.
|
||||
|
||||
When using *links* , Reticulum will automatically verify anything sent over the link, and also
|
||||
automates retransmissions if parts of a message was lost along the way. Due to the caching features
|
||||
of Reticulum, such a retransmission does not need to travel the entire length of an established path.
|
||||
If a packet is lost on the 8th hop of a 12 hop path, it can be fetched from the last hop that received it
|
||||
reliably.
|
||||
When using *links*, Reticulum will automatically verify all data sent over the link, and can also
|
||||
automate retransmissions if *Resources* are used.
|
||||
|
||||
.. _understanding-resources:
|
||||
|
||||
Resources
|
||||
---------
|
||||
|
||||
TODO: Write
|
||||
For exchanging small amounts of data over a Reticulum network, the :ref:`Packet<api-packet>` interface
|
||||
is sufficient, but for exchanging data that would require many packets, an efficient way to coordinate
|
||||
the transfer is needed.
|
||||
|
||||
In traditional networks, large amounts of data is rapidly exchanged with very low latency. Links of
|
||||
several thousand kilometers will often only have round-trip latency in the tens of milliseconds, and
|
||||
as such, traditional protocols are often designed to not store any transmitted data at intermediary
|
||||
hops. If a transmission error occurs, the sending node will simply notice the lack of a packet
|
||||
acknowledgement, and retransmit the packet all the way, until it hears back from the receiver that it
|
||||
got the intended data.
|
||||
This is the purpose of the Reticulum :ref:`Resource<api-resource>`. A *Resource* can automatically
|
||||
handle the reliable transfer of an arbitrary amount of data over an established :ref:`Link<api-link>`.
|
||||
Resources can auto-compress data, will handle breaking the data into individual packets, sequencing
|
||||
the transfer and reassembling the data on the other end.
|
||||
|
||||
In bandwidth-limited and high-latency conditions, such behaviour quickly causes congestion on the
|
||||
network, and communications that span many hops become exceedingly expensive in terms of
|
||||
bandwidth usage, due to the higher risk of some packets failing.
|
||||
|
||||
Reticulum alleviates this in part with it’s *path* discovery methodology, and in part by implementing
|
||||
*resource* caching at all nodes that can support it. Network operation can be made much more
|
||||
efficient by caching everything for a period of time, and given the availability of cheap memory and
|
||||
storage, this is a very welcome tradeoff. A gigabyte of memory can store millions of Reticulum
|
||||
packets, and since everything is encrypted by default, the storing poses very little privacy risk.
|
||||
|
||||
In a Reticulum network, any node that is able to do so, should cache as many packets as it’s
|
||||
memory will allow for. When a packet is received, a timestamp and a hash of the packet is stored
|
||||
along with the full packet itself, and it will be kept in storage until the allocated cache storage is
|
||||
full, whereupon the packet that was last accessed in the cache will be deleted. If a packet is accessed
|
||||
from the cache, it’s timestamp will be updated to the current time, to ensure that packets that are
|
||||
used stay in the cache, and packets that are not used are dropped from memory.
|
||||
|
||||
Some packet types are stored in separate caching tables, that allow easier lookup for other nodes.
|
||||
For example, an announce is stored in a way, that allows other nodes to request the public key for a
|
||||
certain destination, and as such the network as a whole operates as a distributed key ledger.
|
||||
|
||||
For more details on how the caching works and is used, see the reference implementation source
|
||||
code.
|
||||
:ref:`Resources<api-resource>` are programmatically very simple to use, and only requires a few lines
|
||||
of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
|
||||
or stream data directly from files.
|
||||
|
||||
.. _understanding-referencesystem:
|
||||
|
||||
|
|
|
|||
|
|
@ -47,7 +47,6 @@
|
|||
| <a href="#I"><strong>I</strong></a>
|
||||
| <a href="#K"><strong>K</strong></a>
|
||||
| <a href="#L"><strong>L</strong></a>
|
||||
| <a href="#M"><strong>M</strong></a>
|
||||
| <a href="#N"><strong>N</strong></a>
|
||||
| <a href="#P"><strong>P</strong></a>
|
||||
| <a href="#R"><strong>R</strong></a>
|
||||
|
|
@ -214,14 +213,6 @@
|
|||
</ul></td>
|
||||
</tr></table>
|
||||
|
||||
<h2 id="M">M</h2>
|
||||
<table style="width: 100%" class="indextable genindextable"><tr>
|
||||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
<li><a href="reference.html#RNS.Resource.MAX_EFFICIENT_SIZE">MAX_EFFICIENT_SIZE (RNS.Resource attribute)</a>
|
||||
</li>
|
||||
</ul></td>
|
||||
</tr></table>
|
||||
|
||||
<h2 id="N">N</h2>
|
||||
<table style="width: 100%" class="indextable genindextable"><tr>
|
||||
<td style="width: 33%; vertical-align: top;"><ul>
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@
|
|||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>Reticulum Network Stack Documentation — Reticulum Network Stack 0.2.0 beta documentation</title>
|
||||
<title>Reticulum Network Stack Manual — Reticulum Network Stack 0.2.0 beta documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
|
||||
<link rel="stylesheet" type="text/css" href="_static/classic.css" />
|
||||
|
||||
|
|
@ -28,7 +28,7 @@
|
|||
<a href="whatis.html" title="What is Reticulum?"
|
||||
accesskey="N">next</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.2.0 beta documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href="">Reticulum Network Stack Documentation</a></li>
|
||||
<li class="nav-item nav-item-this"><a href="">Reticulum Network Stack Manual</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
|
|
@ -37,9 +37,9 @@
|
|||
<div class="bodywrapper">
|
||||
<div class="body" role="main">
|
||||
|
||||
<div class="section" id="reticulum-network-stack-documentation">
|
||||
<h1>Reticulum Network Stack Documentation<a class="headerlink" href="#reticulum-network-stack-documentation" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Welcome to the documentation for Reticulum. This document aims to provide you
|
||||
<div class="section" id="reticulum-network-stack-manual">
|
||||
<h1>Reticulum Network Stack Manual<a class="headerlink" href="#reticulum-network-stack-manual" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Welcome to the manual for Reticulum. This document aims to provide you
|
||||
with all the information you need to understand Reticulum, develop programs
|
||||
using it, or to participate in the development of Reticulum itself.</p>
|
||||
<div class="section" id="table-of-contents">
|
||||
|
|
@ -134,7 +134,7 @@ using it, or to participate in the development of Reticulum itself.</p>
|
|||
<div class="sphinxsidebarwrapper">
|
||||
<h3><a href="#">Table of Contents</a></h3>
|
||||
<ul>
|
||||
<li><a class="reference internal" href="#">Reticulum Network Stack Documentation</a><ul>
|
||||
<li><a class="reference internal" href="#">Reticulum Network Stack Manual</a><ul>
|
||||
<li><a class="reference internal" href="#table-of-contents">Table of Contents</a></li>
|
||||
<li><a class="reference internal" href="#current-status">Current Status</a></li>
|
||||
<li><a class="reference internal" href="#caveat-emptor">Caveat Emptor</a></li>
|
||||
|
|
@ -177,7 +177,7 @@ using it, or to participate in the development of Reticulum itself.</p>
|
|||
<a href="whatis.html" title="What is Reticulum?"
|
||||
>next</a> |</li>
|
||||
<li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.2.0 beta documentation</a> »</li>
|
||||
<li class="nav-item nav-item-this"><a href="">Reticulum Network Stack Documentation</a></li>
|
||||
<li class="nav-item nav-item-this"><a href="">Reticulum Network Stack Manual</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="footer" role="contentinfo">
|
||||
|
|
|
|||
Plik binarny nie jest wyświetlany.
|
|
@ -870,21 +870,6 @@ compression, coordination and checksumming.</p>
|
|||
</ul>
|
||||
</dd>
|
||||
</dl>
|
||||
<dl class="py attribute">
|
||||
<dt class="sig sig-object py" id="RNS.Resource.MAX_EFFICIENT_SIZE">
|
||||
<span class="sig-name descname"><span class="pre">MAX_EFFICIENT_SIZE</span></span><em class="property"> <span class="pre">=</span> <span class="pre">16777216</span></em><a class="headerlink" href="#RNS.Resource.MAX_EFFICIENT_SIZE" title="Permalink to this definition">¶</a></dt>
|
||||
<dd><p>This is an indication of what the
|
||||
maximum size a resource should be, if
|
||||
it is to be handled within reasonable
|
||||
time constraint, even on small systems.</p>
|
||||
<p>A small system in this regard is
|
||||
defined as a Raspberry Pi, which should
|
||||
be able to compress, encrypt and hash-map
|
||||
the resource in about 10 seconds.</p>
|
||||
<p>This constant will be used when determining
|
||||
how to sequence the sending of large resources.</p>
|
||||
</dd></dl>
|
||||
|
||||
<dl class="py method">
|
||||
<dt class="sig sig-object py" id="RNS.Resource.advertise">
|
||||
<span class="sig-name descname"><span class="pre">advertise</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Resource.advertise" title="Permalink to this definition">¶</a></dt>
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -450,13 +450,14 @@ of hops, where information will be exchanged between two nodes.</p>
|
|||
<ul>
|
||||
<li><div class="line-block">
|
||||
<div class="line">When a node in the network wants to establish verified connectivity with another node, it
|
||||
will create a <em>link request</em> packet, and broadcast it.</div>
|
||||
will randomly generate a new X25519 private/public key pair. It then creates a <em>link request</em>
|
||||
packet, and broadcast it.</div>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">The <em>link request</em> packet contains the destination hash <em>Hd</em> , and an asymmetrically encrypted
|
||||
part containing the following data: The source hash <em>Hs</em> , a symmetric key <em>Lk</em> , a truncated
|
||||
hash of a random number <em>Hr</em> , and a signature <em>S</em> of the plaintext values of <em>Hd</em> , <em>Hs</em> , <em>Lk</em> and <em>Hr</em>.</div>
|
||||
<div class="line">The <em>link request</em> is addressed to the destination hash of the desired destination, and
|
||||
contains the following data: The newly generated X25519 public key <em>LKi</em>. The contents
|
||||
are encrypted with the RSA public key of the destination and tramsitted over the network.</div>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
|
|
@ -468,66 +469,56 @@ previously.</div>
|
|||
<div class="line">Any node that forwards the link request will store a <em>link id</em> in it’s <em>link table</em> , along with the
|
||||
amount of hops the packet had taken when received. The link id is a hash of the entire link
|
||||
request packet. If the path is not <em>proven</em> within some set amount of time, the entry will be
|
||||
dropped from the table again.</div>
|
||||
dropped from the <em>link table</em> again.</div>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">When the destination receives the link request packet, it will decide whether to accept the
|
||||
request. If it is accepted, it will create a special packet called a <em>proof</em>. A <em>proof</em> is a simple
|
||||
construct, consisting of a truncated hash of the message that needs to be proven, and a
|
||||
signature (made by the destination’s private key) of this hash. This <em>proof</em> effectively verifies
|
||||
that the intended recipient got the packet, and also serves to verify the discovered path
|
||||
through the network. Since the <em>proof</em> hash matches the <em>path id</em> in the intermediary nodes’
|
||||
<em>path tables</em> , the intermediary nodes can forward the proof all the way back to the source.</div>
|
||||
<div class="line">When the destination receives the link request packet, it will decrypt it and decide whether to
|
||||
accept the request. If it is accepted, the destination will also generate a new X25519 private/public
|
||||
key pair, and perform a Diffie Hellman Key Exchange, deriving a new symmetric key that will be used
|
||||
to encrypt the channel, once it has been established.</div>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">A <em>link proof</em> packet is now constructed and transmitted over the network. This packet is
|
||||
addressed to the <em>link id</em> of the <em>link</em>. It contains the following data: The newly generated X25519
|
||||
public key <em>LKr</em> and an RSA-1024 signature of the <em>link id</em> and <em>LKr</em>.</div>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">By verifying this <em>link proof</em> packet, all nodes that originally transported the <em>link request</em>
|
||||
packet to the destination from the originator can now verify that the intended destination received
|
||||
the request and accepted it, and that the path they chose for forwarding the request was valid.
|
||||
In sucessfully carrying out this verification, the transporting nodes marks the link as active.
|
||||
An abstract bi-directional communication channel has now been established along a path in the network.</div>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">When the source receives the <em>proof</em> , it will know unequivocally that a verified path has been
|
||||
established to the destination, and that information can now be exchanged reliably and
|
||||
securely.</div>
|
||||
established to the destination. It can now also use the X25519 public key contained in the
|
||||
<em>link proof</em> to perform it’s own Diffie Hellman Key Exchange and derive the symmetric key
|
||||
that is used to encrypt the channel. Information can now be exchanged reliably and securely.</div>
|
||||
</div>
|
||||
</li>
|
||||
</ul>
|
||||
<p>It’s important to note that this methodology ensures that the source of the request does not need to
|
||||
reveal any identifying information. Only the intended destination will know “who called”, so to
|
||||
speak. This is a huge improvement to protocols like IP, where by design, you have to reveal your
|
||||
own address to communicate with anyone, unless you jump through a lot of hoops to hide it.
|
||||
Reticulum offers initiator anonymity by design.</p>
|
||||
<p>When using <em>links</em> , Reticulum will automatically verify anything sent over the link, and also
|
||||
automates retransmissions if parts of a message was lost along the way. Due to the caching features
|
||||
of Reticulum, such a retransmission does not need to travel the entire length of an established path.
|
||||
If a packet is lost on the 8th hop of a 12 hop path, it can be fetched from the last hop that received it
|
||||
reliably.</p>
|
||||
reveal any identifying information about itself. The link initiator remains completely anonymous.</p>
|
||||
<p>When using <em>links</em>, Reticulum will automatically verify all data sent over the link, and can also
|
||||
automate retransmissions if <em>Resources</em> are used.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="resources">
|
||||
<span id="understanding-resources"></span><h3>Resources<a class="headerlink" href="#resources" title="Permalink to this headline">¶</a></h3>
|
||||
<p>TODO: Write</p>
|
||||
<p>In traditional networks, large amounts of data is rapidly exchanged with very low latency. Links of
|
||||
several thousand kilometers will often only have round-trip latency in the tens of milliseconds, and
|
||||
as such, traditional protocols are often designed to not store any transmitted data at intermediary
|
||||
hops. If a transmission error occurs, the sending node will simply notice the lack of a packet
|
||||
acknowledgement, and retransmit the packet all the way, until it hears back from the receiver that it
|
||||
got the intended data.</p>
|
||||
<p>In bandwidth-limited and high-latency conditions, such behaviour quickly causes congestion on the
|
||||
network, and communications that span many hops become exceedingly expensive in terms of
|
||||
bandwidth usage, due to the higher risk of some packets failing.</p>
|
||||
<p>Reticulum alleviates this in part with it’s <em>path</em> discovery methodology, and in part by implementing
|
||||
<em>resource</em> caching at all nodes that can support it. Network operation can be made much more
|
||||
efficient by caching everything for a period of time, and given the availability of cheap memory and
|
||||
storage, this is a very welcome tradeoff. A gigabyte of memory can store millions of Reticulum
|
||||
packets, and since everything is encrypted by default, the storing poses very little privacy risk.</p>
|
||||
<p>In a Reticulum network, any node that is able to do so, should cache as many packets as it’s
|
||||
memory will allow for. When a packet is received, a timestamp and a hash of the packet is stored
|
||||
along with the full packet itself, and it will be kept in storage until the allocated cache storage is
|
||||
full, whereupon the packet that was last accessed in the cache will be deleted. If a packet is accessed
|
||||
from the cache, it’s timestamp will be updated to the current time, to ensure that packets that are
|
||||
used stay in the cache, and packets that are not used are dropped from memory.</p>
|
||||
<p>Some packet types are stored in separate caching tables, that allow easier lookup for other nodes.
|
||||
For example, an announce is stored in a way, that allows other nodes to request the public key for a
|
||||
certain destination, and as such the network as a whole operates as a distributed key ledger.</p>
|
||||
<p>For more details on how the caching works and is used, see the reference implementation source
|
||||
code.</p>
|
||||
<p>For exchanging small amounts of data over a Reticulum network, the <a class="reference internal" href="reference.html#api-packet"><span class="std std-ref">Packet</span></a> interface
|
||||
is sufficient, but for exchanging data that would require many packets, an efficient way to coordinate
|
||||
the transfer is needed.</p>
|
||||
<p>This is the purpose of the Reticulum <a class="reference internal" href="reference.html#api-resource"><span class="std std-ref">Resource</span></a>. A <em>Resource</em> can automatically
|
||||
handle the reliable transfer of an arbitrary amount of data over an established <a class="reference internal" href="reference.html#api-link"><span class="std std-ref">Link</span></a>.
|
||||
Resources can auto-compress data, will handle breaking the data into individual packets, sequencing
|
||||
the transfer and reassembling the data on the other end.</p>
|
||||
<p><a class="reference internal" href="reference.html#api-resource"><span class="std std-ref">Resources</span></a> are programmatically very simple to use, and only requires a few lines
|
||||
of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
|
||||
or stream data directly from files.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="reference-system-setup">
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue