jacob.eva/Reticulum
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated docs

Browse Source
This commit is contained in:
Mark Qvist 2021-05-17 16:06:25 +02:00
parent aa93e475a4
commit 87a2c6b1fc
11 changed files with 90 additions and 138 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
docs/.nojekyll Normal file
View File

2
docs/Makefile
View File

@ -18,3 +18,5 @@ help:
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile %: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
rm -rf html
cp -r build/html ./

8
docs/html/_sources/index.rst.txt
View File

@ -1,7 +1,7 @@
************************************* ******************************
Reticulum Network Stack Documentation Reticulum Network Stack Manual
************************************* ******************************
Welcome to the documentation for Reticulum. This document aims to provide you Welcome to the manual for Reticulum. This document aims to provide you
with all the information you need to understand Reticulum, develop programs with all the information you need to understand Reticulum, develop programs
using it, or to participate in the development of Reticulum itself. using it, or to participate in the development of Reticulum itself.

89
docs/html/_sources/understanding.rst.txt
View File

@ -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 * | 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 * | The *link request* is addressed to the destination hash of the desired destination, and
part containing the following data: The source hash *Hs* , a symmetric key *Lk* , a truncated contains the following data: The newly generated X25519 public key *LKi*. The contents
hash of a random number *Hr* , and a signature *S* of the plaintext values of *Hd* , *Hs* , *Lk* and *Hr*. 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 * | The broadcasted packet will be directed through the network according to the rules laid out
previously. 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 * | 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 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 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 * | When the destination receives the link request packet, it will decrypt it and decide whether to
request. If it is accepted, it will create a special packet called a *proof*. A *proof* is a simple accept the request. If it is accepted, the destination will also generate a new X25519 private/public
construct, consisting of a truncated hash of the message that needs to be proven, and a key pair, and perform a Diffie Hellman Key Exchange, deriving a new symmetric key that will be used
signature (made by the destination’s private key) of this hash. This *proof* effectively verifies to encrypt the channel, once it has been established.
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’ * | A *link proof* packet is now constructed and transmitted over the network. This packet is
*path tables* , the intermediary nodes can forward the proof all the way back to the source. 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 * | 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 established to the destination. It can now also use the X25519 public key contained in the
securely. *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 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 reveal any identifying information about itself. The link initiator remains completely anonymous.
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.
When using *links* , Reticulum will automatically verify anything sent over the link, and also When using *links*, Reticulum will automatically verify all data sent over the link, and can also
automates retransmissions if parts of a message was lost along the way. Due to the caching features automate retransmissions if *Resources* are used.
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.
.. _understanding-resources: .. _understanding-resources:
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 This is the purpose of the Reticulum :ref:`Resource<api-resource>`. A *Resource* can automatically
several thousand kilometers will often only have round-trip latency in the tens of milliseconds, and handle the reliable transfer of an arbitrary amount of data over an established :ref:`Link<api-link>`.
as such, traditional protocols are often designed to not store any transmitted data at intermediary Resources can auto-compress data, will handle breaking the data into individual packets, sequencing
hops. If a transmission error occurs, the sending node will simply notice the lack of a packet the transfer and reassembling the data on the other end.
acknowledgement, and retransmit the packet all the way, until it hears back from the receiver that it
got the intended data.
In bandwidth-limited and high-latency conditions, such behaviour quickly causes congestion on the :ref:`Resources<api-resource>` are programmatically very simple to use, and only requires a few lines
network, and communications that span many hops become exceedingly expensive in terms of of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
bandwidth usage, due to the higher risk of some packets failing. or stream data directly from files.
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.
.. _understanding-referencesystem: .. _understanding-referencesystem:

9
docs/html/genindex.html
View File

@ -47,7 +47,6 @@
| <a href="#I"><strong>I</strong></a> | <a href="#I"><strong>I</strong></a>
| <a href="#K"><strong>K</strong></a> | <a href="#K"><strong>K</strong></a>
| <a href="#L"><strong>L</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="#N"><strong>N</strong></a>
| <a href="#P"><strong>P</strong></a> | <a href="#P"><strong>P</strong></a>
| <a href="#R"><strong>R</strong></a> | <a href="#R"><strong>R</strong></a>
@ -214,14 +213,6 @@
</ul></td> </ul></td>
</tr></table> </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> <h2 id="N">N</h2>
<table style="width: 100%" class="indextable genindextable"><tr> <table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul> <td style="width: 33%; vertical-align: top;"><ul>

14
docs/html/index.html
View File

@ -5,7 +5,7 @@
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Reticulum Network Stack Documentation &#8212; Reticulum Network Stack 0.2.0 beta documentation</title> <title>Reticulum Network Stack Manual &#8212; 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/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" /> <link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -28,7 +28,7 @@
<a href="whatis.html" title="What is Reticulum?" <a href="whatis.html" title="What is Reticulum?"
accesskey="N">next</a> |</li> accesskey="N">next</a> |</li>
<li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.2.0 beta documentation</a> &#187;</li> <li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.2.0 beta documentation</a> &#187;</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> </ul>
</div> </div>
@ -37,9 +37,9 @@
<div class="bodywrapper"> <div class="bodywrapper">
<div class="body" role="main"> <div class="body" role="main">
<div class="section" id="reticulum-network-stack-documentation"> <div class="section" id="reticulum-network-stack-manual">
<h1>Reticulum Network Stack Documentation<a class="headerlink" href="#reticulum-network-stack-documentation" title="Permalink to this headline"></a></h1> <h1>Reticulum Network Stack Manual<a class="headerlink" href="#reticulum-network-stack-manual" title="Permalink to this headline"></a></h1>
<p>Welcome to the documentation for Reticulum. This document aims to provide you <p>Welcome to the manual for Reticulum. This document aims to provide you
with all the information you need to understand Reticulum, develop programs with all the information you need to understand Reticulum, develop programs
using it, or to participate in the development of Reticulum itself.</p> using it, or to participate in the development of Reticulum itself.</p>
<div class="section" id="table-of-contents"> <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"> <div class="sphinxsidebarwrapper">
<h3><a href="#">Table of Contents</a></h3> <h3><a href="#">Table of Contents</a></h3>
<ul> <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="#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="#current-status">Current Status</a></li>
<li><a class="reference internal" href="#caveat-emptor">Caveat Emptor</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?" <a href="whatis.html" title="What is Reticulum?"
>next</a> |</li> >next</a> |</li>
<li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.2.0 beta documentation</a> &#187;</li> <li class="nav-item nav-item-0"><a href="#">Reticulum Network Stack 0.2.0 beta documentation</a> &#187;</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> </ul>
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">

BIN
docs/html/objects.inv
View File

Binary file not shown.

15
docs/html/reference.html
View File

@ -870,21 +870,6 @@ compression, coordination and checksumming.</p>
</ul> </ul>
</dd> </dd>
</dl> </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"> <dl class="py method">
<dt class="sig sig-object py" id="RNS.Resource.advertise"> <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> <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>

2
docs/html/searchindex.js
View File

File diff suppressed because one or more lines are too long

89
docs/html/understanding.html
View File

@ -450,13 +450,14 @@ of hops, where information will be exchanged between two nodes.</p>
<ul> <ul>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">When a node in the network wants to establish verified connectivity with another node, it <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> </div>
</li> </li>
<li><div class="line-block"> <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 <div class="line">The <em>link request</em> is addressed to the destination hash of the desired destination, and
part containing the following data: The source hash <em>Hs</em> , a symmetric key <em>Lk</em> , a truncated contains the following data: The newly generated X25519 public key <em>LKi</em>. The contents
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> are encrypted with the RSA public key of the destination and tramsitted over the network.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <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 <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 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 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> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">When the destination receives the link request packet, it will decide whether to accept the <div class="line">When the destination receives the link request packet, it will decrypt it and decide whether to
request. If it is accepted, it will create a special packet called a <em>proof</em>. A <em>proof</em> is a simple accept the request. If it is accepted, the destination will also generate a new X25519 private/public
construct, consisting of a truncated hash of the message that needs to be proven, and a key pair, and perform a Diffie Hellman Key Exchange, deriving a new symmetric key that will be used
signature (made by the destination’s private key) of this hash. This <em>proof</em> effectively verifies to encrypt the channel, once it has been established.</div>
that the intended recipient got the packet, and also serves to verify the discovered path </div>
through the network. Since the <em>proof</em> hash matches the <em>path id</em> in the intermediary nodes’ </li>
<em>path tables</em> , the intermediary nodes can forward the proof all the way back to the source.</div> <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> </div>
</li> </li>
<li><div class="line-block"> <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 <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 established to the destination. It can now also use the X25519 public key contained in the
securely.</div> <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> </div>
</li> </li>
</ul> </ul>
<p>It’s important to note that this methodology ensures that the source of the request does not need to <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 reveal any identifying information about itself. The link initiator remains completely anonymous.</p>
speak. This is a huge improvement to protocols like IP, where by design, you have to reveal your <p>When using <em>links</em>, Reticulum will automatically verify all data sent over the link, and can also
own address to communicate with anyone, unless you jump through a lot of hoops to hide it. automate retransmissions if <em>Resources</em> are used.</p>
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>
</div> </div>
</div> </div>
<div class="section" id="resources"> <div class="section" id="resources">
<span id="understanding-resources"></span><h3>Resources<a class="headerlink" href="#resources" title="Permalink to this headline"></a></h3> <span id="understanding-resources"></span><h3>Resources<a class="headerlink" href="#resources" title="Permalink to this headline"></a></h3>
<p>TODO: Write</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
<p>In traditional networks, large amounts of data is rapidly exchanged with very low latency. Links of is sufficient, but for exchanging data that would require many packets, an efficient way to coordinate
several thousand kilometers will often only have round-trip latency in the tens of milliseconds, and the transfer is needed.</p>
as such, traditional protocols are often designed to not store any transmitted data at intermediary <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
hops. If a transmission error occurs, the sending node will simply notice the lack of a packet 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>.
acknowledgement, and retransmit the packet all the way, until it hears back from the receiver that it Resources can auto-compress data, will handle breaking the data into individual packets, sequencing
got the intended data.</p> the transfer and reassembling the data on the other end.</p>
<p>In bandwidth-limited and high-latency conditions, such behaviour quickly causes congestion on the <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
network, and communications that span many hops become exceedingly expensive in terms of of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
bandwidth usage, due to the higher risk of some packets failing.</p> or stream data directly from files.</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>
</div> </div>
</div> </div>
<div class="section" id="reference-system-setup"> <div class="section" id="reference-system-setup">

0
docs/index.html Normal file
View File