Mirror/Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2026-07-26 09:38:14 -07:00
Code Issues Packages Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
Mark Qvist
2021-05-20 16:06:12 +02:00
parent f18fb35aba
commit 9c995b33dd
11 changed files with 132 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/manual/understanding.html
+47 -14
View File
@@ -333,10 +333,38 @@ destination, and <em>resources</em> that help make reliable data transfer more e
<p>In networks with changing topology and trustless connectivity, nodes need a way to establish
<em>verified connectivity</em> with each other. Since the network is assumed to be trustless, Reticulum
must provide a way to guarantee that the peer you are communicating with is actually who you
expect. To do this, the following process is employed:</p>
expect. Reticulum offers two ways to do this.</p>
<p>For exchanges of small amounts of information, Reticulum offers the <em>Packet</em> API, which works exactly like you would expect - on a per packet level. The following process is employed when sending a packet:</p>
<ul>
<li><div class="line-block">
<div class="line">First, the node that wishes to establish connectivity will send out a special packet, that
<div class="line">A packet is always created with an associated destination and some payload data. When the packet is sent to a <em>single</em> destination type, Reticulum will automatically create an ephemeral encryption key, perform an ECDH key exchange with the destinations public key, and encrypt the information.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">It is important to note that this key exchange does not require any network traffic. The sender already knows the public key of the destination from an earlier received <em>announce</em>, and can thus perform the ECDH key exchange locally.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">The public key part of the newly generated ephemeral key is included with the encrypted token, and sent along with the encrypted payload data in the packet.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">When the destination receives the packet, it can itself perform an ECDH key exchange and decrypt the packet.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">A new ephemeral key is used for every packet sent in this way, and forward secrecy is guaranteed on a per packet level.</div>
</div>
</li>
<li><div class="line-block">
<div class="line">In case the packet is addressed to a <em>group</em> destination type, the packet will be encrypted with the pre-shared AES-128 key associated with the destination. In case the packet is addressed to a <em>plain</em> destination type, the payload data will not be encrypted. Neither of these two destination types offer forward secrecy. In general, it is recommended to always use the <em>single</em> destination type, unless it is strictly necessary to use one of the others.</div>
</div>
</li>
</ul>
<p>For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the <em>Link</em> API. To establish a <em>link</em>, the following process is employed:</p>
<ul>
<li><div class="line-block">
<div class="line">First, the node that wishes to establish a link will send out a special packet, that
traverses the network and locates the desired destination. Along the way, the nodes that
forward the packet will take note of this <em>link request</em>.</div>
</div>
@@ -368,18 +396,18 @@ recipient.</div>
</div>
</li>
</ul>
<p>In a moment, we will discuss the specifics of how this methodology is implemented, but let’s first
recap what purposes this serves. We first ensure that the node answering our request is actually the
one we want to communicate with, and not a malicious actor pretending to be so. At the same time
we establish an efficient encrypted channel. The setup of this is relatively cheap in terms of
bandwidth, so it can be used just for a short exchange, and then recreated as needed, which will also
rotate encryption keys, but the link can also be kept alive for longer periods of time, if this is
<p>In a moment, we will discuss the details of how this methodology is implemented, but let’s first
recap what purposes this methodology serves. We first ensure that the node answering our request
is actually the one we want to communicate with, and not a malicious actor pretending to be so.
At the same time we establish an efficient encrypted channel. The setup of this is relatively cheap in
terms of bandwidth, so it can be used just for a short exchange, and then recreated as needed, which will
also rotate encryption keys, but the link can also be kept alive for longer periods of time, if this is
more suitable to the application. The amount of bandwidth used on keeping a link open is practically
negligible. The procedure also inserts the <em>link id</em> , a hash calculated from the link request packet,
into the memory of forwarding nodes, which means that the communicating nodes can thereafter reach each
other simply by referring to this <em>link id</em>.</p>
<div class="section" id="step-1-pathfinding">
<h4>Step 1: Pathfinding<a class="headerlink" href="#step-1-pathfinding" title="Permalink to this headline"></a></h4>
<div class="section" id="pathfinding-in-detail">
<h4>Pathfinding in Detail<a class="headerlink" href="#pathfinding-in-detail" title="Permalink to this headline"></a></h4>
<p>The pathfinding method builds on the <em>announce</em> functionality discussed earlier. When an announce
is sent out by a node, it will be forwarded by any node receiving it, but according to some specific
rules:</p>
@@ -440,8 +468,8 @@ distance of <em>Lavg =</em> 15 kilometers, an announce will be able to propagate
kilometers in 34 minutes, and a <em>maximum announce radius</em> of 270 kilometers in approximately 3
days.</p>
</div>
<div class="section" id="step-2-link-establishment">
<h4>Step 2: Link Establishment<a class="headerlink" href="#step-2-link-establishment" title="Permalink to this headline"></a></h4>
<div class="section" id="link-establishment-in-detail">
<h4>Link Establishment in Detail<a class="headerlink" href="#link-establishment-in-detail" title="Permalink to this headline"></a></h4>
<p>After seeing how the conditions for finding a path through the network are created, we will now
explore how two nodes can establish reliable communications over multiple hops. The <em>link</em> in
Reticulum terminology should not be viewed as a direct node-to-node link on the physical layer, but
@@ -511,6 +539,10 @@ reveal any identifying information about itself. The link initiator remains comp
<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 class="section" id="proven-delivery">
<h4>Proven Delivery<a class="headerlink" href="#proven-delivery" title="Permalink to this headline"></a></h4>
<p>TODO: Write</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>
@@ -741,8 +773,9 @@ proof 11
</li>
<li><a class="reference internal" href="#reticulum-transport">Reticulum Transport</a><ul>
<li><a class="reference internal" href="#reaching-the-destination">Reaching the Destination</a><ul>
<li><a class="reference internal" href="#step-1-pathfinding">Step 1: Pathfinding</a></li>
<li><a class="reference internal" href="#step-2-link-establishment">Step 2: Link Establishment</a></li>
<li><a class="reference internal" href="#pathfinding-in-detail">Pathfinding in Detail</a></li>
<li><a class="reference internal" href="#link-establishment-in-detail">Link Establishment in Detail</a></li>
<li><a class="reference internal" href="#proven-delivery">Proven Delivery</a></li>
</ul>
</li>
<li><a class="reference internal" href="#resources">Resources</a></li>