mirror of
https://github.com/markqvist/Reticulum.git
synced 2024-11-04 21:30:14 +00:00
Updated documentation
This commit is contained in:
Mark Qvist
parent
600bd0e64d
commit
8e4bfbbd94
@ -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.
|
||||
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
|
||||
still be reachable. To update it's reachability, a destination simply needs to send an announce on any
|
||||
networks it is part of.
|
||||
still become reachable. To update it's reachability, a destination simply needs to send an announce on any
|
||||
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.
|
||||
|
||||
@ -298,21 +298,22 @@ Identities
|
||||
----------
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
application. Destinations created will then be linked to this identity to allow communication to
|
||||
reach the user. In all cases it is of great importance to store the private keys associated with any
|
||||
Reticulum Identity securely and privately.
|
||||
As an example, we could use an identity to represent the user of a messaging application.
|
||||
Destinations can then be created by this identity to allow communication to reach the user.
|
||||
In all cases it is of great importance to store the private keys associated with any
|
||||
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:
|
||||
|
||||
@ -331,20 +332,16 @@ In the following sections, two concepts that allow this will be introduced, *pat
|
||||
Reticulum Transport
|
||||
===================
|
||||
|
||||
The term routing has been purposefully avoided until now. The current methods of routing used in IP-based
|
||||
networks are fundamentally incompatible with the physical link types that Reticulum was designed to handle.
|
||||
These routing methodologies assume trust at the physical layer, and often needs a lot more bandwidth than
|
||||
Reticulum can assume is available.
|
||||
The methods of routing used in traditional networks are fundamentally incompatible with the physical medium
|
||||
types and circumstances that Reticulum was designed to handle. These mechanisms mostly assume trust at the physical layer,
|
||||
and often needs a lot more bandwidth than Reticulum can assume is available. Since Reticulum is designed to
|
||||
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
|
||||
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
|
||||
To overcome such challenges, Reticulum’s *Transport* system uses asymmetric elliptic curve cryptography to
|
||||
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
|
||||
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:
|
||||
@ -354,13 +351,13 @@ Node Types
|
||||
|
||||
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
|
||||
one place, and is intended to be kept available most of the time, it can be a *Transport Node*, by enabling
|
||||
it in the configuration.
|
||||
one place, and is intended to be kept available most of the time, it is a good contender to be a *Transport Node*.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
--------------------------------
|
||||
|
||||
When an *announce* is transmitted by from a Reticulum instance, it will be forwarded by any transport node receiving it, but
|
||||
according to some specific rules:
|
||||
When an *announce* for a destination is transmitted by from a Reticulum instance, it will be forwarded by
|
||||
any transport node receiving it, but according to some specific rules:
|
||||
|
||||
|
||||
* | 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.
|
||||
|
||||
* | 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.
|
||||
|
||||
* | 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
|
||||
priority higher than *p* are waiting in the queue, and the channel is
|
||||
not utilized by other traffic, the announce will be forwarded.
|
||||
* | When the interface has bandwidth available for processing an announce, it will prioritise announces
|
||||
for destinations that are closest in terms of hops, thus prioritising reachability and connectivity
|
||||
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
|
||||
it left this node, transmitting it will be retried *r* times. By default, *r* is set to 1. Retries
|
||||
follow same rules as above, with the exception that it must wait for at least *d* = c\ :sup:`h+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.
|
||||
* | After the announce has been re-transmitted, and if no other nodes are heard retransmitting the announce
|
||||
with a greater hop count than when it left this node, transmitting it will be retried *r* times. By default,
|
||||
*r* is set to 1.
|
||||
|
||||
* | If a newer announce from the same destination arrives, while an identical one is already in
|
||||
the queue, 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
|
||||
announce.
|
||||
* | If a newer announce from the same destination arrives, while an identical one is already waiting
|
||||
to be transmitted, the newest announce is discarded. If the newest announce contains different
|
||||
application specific data, it will replace the old announce.
|
||||
|
||||
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
|
||||
@ -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
|
||||
destination.
|
||||
|
||||
According to these rules and default constants, an announce will propagate throughout the network
|
||||
in a predictable way.
|
||||
According to these rules, an announce will propagate throughout the network 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
|
||||
kilometers, an announce will be able to propagate outwards over 12 hops, to a radius of 180
|
||||
kilometers, in approximately 20 minutes.
|
||||
|
||||
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.
|
||||
In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full
|
||||
end-to-end connectivity in about one minute, given there is enough bandwidth available to process
|
||||
the required amount of announces.
|
||||
|
||||
.. _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:
|
||||
|
||||
* | 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*.
|
||||
|
||||
* | 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
|
||||
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
|
||||
efficiently encrypted tunnel between the two nodes, using elliptic curve cryptography. As such,
|
||||
this mode of communication is preferred, even for situations when nodes can directly communicate,
|
||||
when the amount of data to be exchanged numbers in the tens of packets.
|
||||
* | 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. As such, this mode of communication is preferred,
|
||||
even for situations when nodes can directly communicate, when the amount of data to be exchanged numbers
|
||||
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
|
||||
the same *proof* mechanism discussed before, so the sending node can obtain verified confirmation
|
||||
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
|
||||
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.
|
||||
|
||||
File diff suppressed because one or more lines are too long
@ -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.
|
||||
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
|
||||
still be reachable. To update it’s reachability, a destination simply needs to send an announce on any
|
||||
networks it is part of.</p>
|
||||
still become reachable. To update it’s reachability, a destination simply needs to send an announce on any
|
||||
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>
|
||||
</div>
|
||||
<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>
|
||||
<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
|
||||
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>
|
||||
<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
|
||||
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
|
||||
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
|
||||
application. Destinations created will then be linked to this identity to allow communication to
|
||||
reach the user. In all cases it is of great importance to store the private keys associated with any
|
||||
Reticulum Identity securely and privately.</p>
|
||||
<p>As an example, we could use an identity to represent the user of a messaging application.
|
||||
Destinations can then be created by this identity to allow communication to reach the user.
|
||||
In all cases it is of great importance to store the private keys associated with any
|
||||
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 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>
|
||||
@ -360,77 +361,74 @@ hops in the network.</p>
|
||||
</div>
|
||||
<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>
|
||||
<p>The term routing has been purposefully avoided until now. The current methods of routing used in IP-based
|
||||
networks are fundamentally incompatible with the physical link types that Reticulum was designed to handle.
|
||||
These routing methodologies assume trust at the physical layer, and often needs a lot more bandwidth than
|
||||
Reticulum can assume is available.</p>
|
||||
<p>Since Reticulum is designed to survive running over open radio spectrum, no such trust exists, and bandwidth
|
||||
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
|
||||
<p>The methods of routing used in traditional networks are fundamentally incompatible with the physical medium
|
||||
types and circumstances that Reticulum was designed to handle. These mechanisms mostly assume trust at the physical layer,
|
||||
and often needs a lot more bandwidth than Reticulum can assume is available. Since Reticulum is designed to
|
||||
survive running over open radio spectrum, no such trust can be assumed, and bandwidth is often very limited.</p>
|
||||
<p>To overcome such challenges, Reticulum’s <em>Transport</em> system uses asymmetric elliptic curve cryptography to
|
||||
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
|
||||
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">
|
||||
<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
|
||||
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
|
||||
it in the configuration.</p>
|
||||
<p>This distinction is made by the user configuring the node, and is used to determine what nodes on the
|
||||
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>
|
||||
<p>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
|
||||
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>
|
||||
<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 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>
|
||||
<p>When an <em>announce</em> is transmitted by from a Reticulum instance, it will be forwarded by any transport node receiving it, but
|
||||
according to some specific rules:</p>
|
||||
<p>When an <em>announce</em> for a destination is transmitted by from a Reticulum instance, it will be forwarded by
|
||||
any transport node receiving it, but according to some specific rules:</p>
|
||||
<ul>
|
||||
<li><div class="line-block">
|
||||
<div class="line">If this exact announce has already been received before, ignore it.</div>
|
||||
</div>
|
||||
</li>
|
||||
<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>
|
||||
</div>
|
||||
</li>
|
||||
<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>
|
||||
</div>
|
||||
</li>
|
||||
<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>
|
||||
</li>
|
||||
<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>
|
||||
</li>
|
||||
<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
|
||||
priority higher than <em>p</em> are waiting in the queue, and the channel is
|
||||
not utilized by other traffic, the announce will be forwarded.</div>
|
||||
<div class="line">When the interface has bandwidth available for processing an announce, it will prioritise announces
|
||||
for destinations that are closest in terms of hops, thus prioritising reachability and connectivity
|
||||
of local nodes, even on slow networks that connect to wider and faster networks.</div>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">If no other nodes are heard retransmitting the announce with a greater hop count than when
|
||||
it left this node, transmitting it will be retried <em>r</em> times. By default, <em>r</em> is set to 1. Retries
|
||||
follow same rules as above, with the exception that it must wait for at least <em>d</em> = c<sup>h+1</sup> +
|
||||
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 class="line">After the announce has been re-transmitted, and if no other nodes are heard retransmitting the announce
|
||||
with a greater hop count than when it left this node, transmitting it will be retried <em>r</em> times. By default,
|
||||
<em>r</em> is set to 1.</div>
|
||||
</div>
|
||||
</li>
|
||||
<li><div class="line-block">
|
||||
<div class="line">If a newer announce from the same destination arrives, while an identical one is already in
|
||||
the queue, 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
|
||||
announce.</div>
|
||||
<div class="line">If a newer announce from the same destination arrives, while an identical one is already waiting
|
||||
to be transmitted, the newest announce is discarded. If the newest announce contains different
|
||||
application specific data, it will replace the old announce.</div>
|
||||
</div>
|
||||
</li>
|
||||
</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
|
||||
packet towards the destination by looking up the next node with the shortest amount of hops to the
|
||||
destination.</p>
|
||||
<p>According to these rules and default constants, an announce will propagate throughout the network
|
||||
in a predictable way.</p>
|
||||
<p>As an example, in a network based only on radio transceivers with an average link distance of 15
|
||||
kilometers, an announce will be able to propagate outwards over 12 hops, to a radius of 180
|
||||
kilometers, in approximately 20 minutes.</p>
|
||||
<p>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.</p>
|
||||
<p>According to these rules, an announce will propagate throughout the network 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.</p>
|
||||
<p>In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full
|
||||
end-to-end connectivity in about one minute, given there is enough bandwidth available to process
|
||||
the required amount of announces.</p>
|
||||
</div>
|
||||
<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>
|
||||
@ -504,7 +503,7 @@ strictly necessary to use one of the others.</div>
|
||||
<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
|
||||
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>
|
||||
</div>
|
||||
</li>
|
||||
@ -521,10 +520,10 @@ remember the <em>link</em> , and it can subsequently be used by referring to a h
|
||||
</div>
|
||||
</li>
|
||||
<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
|
||||
efficiently encrypted tunnel between the two nodes, using elliptic curve cryptography. As such,
|
||||
this mode of communication is preferred, even for situations when nodes can directly communicate,
|
||||
when the amount of data to be exchanged numbers in the tens of packets.</div>
|
||||
<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. As such, this mode of communication is preferred,
|
||||
even for situations when nodes can directly communicate, when the amount of data to be exchanged numbers
|
||||
in the tens of packets, or whenever the use of the more advanced API functions is desired.</div>
|
||||
</div>
|
||||
</li>
|
||||
<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>
|
||||
</div>
|
||||
</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>
|
||||
<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
|
||||
|
||||
@ -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.
|
||||
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
|
||||
still be reachable. To update it's reachability, a destination simply needs to send an announce on any
|
||||
networks it is part of.
|
||||
still become reachable. To update it's reachability, a destination simply needs to send an announce on any
|
||||
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.
|
||||
|
||||
@ -298,21 +298,22 @@ Identities
|
||||
----------
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
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
|
||||
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
|
||||
application. Destinations created will then be linked to this identity to allow communication to
|
||||
reach the user. In all cases it is of great importance to store the private keys associated with any
|
||||
Reticulum Identity securely and privately.
|
||||
As an example, we could use an identity to represent the user of a messaging application.
|
||||
Destinations can then be created by this identity to allow communication to reach the user.
|
||||
In all cases it is of great importance to store the private keys associated with any
|
||||
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:
|
||||
|
||||
@ -331,20 +332,16 @@ In the following sections, two concepts that allow this will be introduced, *pat
|
||||
Reticulum Transport
|
||||
===================
|
||||
|
||||
The term routing has been purposefully avoided until now. The current methods of routing used in IP-based
|
||||
networks are fundamentally incompatible with the physical link types that Reticulum was designed to handle.
|
||||
These routing methodologies assume trust at the physical layer, and often needs a lot more bandwidth than
|
||||
Reticulum can assume is available.
|
||||
The methods of routing used in traditional networks are fundamentally incompatible with the physical medium
|
||||
types and circumstances that Reticulum was designed to handle. These mechanisms mostly assume trust at the physical layer,
|
||||
and often needs a lot more bandwidth than Reticulum can assume is available. Since Reticulum is designed to
|
||||
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
|
||||
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
|
||||
To overcome such challenges, Reticulum’s *Transport* system uses asymmetric elliptic curve cryptography to
|
||||
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
|
||||
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:
|
||||
@ -354,13 +351,13 @@ Node Types
|
||||
|
||||
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
|
||||
one place, and is intended to be kept available most of the time, it can be a *Transport Node*, by enabling
|
||||
it in the configuration.
|
||||
one place, and is intended to be kept available most of the time, it is a good contender to be a *Transport Node*.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
--------------------------------
|
||||
|
||||
When an *announce* is transmitted by from a Reticulum instance, it will be forwarded by any transport node receiving it, but
|
||||
according to some specific rules:
|
||||
When an *announce* for a destination is transmitted by from a Reticulum instance, it will be forwarded by
|
||||
any transport node receiving it, but according to some specific rules:
|
||||
|
||||
|
||||
* | 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.
|
||||
|
||||
* | 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.
|
||||
|
||||
* | 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
|
||||
priority higher than *p* are waiting in the queue, and the channel is
|
||||
not utilized by other traffic, the announce will be forwarded.
|
||||
* | When the interface has bandwidth available for processing an announce, it will prioritise announces
|
||||
for destinations that are closest in terms of hops, thus prioritising reachability and connectivity
|
||||
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
|
||||
it left this node, transmitting it will be retried *r* times. By default, *r* is set to 1. Retries
|
||||
follow same rules as above, with the exception that it must wait for at least *d* = c\ :sup:`h+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.
|
||||
* | After the announce has been re-transmitted, and if no other nodes are heard retransmitting the announce
|
||||
with a greater hop count than when it left this node, transmitting it will be retried *r* times. By default,
|
||||
*r* is set to 1.
|
||||
|
||||
* | If a newer announce from the same destination arrives, while an identical one is already in
|
||||
the queue, 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
|
||||
announce.
|
||||
* | If a newer announce from the same destination arrives, while an identical one is already waiting
|
||||
to be transmitted, the newest announce is discarded. If the newest announce contains different
|
||||
application specific data, it will replace the old announce.
|
||||
|
||||
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
|
||||
@ -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
|
||||
destination.
|
||||
|
||||
According to these rules and default constants, an announce will propagate throughout the network
|
||||
in a predictable way.
|
||||
According to these rules, an announce will propagate throughout the network 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
|
||||
kilometers, an announce will be able to propagate outwards over 12 hops, to a radius of 180
|
||||
kilometers, in approximately 20 minutes.
|
||||
|
||||
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.
|
||||
In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full
|
||||
end-to-end connectivity in about one minute, given there is enough bandwidth available to process
|
||||
the required amount of announces.
|
||||
|
||||
.. _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:
|
||||
|
||||
* | 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*.
|
||||
|
||||
* | 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
|
||||
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
|
||||
efficiently encrypted tunnel between the two nodes, using elliptic curve cryptography. As such,
|
||||
this mode of communication is preferred, even for situations when nodes can directly communicate,
|
||||
when the amount of data to be exchanged numbers in the tens of packets.
|
||||
* | 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. As such, this mode of communication is preferred,
|
||||
even for situations when nodes can directly communicate, when the amount of data to be exchanged numbers
|
||||
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
|
||||
the same *proof* mechanism discussed before, so the sending node can obtain verified confirmation
|
||||
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
|
||||
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user