William/Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2024-11-22 21:50:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
Mark Qvist 2022-04-28 14:56:52 +02:00
parent 600bd0e64d
commit 8e4bfbbd94
4 changed files with 169 additions and 162 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
docs/manual/_sources/understanding.rst.txt
View File

@ -287,8 +287,8 @@ In Reticulum, destinations are allowed to move around the network at will. This
protocols such as IP, where an address is always expected to stay within the network segment it was assigned in. protocols such as IP, where an address is always expected to stay within the network segment it was assigned in.
This limitation does not exist in Reticulum, and any destination is *completely portable* over the entire topography This limitation does not exist in Reticulum, and any destination is *completely portable* over the entire topography
of the network, and *can even be moved to other Reticulum networks* than the one it was created in, and of the network, and *can even be moved to other Reticulum networks* than the one it was created in, and
still be reachable. To update it's reachability, a destination simply needs to send an announce on any still become reachable. To update it's reachability, a destination simply needs to send an announce on any
networks it is part of. networks it is part of. After a short while, it will be globally reachable in the network.
Seeing how *single* destinations are always tied to a private/public key pair leads us to the next topic. Seeing how *single* destinations are always tied to a private/public key pair leads us to the next topic.
@ -298,21 +298,22 @@ Identities
---------- ----------
In Reticulum, an *identity* does not necessarily represent a personal identity, but is an abstraction that In Reticulum, an *identity* does not necessarily represent a personal identity, but is an abstraction that
can represent any kind of *verified entity*. This could very well be a person, but it could also be the can represent any kind of *verifiable entity*. This could very well be a person, but it could also be the
control interface of a machine, a program, robot, computer, sensor or something else entirely. In control interface of a machine, a program, robot, computer, sensor or something else entirely. In
general, any kind of agent that can act, or be acted upon, or store or manipulate information, can be general, any kind of agent that can act, or be acted upon, or store or manipulate information, can be
represented as an identity. An *identity* can be used to create any number of destinations. represented as an identity. An *identity* can be used to create any number of destinations.
As we have seen, a *single* destination will always have an *identity* tied to it, but not *plain* or *group* A *single* destination will always have an *identity* tied to it, but not *plain* or *group*
destinations. Destinations and identities share a multilateral connection. You can create a destinations. Destinations and identities share a multilateral connection. You can create a
destination, and if it is not connected to an identity upon creation, it will just create a new one to use destination, and if it is not connected to an identity upon creation, it will just create a new one to use
automatically. This may be desirable in some situations, but often you will probably want to create automatically. This may be desirable in some situations, but often you will probably want to create
the identity first, and then use it to create new destinations. the identity first, and then use it to create new destinations.
Building upon the simple messenger example, we could use an identity to represent the user of the As an example, we could use an identity to represent the user of a messaging application.
application. Destinations created will then be linked to this identity to allow communication to Destinations can then be created by this identity to allow communication to reach the user.
reach the user. In all cases it is of great importance to store the private keys associated with any In all cases it is of great importance to store the private keys associated with any
Reticulum Identity securely and privately. Reticulum Identity securely and privately, since obtaining access to the identity keys equals
obtaining access and controlling reachability to any destinations created by that identity.
.. _understanding-gettingfurther: .. _understanding-gettingfurther:
@ -331,20 +332,16 @@ In the following sections, two concepts that allow this will be introduced, *pat
Reticulum Transport Reticulum Transport
=================== ===================
The term routing has been purposefully avoided until now. The current methods of routing used in IP-based The methods of routing used in traditional networks are fundamentally incompatible with the physical medium
networks are fundamentally incompatible with the physical link types that Reticulum was designed to handle. types and circumstances that Reticulum was designed to handle. These mechanisms mostly assume trust at the physical layer,
These routing methodologies assume trust at the physical layer, and often needs a lot more bandwidth than and often needs a lot more bandwidth than Reticulum can assume is available. Since Reticulum is designed to
Reticulum can assume is available. survive running over open radio spectrum, no such trust can be assumed, and bandwidth is often very limited.
Since Reticulum is designed to survive running over open radio spectrum, no such trust exists, and bandwidth To overcome such challenges, Reticulum’s *Transport* system uses asymmetric elliptic curve cryptography to
is often very limited. Existing routing protocols like BGP or OSPF carry too much overhead to be practically
useable over bandwidth-limited, high-latency links.
To overcome such challenges, Reticulum’s *Transport* system uses public-key cryptography to
implement the concept of *paths* that allow discovery of how to get information closer to a certain implement the concept of *paths* that allow discovery of how to get information closer to a certain
destination. It is important to note that no single node in a Reticulum network knows the complete destination. It is important to note that no single node in a Reticulum network knows the complete
path to a destination. Every Transport node participating in a Reticulum network will only path to a destination. Every Transport node participating in a Reticulum network will only
know what the most direct way to get a packet one hop closer to it's destination is. know the most direct way to get a packet one hop closer to it's destination.
.. _understanding-nodetypes: .. _understanding-nodetypes:
@ -354,13 +351,13 @@ Node Types
Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network
are *Reticulum Instances*, and some are alo *Transport Nodes*. If a system running Reticulum is fixed in are *Reticulum Instances*, and some are alo *Transport Nodes*. If a system running Reticulum is fixed in
one place, and is intended to be kept available most of the time, it can be a *Transport Node*, by enabling one place, and is intended to be kept available most of the time, it is a good contender to be a *Transport Node*.
it in the configuration.
Any Reticulum Instance can become a Transport Node by enabling it in the configuration.
This distinction is made by the user configuring the node, and is used to determine what nodes on the This distinction is made by the user configuring the node, and is used to determine what nodes on the
network will help forward traffic, and what nodes rely on other nodes for wider connectivity. network will help forward traffic, and what nodes rely on other nodes for wider connectivity.
If a node is a *Instance* it should be given the configuration directive ``enable_transport = No``, which If a node is an *Instance* it should be given the configuration directive ``enable_transport = No``, which
is the default setting. is the default setting.
If it is a *Transport Node*, it should be given the configuration directive ``enable_transport = Yes``. If it is a *Transport Node*, it should be given the configuration directive ``enable_transport = Yes``.
@ -371,37 +368,37 @@ If it is a *Transport Node*, it should be given the configuration directive ``en
The Announce Mechanism in Detail The Announce Mechanism in Detail
-------------------------------- --------------------------------
When an *announce* is transmitted by from a Reticulum instance, it will be forwarded by any transport node receiving it, but When an *announce* for a destination is transmitted by from a Reticulum instance, it will be forwarded by
according to some specific rules: any transport node receiving it, but according to some specific rules:
* | If this exact announce has already been received before, ignore it. * | If this exact announce has already been received before, ignore it.
* | If not, record into a table which node the announce was received from, and how many times in * | If not, record into a table which Transport Node the announce was received from, and how many times in
total it has been retransmitted to get here. total it has been retransmitted to get here.
* | If the announce has been retransmitted *m+1* times, it will not be forwarded. By default, *m* is * | If the announce has been retransmitted *m+1* times, it will not be forwarded any more. By default, *m* is
set to 128. set to 128.
* | The announce will be assigned a delay *d* = c\ :sup:`h` seconds, where *c* is a decay constant, and *h* is the amount of times this packet has already been forwarded. * | After a randomised delay, the announce will be retransmitted on all interfaces that have bandwidth
available for processing announces. By default, the maximum bandwidth allocation for processing
announces is set at 2%, but can be configured on a per-interface basis.
* | The packet will be given a priority *p = 1/d*. * | If any given interface does not have enough bandwidth available for retransmitting the announce,
the announce will be assigned a priority inversely proportional to it's hop count, and be inserted
into a queue managed by the interface.
* | If at least *d* seconds has passed since the announce was received, and no other packets with a * | When the interface has bandwidth available for processing an announce, it will prioritise announces
priority higher than *p* are waiting in the queue, and the channel is for destinations that are closest in terms of hops, thus prioritising reachability and connectivity
not utilized by other traffic, the announce will be forwarded. of local nodes, even on slow networks that connect to wider and faster networks.
* | If no other nodes are heard retransmitting the announce with a greater hop count than when * | After the announce has been re-transmitted, and if no other nodes are heard retransmitting the announce
it left this node, transmitting it will be retried *r* times. By default, *r* is set to 1. Retries with a greater hop count than when it left this node, transmitting it will be retried *r* times. By default,
follow same rules as above, with the exception that it must wait for at least *d* = c\ :sup:`h+1` + *r* is set to 1.
t + rand(0, rw) seconds. This amount of time is equal to the amount of time it would take the next
node to retransmit the packet, plus a random window. By default, *t* is set to 10 seconds, and the
random window *rw* is set to 10 seconds.
* | If a newer announce from the same destination arrives, while an identical one is already in * | If a newer announce from the same destination arrives, while an identical one is already waiting
the queue, the newest announce is discarded. If the newest announce contains different to be transmitted, the newest announce is discarded. If the newest announce contains different
application specific data, it will replace the old announce, but will use *d* and *p* of the old application specific data, it will replace the old announce.
announce.
Once an announce has reached a node in the network, any other node in direct contact with that Once an announce has reached a node in the network, any other node in direct contact with that
node will be able to reach the destination the announce originated from, simply by sending a packet node will be able to reach the destination the announce originated from, simply by sending a packet
@ -409,16 +406,16 @@ addressed to that destination. Any node with knowledge of the announce will be a
packet towards the destination by looking up the next node with the shortest amount of hops to the packet towards the destination by looking up the next node with the shortest amount of hops to the
destination. destination.
According to these rules and default constants, an announce will propagate throughout the network According to these rules, an announce will propagate throughout the network in a predictable way,
in a predictable way. and make the announced destination reachable in a short amount of time. Fast networks that have the
capacity to process many announces can reach full convergence very quickly, even when constantly adding
new destinations. Slower segments of such networks might take a bit longer to gain full knowledge about
the wide and fast networks they are connected to, but can still do so over time, while prioritising full
and quickly converging end-to-end connectivity for their local, slower segments.
As an example, in a network based only on radio transceivers with an average link distance of 15 In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full
kilometers, an announce will be able to propagate outwards over 12 hops, to a radius of 180 end-to-end connectivity in about one minute, given there is enough bandwidth available to process
kilometers, in approximately 20 minutes. the required amount of announces.
The design and constants of the decay and delay functionality in the announce propagation is subject
to change and optimisation as real-world usage is explored. The announce propagation speed can be
increased at the cost of increased bandwidth consumption.
.. _understanding-paths: .. _understanding-paths:
@ -465,7 +462,7 @@ For exchanges of small amounts of information, Reticulum offers the *Packet* API
For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the *Link* API. To establish a *link*, the following process is employed: For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the *Link* API. To establish a *link*, the following process is employed:
* | First, the node that wishes to establish a link will send out a special packet, that * | 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 traverses the network and locates the desired destination. Along the way, the Transport Nodes that
forward the packet will take note of this *link request*. forward the packet will take note of this *link request*.
* | Second, if the destination accepts the *link request* , it will send back a packet that proves the * | Second, if the destination accepts the *link request* , it will send back a packet that proves the
@ -476,15 +473,19 @@ For exchanges of larger amounts of data, or when longer sessions of bidirectiona
* | When the validity of the *link* has been accepted by forwarding nodes, these nodes will * | When the validity of the *link* has been accepted by forwarding nodes, these nodes will
remember the *link* , and it can subsequently be used by referring to a hash representing it. remember the *link* , and it can subsequently be used by referring to a hash representing it.
* | As a part of the *link request* , a Diffie-Hellman key exchange takes place, that sets up an * | As a part of the *link request*, an Elliptic Curve Diffie-Hellman key exchange takes place, that sets up an
efficiently encrypted tunnel between the two nodes, using elliptic curve cryptography. As such, efficiently encrypted tunnel between the two nodes. As such, this mode of communication is preferred,
this mode of communication is preferred, even for situations when nodes can directly communicate, even for situations when nodes can directly communicate, when the amount of data to be exchanged numbers
when the amount of data to be exchanged numbers in the tens of packets. in the tens of packets, or whenever the use of the more advanced API functions is desired.
* | When a *link* has been set up, it automatically provides message receipt functionality, through * | When a *link* has been set up, it automatically provides message receipt functionality, through
the same *proof* mechanism discussed before, so the sending node can obtain verified confirmation the same *proof* mechanism discussed before, so the sending node can obtain verified confirmation
that the information reached the intended recipient. that the information reached the intended recipient.
* | Once the *link* has been set up, the initiator can remain anonymous, or choose to authenticate towards
the destination using a Reticulum Identity. This authentication is happening inside the encrypted
link, and is only revealed to the verified destination, and no intermediaries.
In a moment, we will discuss the details of how this methodology is implemented, but let’s first 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 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. is actually the one we want to communicate with, and not a malicious actor pretending to be so.

2
docs/manual/searchindex.js
View File

File diff suppressed because one or more lines are too long

111
docs/manual/understanding.html
View File

@ -328,26 +328,27 @@ certain pattern. This will be detailed in the section
protocols such as IP, where an address is always expected to stay within the network segment it was assigned in. protocols such as IP, where an address is always expected to stay within the network segment it was assigned in.
This limitation does not exist in Reticulum, and any destination is <em>completely portable</em> over the entire topography This limitation does not exist in Reticulum, and any destination is <em>completely portable</em> over the entire topography
of the network, and <em>can even be moved to other Reticulum networks</em> than the one it was created in, and of the network, and <em>can even be moved to other Reticulum networks</em> than the one it was created in, and
still be reachable. To update it’s reachability, a destination simply needs to send an announce on any still become reachable. To update it’s reachability, a destination simply needs to send an announce on any
networks it is part of.</p> networks it is part of. After a short while, it will be globally reachable in the network.</p>
<p>Seeing how <em>single</em> destinations are always tied to a private/public key pair leads us to the next topic.</p> <p>Seeing how <em>single</em> destinations are always tied to a private/public key pair leads us to the next topic.</p>
</div> </div>
<div class="section" id="understanding-identities"> <div class="section" id="understanding-identities">
<span id="identities"></span><h3>Identities<a class="headerlink" href="#understanding-identities" title="Permalink to this headline"></a></h3> <span id="identities"></span><h3>Identities<a class="headerlink" href="#understanding-identities" title="Permalink to this headline"></a></h3>
<p>In Reticulum, an <em>identity</em> does not necessarily represent a personal identity, but is an abstraction that <p>In Reticulum, an <em>identity</em> does not necessarily represent a personal identity, but is an abstraction that
can represent any kind of <em>verified entity</em>. This could very well be a person, but it could also be the can represent any kind of <em>verifiable entity</em>. This could very well be a person, but it could also be the
control interface of a machine, a program, robot, computer, sensor or something else entirely. In control interface of a machine, a program, robot, computer, sensor or something else entirely. In
general, any kind of agent that can act, or be acted upon, or store or manipulate information, can be general, any kind of agent that can act, or be acted upon, or store or manipulate information, can be
represented as an identity. An <em>identity</em> can be used to create any number of destinations.</p> represented as an identity. An <em>identity</em> can be used to create any number of destinations.</p>
<p>As we have seen, a <em>single</em> destination will always have an <em>identity</em> tied to it, but not <em>plain</em> or <em>group</em> <p>A <em>single</em> destination will always have an <em>identity</em> tied to it, but not <em>plain</em> or <em>group</em>
destinations. Destinations and identities share a multilateral connection. You can create a destinations. Destinations and identities share a multilateral connection. You can create a
destination, and if it is not connected to an identity upon creation, it will just create a new one to use destination, and if it is not connected to an identity upon creation, it will just create a new one to use
automatically. This may be desirable in some situations, but often you will probably want to create automatically. This may be desirable in some situations, but often you will probably want to create
the identity first, and then use it to create new destinations.</p> the identity first, and then use it to create new destinations.</p>
<p>Building upon the simple messenger example, we could use an identity to represent the user of the <p>As an example, we could use an identity to represent the user of a messaging application.
application. Destinations created will then be linked to this identity to allow communication to Destinations can then be created by this identity to allow communication to reach the user.
reach the user. In all cases it is of great importance to store the private keys associated with any In all cases it is of great importance to store the private keys associated with any
Reticulum Identity securely and privately.</p> Reticulum Identity securely and privately, since obtaining access to the identity keys equals
obtaining access and controlling reachability to any destinations created by that identity.</p>
</div> </div>
<div class="section" id="getting-further"> <div class="section" id="getting-further">
<span id="understanding-gettingfurther"></span><h3>Getting Further<a class="headerlink" href="#getting-further" title="Permalink to this headline"></a></h3> <span id="understanding-gettingfurther"></span><h3>Getting Further<a class="headerlink" href="#getting-further" title="Permalink to this headline"></a></h3>
@ -360,77 +361,74 @@ hops in the network.</p>
</div> </div>
<div class="section" id="reticulum-transport"> <div class="section" id="reticulum-transport">
<span id="understanding-transport"></span><h2>Reticulum Transport<a class="headerlink" href="#reticulum-transport" title="Permalink to this headline"></a></h2> <span id="understanding-transport"></span><h2>Reticulum Transport<a class="headerlink" href="#reticulum-transport" title="Permalink to this headline"></a></h2>
<p>The term routing has been purposefully avoided until now. The current methods of routing used in IP-based <p>The methods of routing used in traditional networks are fundamentally incompatible with the physical medium
networks are fundamentally incompatible with the physical link types that Reticulum was designed to handle. types and circumstances that Reticulum was designed to handle. These mechanisms mostly assume trust at the physical layer,
These routing methodologies assume trust at the physical layer, and often needs a lot more bandwidth than and often needs a lot more bandwidth than Reticulum can assume is available. Since Reticulum is designed to
Reticulum can assume is available.</p> survive running over open radio spectrum, no such trust can be assumed, and bandwidth is often very limited.</p>
<p>Since Reticulum is designed to survive running over open radio spectrum, no such trust exists, and bandwidth <p>To overcome such challenges, Reticulum’s <em>Transport</em> system uses asymmetric elliptic curve cryptography to
is often very limited. Existing routing protocols like BGP or OSPF carry too much overhead to be practically
useable over bandwidth-limited, high-latency links.</p>
<p>To overcome such challenges, Reticulum’s <em>Transport</em> system uses public-key cryptography to
implement the concept of <em>paths</em> that allow discovery of how to get information closer to a certain implement the concept of <em>paths</em> that allow discovery of how to get information closer to a certain
destination. It is important to note that no single node in a Reticulum network knows the complete destination. It is important to note that no single node in a Reticulum network knows the complete
path to a destination. Every Transport node participating in a Reticulum network will only path to a destination. Every Transport node participating in a Reticulum network will only
know what the most direct way to get a packet one hop closer to it’s destination is.</p> know the most direct way to get a packet one hop closer to it’s destination.</p>
<div class="section" id="node-types"> <div class="section" id="node-types">
<span id="understanding-nodetypes"></span><h3>Node Types<a class="headerlink" href="#node-types" title="Permalink to this headline"></a></h3> <span id="understanding-nodetypes"></span><h3>Node Types<a class="headerlink" href="#node-types" title="Permalink to this headline"></a></h3>
<p>Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network <p>Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network
are <em>Reticulum Instances</em>, and some are alo <em>Transport Nodes</em>. If a system running Reticulum is fixed in are <em>Reticulum Instances</em>, and some are alo <em>Transport Nodes</em>. If a system running Reticulum is fixed in
one place, and is intended to be kept available most of the time, it can be a <em>Transport Node</em>, by enabling one place, and is intended to be kept available most of the time, it is a good contender to be a <em>Transport Node</em>.</p>
it in the configuration.</p> <p>Any Reticulum Instance can become a Transport Node by enabling it in the configuration.
<p>This distinction is made by the user configuring the node, and is used to determine what nodes on the This distinction is made by the user configuring the node, and is used to determine what nodes on the
network will help forward traffic, and what nodes rely on other nodes for wider connectivity.</p> network will help forward traffic, and what nodes rely on other nodes for wider connectivity.</p>
<p>If a node is a <em>Instance</em> it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">No</span></code>, which <p>If a node is an <em>Instance</em> it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">No</span></code>, which
is the default setting.</p> is the default setting.</p>
<p>If it is a <em>Transport Node</em>, it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">Yes</span></code>.</p> <p>If it is a <em>Transport Node</em>, it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">Yes</span></code>.</p>
</div> </div>
<div class="section" id="the-announce-mechanism-in-detail"> <div class="section" id="the-announce-mechanism-in-detail">
<span id="understanding-announce"></span><h3>The Announce Mechanism in Detail<a class="headerlink" href="#the-announce-mechanism-in-detail" title="Permalink to this headline"></a></h3> <span id="understanding-announce"></span><h3>The Announce Mechanism in Detail<a class="headerlink" href="#the-announce-mechanism-in-detail" title="Permalink to this headline"></a></h3>
<p>When an <em>announce</em> is transmitted by from a Reticulum instance, it will be forwarded by any transport node receiving it, but <p>When an <em>announce</em> for a destination is transmitted by from a Reticulum instance, it will be forwarded by
according to some specific rules:</p> any transport node receiving it, but according to some specific rules:</p>
<ul> <ul>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">If this exact announce has already been received before, ignore it.</div> <div class="line">If this exact announce has already been received before, ignore it.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">If not, record into a table which node the announce was received from, and how many times in <div class="line">If not, record into a table which Transport Node the announce was received from, and how many times in
total it has been retransmitted to get here.</div> total it has been retransmitted to get here.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">If the announce has been retransmitted <em>m+1</em> times, it will not be forwarded. By default, <em>m</em> is <div class="line">If the announce has been retransmitted <em>m+1</em> times, it will not be forwarded any more. By default, <em>m</em> is
set to 128.</div> set to 128.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">The announce will be assigned a delay <em>d</em> = c<sup>h</sup> seconds, where <em>c</em> is a decay constant, and <em>h</em> is the amount of times this packet has already been forwarded.</div> <div class="line">After a randomised delay, the announce will be retransmitted on all interfaces that have bandwidth
available for processing announces. By default, the maximum bandwidth allocation for processing
announces is set at 2%, but can be configured on a per-interface basis.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">The packet will be given a priority <em>p = 1/d</em>.</div> <div class="line">If any given interface does not have enough bandwidth available for retransmitting the announce,
the announce will be assigned a priority inversely proportional to it’s hop count, and be inserted
into a queue managed by the interface.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">If at least <em>d</em> seconds has passed since the announce was received, and no other packets with a <div class="line">When the interface has bandwidth available for processing an announce, it will prioritise announces
priority higher than <em>p</em> are waiting in the queue, and the channel is for destinations that are closest in terms of hops, thus prioritising reachability and connectivity
not utilized by other traffic, the announce will be forwarded.</div> of local nodes, even on slow networks that connect to wider and faster networks.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">If no other nodes are heard retransmitting the announce with a greater hop count than when <div class="line">After the announce has been re-transmitted, and if no other nodes are heard retransmitting the announce
it left this node, transmitting it will be retried <em>r</em> times. By default, <em>r</em> is set to 1. Retries with a greater hop count than when it left this node, transmitting it will be retried <em>r</em> times. By default,
follow same rules as above, with the exception that it must wait for at least <em>d</em> = c<sup>h+1</sup> + <em>r</em> is set to 1.</div>
t + rand(0, rw) seconds. This amount of time is equal to the amount of time it would take the next
node to retransmit the packet, plus a random window. By default, <em>t</em> is set to 10 seconds, and the
random window <em>rw</em> is set to 10 seconds.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">If a newer announce from the same destination arrives, while an identical one is already in <div class="line">If a newer announce from the same destination arrives, while an identical one is already waiting
the queue, the newest announce is discarded. If the newest announce contains different to be transmitted, the newest announce is discarded. If the newest announce contains different
application specific data, it will replace the old announce, but will use <em>d</em> and <em>p</em> of the old application specific data, it will replace the old announce.</div>
announce.</div>
</div> </div>
</li> </li>
</ul> </ul>
@ -439,14 +437,15 @@ node will be able to reach the destination the announce originated from, simply
addressed to that destination. Any node with knowledge of the announce will be able to direct the addressed to that destination. Any node with knowledge of the announce will be able to direct the
packet towards the destination by looking up the next node with the shortest amount of hops to the packet towards the destination by looking up the next node with the shortest amount of hops to the
destination.</p> destination.</p>
<p>According to these rules and default constants, an announce will propagate throughout the network <p>According to these rules, an announce will propagate throughout the network in a predictable way,
in a predictable way.</p> and make the announced destination reachable in a short amount of time. Fast networks that have the
<p>As an example, in a network based only on radio transceivers with an average link distance of 15 capacity to process many announces can reach full convergence very quickly, even when constantly adding
kilometers, an announce will be able to propagate outwards over 12 hops, to a radius of 180 new destinations. Slower segments of such networks might take a bit longer to gain full knowledge about
kilometers, in approximately 20 minutes.</p> the wide and fast networks they are connected to, but can still do so over time, while prioritising full
<p>The design and constants of the decay and delay functionality in the announce propagation is subject and quickly converging end-to-end connectivity for their local, slower segments.</p>
to change and optimisation as real-world usage is explored. The announce propagation speed can be <p>In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full
increased at the cost of increased bandwidth consumption.</p> end-to-end connectivity in about one minute, given there is enough bandwidth available to process
the required amount of announces.</p>
</div> </div>
<div class="section" id="reaching-the-destination"> <div class="section" id="reaching-the-destination">
<span id="understanding-paths"></span><h3>Reaching the Destination<a class="headerlink" href="#reaching-the-destination" title="Permalink to this headline"></a></h3> <span id="understanding-paths"></span><h3>Reaching the Destination<a class="headerlink" href="#reaching-the-destination" title="Permalink to this headline"></a></h3>
@ -504,7 +503,7 @@ strictly necessary to use one of the others.</div>
<ul> <ul>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">First, the node that wishes to establish a link will send out a special packet, that <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 traverses the network and locates the desired destination. Along the way, the Transport Nodes that
forward the packet will take note of this <em>link request</em>.</div> forward the packet will take note of this <em>link request</em>.</div>
</div> </div>
</li> </li>
@ -521,10 +520,10 @@ remember the <em>link</em> , and it can subsequently be used by referring to a h
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
<div class="line">As a part of the <em>link request</em> , a Diffie-Hellman key exchange takes place, that sets up an <div class="line">As a part of the <em>link request</em>, an Elliptic Curve Diffie-Hellman key exchange takes place, that sets up an
efficiently encrypted tunnel between the two nodes, using elliptic curve cryptography. As such, efficiently encrypted tunnel between the two nodes. As such, this mode of communication is preferred,
this mode of communication is preferred, even for situations when nodes can directly communicate, even for situations when nodes can directly communicate, when the amount of data to be exchanged numbers
when the amount of data to be exchanged numbers in the tens of packets.</div> in the tens of packets, or whenever the use of the more advanced API functions is desired.</div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
@ -533,6 +532,12 @@ the same <em>proof</em> mechanism discussed before, so the sending node can obta
that the information reached the intended recipient.</div> that the information reached the intended recipient.</div>
</div> </div>
</li> </li>
<li><div class="line-block">
<div class="line">Once the <em>link</em> has been set up, the initiator can remain anonymous, or choose to authenticate towards
the destination using a Reticulum Identity. This authentication is happening inside the encrypted
link, and is only revealed to the verified destination, and no intermediaries.</div>
</div>
</li>
</ul> </ul>
<p>In a moment, we will discuss the details of how this methodology is implemented, but let’s first <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 recap what purposes this methodology serves. We first ensure that the node answering our request

109
docs/source/understanding.rst
View File

@ -287,8 +287,8 @@ In Reticulum, destinations are allowed to move around the network at will. This
protocols such as IP, where an address is always expected to stay within the network segment it was assigned in. protocols such as IP, where an address is always expected to stay within the network segment it was assigned in.
This limitation does not exist in Reticulum, and any destination is *completely portable* over the entire topography This limitation does not exist in Reticulum, and any destination is *completely portable* over the entire topography
of the network, and *can even be moved to other Reticulum networks* than the one it was created in, and of the network, and *can even be moved to other Reticulum networks* than the one it was created in, and
still be reachable. To update it's reachability, a destination simply needs to send an announce on any still become reachable. To update it's reachability, a destination simply needs to send an announce on any
networks it is part of. networks it is part of. After a short while, it will be globally reachable in the network.
Seeing how *single* destinations are always tied to a private/public key pair leads us to the next topic. Seeing how *single* destinations are always tied to a private/public key pair leads us to the next topic.
@ -298,21 +298,22 @@ Identities
---------- ----------
In Reticulum, an *identity* does not necessarily represent a personal identity, but is an abstraction that In Reticulum, an *identity* does not necessarily represent a personal identity, but is an abstraction that
can represent any kind of *verified entity*. This could very well be a person, but it could also be the can represent any kind of *verifiable entity*. This could very well be a person, but it could also be the
control interface of a machine, a program, robot, computer, sensor or something else entirely. In control interface of a machine, a program, robot, computer, sensor or something else entirely. In
general, any kind of agent that can act, or be acted upon, or store or manipulate information, can be general, any kind of agent that can act, or be acted upon, or store or manipulate information, can be
represented as an identity. An *identity* can be used to create any number of destinations. represented as an identity. An *identity* can be used to create any number of destinations.
As we have seen, a *single* destination will always have an *identity* tied to it, but not *plain* or *group* A *single* destination will always have an *identity* tied to it, but not *plain* or *group*
destinations. Destinations and identities share a multilateral connection. You can create a destinations. Destinations and identities share a multilateral connection. You can create a
destination, and if it is not connected to an identity upon creation, it will just create a new one to use destination, and if it is not connected to an identity upon creation, it will just create a new one to use
automatically. This may be desirable in some situations, but often you will probably want to create automatically. This may be desirable in some situations, but often you will probably want to create
the identity first, and then use it to create new destinations. the identity first, and then use it to create new destinations.
Building upon the simple messenger example, we could use an identity to represent the user of the As an example, we could use an identity to represent the user of a messaging application.
application. Destinations created will then be linked to this identity to allow communication to Destinations can then be created by this identity to allow communication to reach the user.
reach the user. In all cases it is of great importance to store the private keys associated with any In all cases it is of great importance to store the private keys associated with any
Reticulum Identity securely and privately. Reticulum Identity securely and privately, since obtaining access to the identity keys equals
obtaining access and controlling reachability to any destinations created by that identity.
.. _understanding-gettingfurther: .. _understanding-gettingfurther:
@ -331,20 +332,16 @@ In the following sections, two concepts that allow this will be introduced, *pat
Reticulum Transport Reticulum Transport
=================== ===================
The term routing has been purposefully avoided until now. The current methods of routing used in IP-based The methods of routing used in traditional networks are fundamentally incompatible with the physical medium
networks are fundamentally incompatible with the physical link types that Reticulum was designed to handle. types and circumstances that Reticulum was designed to handle. These mechanisms mostly assume trust at the physical layer,
These routing methodologies assume trust at the physical layer, and often needs a lot more bandwidth than and often needs a lot more bandwidth than Reticulum can assume is available. Since Reticulum is designed to
Reticulum can assume is available. survive running over open radio spectrum, no such trust can be assumed, and bandwidth is often very limited.
Since Reticulum is designed to survive running over open radio spectrum, no such trust exists, and bandwidth To overcome such challenges, Reticulum’s *Transport* system uses asymmetric elliptic curve cryptography to
is often very limited. Existing routing protocols like BGP or OSPF carry too much overhead to be practically
useable over bandwidth-limited, high-latency links.
To overcome such challenges, Reticulum’s *Transport* system uses public-key cryptography to
implement the concept of *paths* that allow discovery of how to get information closer to a certain implement the concept of *paths* that allow discovery of how to get information closer to a certain
destination. It is important to note that no single node in a Reticulum network knows the complete destination. It is important to note that no single node in a Reticulum network knows the complete
path to a destination. Every Transport node participating in a Reticulum network will only path to a destination. Every Transport node participating in a Reticulum network will only
know what the most direct way to get a packet one hop closer to it's destination is. know the most direct way to get a packet one hop closer to it's destination.
.. _understanding-nodetypes: .. _understanding-nodetypes:
@ -354,13 +351,13 @@ Node Types
Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network
are *Reticulum Instances*, and some are alo *Transport Nodes*. If a system running Reticulum is fixed in are *Reticulum Instances*, and some are alo *Transport Nodes*. If a system running Reticulum is fixed in
one place, and is intended to be kept available most of the time, it can be a *Transport Node*, by enabling one place, and is intended to be kept available most of the time, it is a good contender to be a *Transport Node*.
it in the configuration.
Any Reticulum Instance can become a Transport Node by enabling it in the configuration.
This distinction is made by the user configuring the node, and is used to determine what nodes on the This distinction is made by the user configuring the node, and is used to determine what nodes on the
network will help forward traffic, and what nodes rely on other nodes for wider connectivity. network will help forward traffic, and what nodes rely on other nodes for wider connectivity.
If a node is a *Instance* it should be given the configuration directive ``enable_transport = No``, which If a node is an *Instance* it should be given the configuration directive ``enable_transport = No``, which
is the default setting. is the default setting.
If it is a *Transport Node*, it should be given the configuration directive ``enable_transport = Yes``. If it is a *Transport Node*, it should be given the configuration directive ``enable_transport = Yes``.
@ -371,37 +368,37 @@ If it is a *Transport Node*, it should be given the configuration directive ``en
The Announce Mechanism in Detail The Announce Mechanism in Detail
-------------------------------- --------------------------------
When an *announce* is transmitted by from a Reticulum instance, it will be forwarded by any transport node receiving it, but When an *announce* for a destination is transmitted by from a Reticulum instance, it will be forwarded by
according to some specific rules: any transport node receiving it, but according to some specific rules:
* | If this exact announce has already been received before, ignore it. * | If this exact announce has already been received before, ignore it.
* | If not, record into a table which node the announce was received from, and how many times in * | If not, record into a table which Transport Node the announce was received from, and how many times in
total it has been retransmitted to get here. total it has been retransmitted to get here.
* | If the announce has been retransmitted *m+1* times, it will not be forwarded. By default, *m* is * | If the announce has been retransmitted *m+1* times, it will not be forwarded any more. By default, *m* is
set to 128. set to 128.
* | The announce will be assigned a delay *d* = c\ :sup:`h` seconds, where *c* is a decay constant, and *h* is the amount of times this packet has already been forwarded. * | After a randomised delay, the announce will be retransmitted on all interfaces that have bandwidth
available for processing announces. By default, the maximum bandwidth allocation for processing
announces is set at 2%, but can be configured on a per-interface basis.
* | The packet will be given a priority *p = 1/d*. * | If any given interface does not have enough bandwidth available for retransmitting the announce,
the announce will be assigned a priority inversely proportional to it's hop count, and be inserted
into a queue managed by the interface.
* | If at least *d* seconds has passed since the announce was received, and no other packets with a * | When the interface has bandwidth available for processing an announce, it will prioritise announces
priority higher than *p* are waiting in the queue, and the channel is for destinations that are closest in terms of hops, thus prioritising reachability and connectivity
not utilized by other traffic, the announce will be forwarded. of local nodes, even on slow networks that connect to wider and faster networks.
* | If no other nodes are heard retransmitting the announce with a greater hop count than when * | After the announce has been re-transmitted, and if no other nodes are heard retransmitting the announce
it left this node, transmitting it will be retried *r* times. By default, *r* is set to 1. Retries with a greater hop count than when it left this node, transmitting it will be retried *r* times. By default,
follow same rules as above, with the exception that it must wait for at least *d* = c\ :sup:`h+1` + *r* is set to 1.
t + rand(0, rw) seconds. This amount of time is equal to the amount of time it would take the next
node to retransmit the packet, plus a random window. By default, *t* is set to 10 seconds, and the
random window *rw* is set to 10 seconds.
* | If a newer announce from the same destination arrives, while an identical one is already in * | If a newer announce from the same destination arrives, while an identical one is already waiting
the queue, the newest announce is discarded. If the newest announce contains different to be transmitted, the newest announce is discarded. If the newest announce contains different
application specific data, it will replace the old announce, but will use *d* and *p* of the old application specific data, it will replace the old announce.
announce.
Once an announce has reached a node in the network, any other node in direct contact with that Once an announce has reached a node in the network, any other node in direct contact with that
node will be able to reach the destination the announce originated from, simply by sending a packet node will be able to reach the destination the announce originated from, simply by sending a packet
@ -409,16 +406,16 @@ addressed to that destination. Any node with knowledge of the announce will be a
packet towards the destination by looking up the next node with the shortest amount of hops to the packet towards the destination by looking up the next node with the shortest amount of hops to the
destination. destination.
According to these rules and default constants, an announce will propagate throughout the network According to these rules, an announce will propagate throughout the network in a predictable way,
in a predictable way. and make the announced destination reachable in a short amount of time. Fast networks that have the
capacity to process many announces can reach full convergence very quickly, even when constantly adding
new destinations. Slower segments of such networks might take a bit longer to gain full knowledge about
the wide and fast networks they are connected to, but can still do so over time, while prioritising full
and quickly converging end-to-end connectivity for their local, slower segments.
As an example, in a network based only on radio transceivers with an average link distance of 15 In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full
kilometers, an announce will be able to propagate outwards over 12 hops, to a radius of 180 end-to-end connectivity in about one minute, given there is enough bandwidth available to process
kilometers, in approximately 20 minutes. the required amount of announces.
The design and constants of the decay and delay functionality in the announce propagation is subject
to change and optimisation as real-world usage is explored. The announce propagation speed can be
increased at the cost of increased bandwidth consumption.
.. _understanding-paths: .. _understanding-paths:
@ -465,7 +462,7 @@ For exchanges of small amounts of information, Reticulum offers the *Packet* API
For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the *Link* API. To establish a *link*, the following process is employed: For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the *Link* API. To establish a *link*, the following process is employed:
* | First, the node that wishes to establish a link will send out a special packet, that * | 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 traverses the network and locates the desired destination. Along the way, the Transport Nodes that
forward the packet will take note of this *link request*. forward the packet will take note of this *link request*.
* | Second, if the destination accepts the *link request* , it will send back a packet that proves the * | Second, if the destination accepts the *link request* , it will send back a packet that proves the
@ -476,15 +473,19 @@ For exchanges of larger amounts of data, or when longer sessions of bidirectiona
* | When the validity of the *link* has been accepted by forwarding nodes, these nodes will * | When the validity of the *link* has been accepted by forwarding nodes, these nodes will
remember the *link* , and it can subsequently be used by referring to a hash representing it. remember the *link* , and it can subsequently be used by referring to a hash representing it.
* | As a part of the *link request* , a Diffie-Hellman key exchange takes place, that sets up an * | As a part of the *link request*, an Elliptic Curve Diffie-Hellman key exchange takes place, that sets up an
efficiently encrypted tunnel between the two nodes, using elliptic curve cryptography. As such, efficiently encrypted tunnel between the two nodes. As such, this mode of communication is preferred,
this mode of communication is preferred, even for situations when nodes can directly communicate, even for situations when nodes can directly communicate, when the amount of data to be exchanged numbers
when the amount of data to be exchanged numbers in the tens of packets. in the tens of packets, or whenever the use of the more advanced API functions is desired.
* | When a *link* has been set up, it automatically provides message receipt functionality, through * | When a *link* has been set up, it automatically provides message receipt functionality, through
the same *proof* mechanism discussed before, so the sending node can obtain verified confirmation the same *proof* mechanism discussed before, so the sending node can obtain verified confirmation
that the information reached the intended recipient. that the information reached the intended recipient.
* | Once the *link* has been set up, the initiator can remain anonymous, or choose to authenticate towards
the destination using a Reticulum Identity. This authentication is happening inside the encrypted
link, and is only revealed to the verified destination, and no intermediaries.
In a moment, we will discuss the details of how this methodology is implemented, but let’s first 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 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. is actually the one we want to communicate with, and not a malicious actor pretending to be so.