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

Updated documentation

Browse Source
This commit is contained in:
Mark Qvist 2021-12-06 14:10:22 +01:00
parent 2e4fcc659c
commit 98d66e2ba5
10 changed files with 151 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/manual/_sources/gettingstartedfast.rst.txt
View File

@ -16,7 +16,7 @@ provides a complete encrypted communications suite built with Reticulum.
:target: _images/nomadnet_3.png :target: _images/nomadnet_3.png
`Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client `Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client
in the development for the messaging and information-sharing protocol for the messaging and information-sharing protocol
`LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum. `LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum.
You can install Nomad Network via pip: You can install Nomad Network via pip:
@ -48,7 +48,8 @@ Creating a Network With Reticulum
============================================= =============================================
To create a network, you will need to specify one or more *interfaces* for To create a network, you will need to specify one or more *interfaces* for
Reticulum to use. This is done in the Reticulum configuration file, which by Reticulum to use. This is done in the Reticulum configuration file, which by
default is located at ``~/.reticulum/config``. default is located at ``~/.reticulum/config``. You can edit this file by hand,
or use the interactive ``rnsconfig`` utility.
When Reticulum is started for the first time, it will create a default When Reticulum is started for the first time, it will create a default
configuration file, with one active interface. This default interface uses configuration file, with one active interface. This default interface uses
@ -152,7 +153,7 @@ From within Termux, execute the following:
pkg update pkg update
pkg upgrade pkg upgrade
# Then install dependencies for cryptography library. # Then install dependencies for the cryptography library.
pkg install python build-essential openssl libffi rust pkg install python build-essential openssl libffi rust
# Make sure pip is up to date, and install the wheel module. # Make sure pip is up to date, and install the wheel module.

29
docs/manual/_sources/interfaces.rst.txt
View File

@ -78,6 +78,9 @@ pre-existing LAN.
# forward_ip = 10.55.0.16 # forward_ip = 10.55.0.16
# forward_port = 4242 # forward_port = 4242
*Please Note!* If you use the ``device`` option, you will need the Python module
``netifaces`` installed on your system. You can install it with ``pip3 install netifaces``.
.. _interfaces-tcps: .. _interfaces-tcps:
TCP Server Interface TCP Server Interface
@ -114,6 +117,8 @@ configured, other Reticulum peers can connect to it with a TCP Client interface.
# device = eth0 # device = eth0
# port = 4242 # port = 4242
*Please Note!* If you use the ``device`` option, you will need the Python module
``netifaces`` installed on your system. You can install it with ``pip3 install netifaces``.
.. _interfaces-tcpc: .. _interfaces-tcpc:
@ -136,6 +141,30 @@ same TCP Server interface at the same time.
target_host = 127.0.0.1 target_host = 127.0.0.1
target_port = 4242 target_port = 4242
It is also possible to use this interface type to connect via other programs
or hardware devices that expose a KISS interface on a TCP port, for example
software-based soundmodems. To do this, use the ``kiss_framing`` option:
.. code::
# Here's an example of a TCP Client interface that connects
# to a software TNC soundmodem on a KISS over TCP port.
[[TCP KISS Interface]]
type = TCPClientInterface
interface_enabled = True
outgoing = True
kiss_framing = True
target_host = 127.0.0.1
target_port = 8001
**Caution!** Only use the KISS framing option when connecting to external devices
and programs like soundmodems and similar over TCP. When using the
``TCPClientInterface`` in conjunction with the ``TCPServerInterface`` you should
never enable ``kiss_framing``, since this will disable internal reliability and
recovery mechanisms that greatly improves performance over unreliable and
intermittent TCP links.
.. _interfaces-rnode: .. _interfaces-rnode:

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

@ -67,9 +67,12 @@ guide the design of Reticulum:
it can be easily replicated. it can be easily replicated.
* **Very low bandwidth requirements** * **Very low bandwidth requirements**
Reticulum should be able to function reliably over links with a transmission capacity as low Reticulum should be able to function reliably over links with a transmission capacity as low
as *1,000 bps*. as *500 bps*.
* **Encryption by default** * **Encryption by default**
Reticulum must use encryption by default where possible and applicable. Reticulum must use strong encryption by default for all communication.
* **Initiator Anonymity**
It must be possible to communicate over a Reticulum network without revealing any identifying
information about oneself.
* **Unlicensed use** * **Unlicensed use**
Reticulum shall be functional over physical communication mediums that do not require any Reticulum shall be functional over physical communication mediums that do not require any
form of license to use. Reticulum must be designed in a way, so it is usable over ISM radio form of license to use. Reticulum must be designed in a way, so it is usable over ISM radio
@ -99,7 +102,7 @@ Introduction & Basic Functionality
Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s
core a *message oriented* system. It is suited for both local point-to-point or point-to-multipoint core a *message oriented* system. It is suited for both local point-to-point or point-to-multipoint
scenarios where alle nodes are within range of each other, as well as scenarios where packets need scenarios where alle nodes are within range of each other, as well as scenarios where packets need
to be transported over multiple hops to reach the recipient. to be transported over multiple hops in a complex network to reach the recipient.
Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead
Reticulum uses the singular concept of *destinations*. Any application using Reticulum as it’s Reticulum uses the singular concept of *destinations*. Any application using Reticulum as it’s
@ -110,9 +113,9 @@ All destinations in Reticulum are represented internally as 10 bytes, derived fr
SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
will be displayed as 10 bytes in hexadecimal representation, as in the following example: ``<80e29bf7cccaf31431b3>``. will be displayed as 10 bytes in hexadecimal representation, as in the following example: ``<80e29bf7cccaf31431b3>``.
By default Reticulum encrypts all data using public-key cryptography. Any message sent to a By default Reticulum encrypts all data using elliptic curve cryptography. Any packet sent to a
destination is encrypted with that destinations public key. Reticulum can also set up an encrypted destination is encrypted with a derived ephemeral key. Reticulum can also set up an encrypted
channel to a destination with *Perfect Forward Secrecy* and *Initiator Anonymity* using a elliptic channel to a destination with *Forward Secrecy* and *Initiator Anonymity* using a elliptic
curve cryptography and ephemeral keys derived from a Diffie Hellman exchange on Curve25519. In curve cryptography and ephemeral keys derived from a Diffie Hellman exchange on Curve25519. In
Reticulum terminology, this is called a *Link*. Reticulum terminology, this is called a *Link*.
@ -135,17 +138,17 @@ destinations. Reticulum uses three different basic destination types, and one sp
* **Single** * **Single**
The *single* destination type defines a public-key encrypted destination. Any data sent to this The *single* destination type is always identified by a unique public key. Any data sent to this
destination will be encrypted with the destination’s public key, and will only be readable by destination will be encrypted using ephemeral keys derived from an ECDH key exchange, and will
the creator of the destination. only be readable by the creator of the destination, who holds the corresponding private key.
* **Group** * **Group**
The *group* destination type defines a symmetrically encrypted destination. Data sent to this The *group* destination type defines a symmetrically encrypted destination. Data sent to this
destination will be encrypted with a symmetric key, and will be readable by anyone in destination will be encrypted with a symmetric key, and will be readable by anyone in
possession of the key. The *group* destination can be used just as well by only two peers, as it possession of the key.
can by many.
* **Plain** * **Plain**
A *plain* destination type is unencrypted, and suited for traffic that should be broadcast to a A *plain* destination type is unencrypted, and suited for traffic that should be broadcast to a
number of users, or should be readable by anyone. Traffic to a *plain* destination is not encrypted. number of users, or should be readable by anyone. Traffic to a *plain* destination is not encrypted.
Generally, *plain* destinations can be used for broadcast information intended to be public.
* **Link** * **Link**
A *link* is a special destination type, that serves as an abstract channel to a *single* A *link* is a special destination type, that serves as an abstract channel to a *single*
destination, directly connected or over multiple hops. The *link* also offers reliability and destination, directly connected or over multiple hops. The *link* also offers reliability and
@ -507,7 +510,7 @@ the transfer is needed.
This is the purpose of the Reticulum :ref:`Resource<api-resource>`. A *Resource* can automatically This is the purpose of the Reticulum :ref:`Resource<api-resource>`. A *Resource* can automatically
handle the reliable transfer of an arbitrary amount of data over an established :ref:`Link<api-link>`. handle the reliable transfer of an arbitrary amount of data over an established :ref:`Link<api-link>`.
Resources can auto-compress data, will handle breaking the data into individual packets, sequencing Resources can auto-compress data, will handle breaking the data into individual packets, sequencing
the transfer and reassembling the data on the other end. the transfer, integrity verification and reassembling the data on the other end.
:ref:`Resources<api-resource>` are programmatically very simple to use, and only requires a few lines :ref:`Resources<api-resource>` are programmatically very simple to use, and only requires a few lines
of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory, of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
@ -581,6 +584,7 @@ Node Types
Currently Reticulum defines two node types, the *Station* and the *Peer*. A node is a *station* if it fixed Currently Reticulum defines two node types, the *Station* and the *Peer*. A node is a *station* if it fixed
in one place, and if it is intended to be kept online most of the time. Otherwise the node is a *peer*. in one place, and if it is intended to be kept online most of the time. Otherwise the node is a *peer*.
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 connectivity. network will help forward traffic, and what nodes rely on other nodes for connectivity.
@ -596,10 +600,6 @@ Currently, Reticulum is completely priority-agnostic regarding general traffic.
on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission
times and priorities described earlier in this chapter. times and priorities described earlier in this chapter.
It is possible that a prioritisation engine could be added to Reticulum in the future, but in
the light of Reticulums goal of equal access, doing so would need to be the subject of careful
investigation of the consequences first.
.. _understanding-packetformat: .. _understanding-packetformat:

7
docs/manual/gettingstartedfast.html
View File

@ -53,7 +53,7 @@ a look at <a class="reference external" href="https://github.com/markqvist/nomad
provides a complete encrypted communications suite built with Reticulum.</p> provides a complete encrypted communications suite built with Reticulum.</p>
<a class="reference external image-reference" href="_images/nomadnet_3.png"><img alt="_images/nomadnet_3.png" src="_images/nomadnet_3.png" /></a> <a class="reference external image-reference" href="_images/nomadnet_3.png"><img alt="_images/nomadnet_3.png" src="_images/nomadnet_3.png" /></a>
<p><a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a> is a user-facing client <p><a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a> is a user-facing client
in the development for the messaging and information-sharing protocol for the messaging and information-sharing protocol
<a class="reference external" href="https://github.com/markqvist/lxmf">LXMF</a>, another project built with Reticulum.</p> <a class="reference external" href="https://github.com/markqvist/lxmf">LXMF</a>, another project built with Reticulum.</p>
<p>You can install Nomad Network via pip:</p> <p>You can install Nomad Network via pip:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install ...</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Install ...</span>
@ -79,7 +79,8 @@ network status and connectivity.</p>
<h2>Creating a Network With Reticulum<a class="headerlink" href="#creating-a-network-with-reticulum" title="Permalink to this headline"></a></h2> <h2>Creating a Network With Reticulum<a class="headerlink" href="#creating-a-network-with-reticulum" title="Permalink to this headline"></a></h2>
<p>To create a network, you will need to specify one or more <em>interfaces</em> for <p>To create a network, you will need to specify one or more <em>interfaces</em> for
Reticulum to use. This is done in the Reticulum configuration file, which by Reticulum to use. This is done in the Reticulum configuration file, which by
default is located at <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>.</p> default is located at <code class="docutils literal notranslate"><span class="pre">~/.reticulum/config</span></code>. You can edit this file by hand,
or use the interactive <code class="docutils literal notranslate"><span class="pre">rnsconfig</span></code> utility.</p>
<p>When Reticulum is started for the first time, it will create a default <p>When Reticulum is started for the first time, it will create a default
configuration file, with one active interface. This default interface uses configuration file, with one active interface. This default interface uses
your existing ethernet network (if there is one), and only allows you to your existing ethernet network (if there is one), and only allows you to
@ -163,7 +164,7 @@ and a few extra commands are required.</p>
<span class="n">pkg</span> <span class="n">update</span> <span class="n">pkg</span> <span class="n">update</span>
<span class="n">pkg</span> <span class="n">upgrade</span> <span class="n">pkg</span> <span class="n">upgrade</span>
<span class="c1"># Then install dependencies for cryptography library.</span> <span class="c1"># Then install dependencies for the cryptography library.</span>
<span class="n">pkg</span> <span class="n">install</span> <span class="n">python</span> <span class="n">build</span><span class="o">-</span><span class="n">essential</span> <span class="n">openssl</span> <span class="n">libffi</span> <span class="n">rust</span> <span class="n">pkg</span> <span class="n">install</span> <span class="n">python</span> <span class="n">build</span><span class="o">-</span><span class="n">essential</span> <span class="n">openssl</span> <span class="n">libffi</span> <span class="n">rust</span>
<span class="c1"># Make sure pip is up to date, and install the wheel module.</span> <span class="c1"># Make sure pip is up to date, and install the wheel module.</span>

25
docs/manual/interfaces.html
View File

@ -107,6 +107,8 @@ pre-existing LAN.</p>
<span class="c1"># forward_port = 4242</span> <span class="c1"># forward_port = 4242</span>
</pre></div> </pre></div>
</div> </div>
<p><em>Please Note!</em> If you use the <code class="docutils literal notranslate"><span class="pre">device</span></code> option, you will need the Python module
<code class="docutils literal notranslate"><span class="pre">netifaces</span></code> installed on your system. You can install it with <code class="docutils literal notranslate"><span class="pre">pip3</span> <span class="pre">install</span> <span class="pre">netifaces</span></code>.</p>
</div> </div>
<div class="section" id="tcp-server-interface"> <div class="section" id="tcp-server-interface">
<span id="interfaces-tcps"></span><h2>TCP Server Interface<a class="headerlink" href="#tcp-server-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-tcps"></span><h2>TCP Server Interface<a class="headerlink" href="#tcp-server-interface" title="Permalink to this headline"></a></h2>
@ -139,6 +141,8 @@ configured, other Reticulum peers can connect to it with a TCP Client interface.
<span class="c1"># port = 4242</span> <span class="c1"># port = 4242</span>
</pre></div> </pre></div>
</div> </div>
<p><em>Please Note!</em> If you use the <code class="docutils literal notranslate"><span class="pre">device</span></code> option, you will need the Python module
<code class="docutils literal notranslate"><span class="pre">netifaces</span></code> installed on your system. You can install it with <code class="docutils literal notranslate"><span class="pre">pip3</span> <span class="pre">install</span> <span class="pre">netifaces</span></code>.</p>
</div> </div>
<div class="section" id="tcp-client-interface"> <div class="section" id="tcp-client-interface">
<span id="interfaces-tcpc"></span><h2>TCP Client Interface<a class="headerlink" href="#tcp-client-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-tcpc"></span><h2>TCP Client Interface<a class="headerlink" href="#tcp-client-interface" title="Permalink to this headline"></a></h2>
@ -156,6 +160,27 @@ same TCP Server interface at the same time.</p>
<span class="n">target_port</span> <span class="o">=</span> <span class="mi">4242</span> <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4242</span>
</pre></div> </pre></div>
</div> </div>
<p>It is also possible to use this interface type to connect via other programs
or hardware devices that expose a KISS interface on a TCP port, for example
software-based soundmodems. To do this, use the <code class="docutils literal notranslate"><span class="pre">kiss_framing</span></code> option:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here&#39;s an example of a TCP Client interface that connects</span>
<span class="c1"># to a software TNC soundmodem on a KISS over TCP port.</span>
<span class="p">[[</span><span class="n">TCP</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">outgoing</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">kiss_framing</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0</span><span class="o">.</span><span class="mf">0.1</span>
<span class="n">target_port</span> <span class="o">=</span> <span class="mi">8001</span>
</pre></div>
</div>
<p><strong>Caution!</strong> Only use the KISS framing option when connecting to external devices
and programs like soundmodems and similar over TCP. When using the
<code class="docutils literal notranslate"><span class="pre">TCPClientInterface</span></code> in conjunction with the <code class="docutils literal notranslate"><span class="pre">TCPServerInterface</span></code> you should
never enable <code class="docutils literal notranslate"><span class="pre">kiss_framing</span></code>, since this will disable internal reliability and
recovery mechanisms that greatly improves performance over unreliable and
intermittent TCP links.</p>
</div> </div>
<div class="section" id="rnode-lora-interface"> <div class="section" id="rnode-lora-interface">
<span id="interfaces-rnode"></span><h2>RNode LoRa Interface<a class="headerlink" href="#rnode-lora-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-rnode"></span><h2>RNode LoRa Interface<a class="headerlink" href="#rnode-lora-interface" title="Permalink to this headline"></a></h2>

2
docs/manual/searchindex.js
View File

File diff suppressed because one or more lines are too long

39
docs/manual/understanding.html
View File

@ -100,12 +100,18 @@ it can be easily replicated.</p>
</li> </li>
<li><dl class="simple"> <li><dl class="simple">
<dt><strong>Very low bandwidth requirements</strong></dt><dd><p>Reticulum should be able to function reliably over links with a transmission capacity as low <dt><strong>Very low bandwidth requirements</strong></dt><dd><p>Reticulum should be able to function reliably over links with a transmission capacity as low
as <em>1,000 bps</em>.</p> as <em>500 bps</em>.</p>
</dd> </dd>
</dl> </dl>
</li> </li>
<li><dl class="simple"> <li><dl class="simple">
<dt><strong>Encryption by default</strong></dt><dd><p>Reticulum must use encryption by default where possible and applicable.</p> <dt><strong>Encryption by default</strong></dt><dd><p>Reticulum must use strong encryption by default for all communication.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>Initiator Anonymity</strong></dt><dd><p>It must be possible to communicate over a Reticulum network without revealing any identifying
information about oneself.</p>
</dd> </dd>
</dl> </dl>
</li> </li>
@ -148,7 +154,7 @@ needs to be purchased.</p>
<p>Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s <p>Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s
core a <em>message oriented</em> system. It is suited for both local point-to-point or point-to-multipoint core a <em>message oriented</em> system. It is suited for both local point-to-point or point-to-multipoint
scenarios where alle nodes are within range of each other, as well as scenarios where packets need scenarios where alle nodes are within range of each other, as well as scenarios where packets need
to be transported over multiple hops to reach the recipient.</p> to be transported over multiple hops in a complex network to reach the recipient.</p>
<p>Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead <p>Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead
Reticulum uses the singular concept of <em>destinations</em>. Any application using Reticulum as it’s Reticulum uses the singular concept of <em>destinations</em>. Any application using Reticulum as it’s
networking stack will need to create one or more destinations to receive data, and know the networking stack will need to create one or more destinations to receive data, and know the
@ -156,9 +162,9 @@ destinations it needs to send data to.</p>
<p>All destinations in Reticulum are represented internally as 10 bytes, derived from truncating a full <p>All destinations in Reticulum are represented internally as 10 bytes, derived from truncating a full
SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
will be displayed as 10 bytes in hexadecimal representation, as in the following example: <code class="docutils literal notranslate"><span class="pre">&lt;80e29bf7cccaf31431b3&gt;</span></code>.</p> will be displayed as 10 bytes in hexadecimal representation, as in the following example: <code class="docutils literal notranslate"><span class="pre">&lt;80e29bf7cccaf31431b3&gt;</span></code>.</p>
<p>By default Reticulum encrypts all data using public-key cryptography. Any message sent to a <p>By default Reticulum encrypts all data using elliptic curve cryptography. Any packet sent to a
destination is encrypted with that destinations public key. Reticulum can also set up an encrypted destination is encrypted with a derived ephemeral key. Reticulum can also set up an encrypted
channel to a destination with <em>Perfect Forward Secrecy</em> and <em>Initiator Anonymity</em> using a elliptic channel to a destination with <em>Forward Secrecy</em> and <em>Initiator Anonymity</em> using a elliptic
curve cryptography and ephemeral keys derived from a Diffie Hellman exchange on Curve25519. In curve cryptography and ephemeral keys derived from a Diffie Hellman exchange on Curve25519. In
Reticulum terminology, this is called a <em>Link</em>.</p> Reticulum terminology, this is called a <em>Link</em>.</p>
<p>Reticulum also offers symmetric key encryption for group-oriented communications, as well as <p>Reticulum also offers symmetric key encryption for group-oriented communications, as well as
@ -174,23 +180,23 @@ private IP networks.</p>
destinations. Reticulum uses three different basic destination types, and one special:</p> destinations. Reticulum uses three different basic destination types, and one special:</p>
<ul class="simple"> <ul class="simple">
<li><dl class="simple"> <li><dl class="simple">
<dt><strong>Single</strong></dt><dd><p>The <em>single</em> destination type defines a public-key encrypted destination. Any data sent to this <dt><strong>Single</strong></dt><dd><p>The <em>single</em> destination type is always identified by a unique public key. Any data sent to this
destination will be encrypted with the destination’s public key, and will only be readable by destination will be encrypted using ephemeral keys derived from an ECDH key exchange, and will
the creator of the destination.</p> only be readable by the creator of the destination, who holds the corresponding private key.</p>
</dd> </dd>
</dl> </dl>
</li> </li>
<li><dl class="simple"> <li><dl class="simple">
<dt><strong>Group</strong></dt><dd><p>The <em>group</em> destination type defines a symmetrically encrypted destination. Data sent to this <dt><strong>Group</strong></dt><dd><p>The <em>group</em> destination type defines a symmetrically encrypted destination. Data sent to this
destination will be encrypted with a symmetric key, and will be readable by anyone in destination will be encrypted with a symmetric key, and will be readable by anyone in
possession of the key. The <em>group</em> destination can be used just as well by only two peers, as it possession of the key.</p>
can by many.</p>
</dd> </dd>
</dl> </dl>
</li> </li>
<li><dl class="simple"> <li><dl class="simple">
<dt><strong>Plain</strong></dt><dd><p>A <em>plain</em> destination type is unencrypted, and suited for traffic that should be broadcast to a <dt><strong>Plain</strong></dt><dd><p>A <em>plain</em> destination type is unencrypted, and suited for traffic that should be broadcast to a
number of users, or should be readable by anyone. Traffic to a <em>plain</em> destination is not encrypted.</p> number of users, or should be readable by anyone. Traffic to a <em>plain</em> destination is not encrypted.
Generally, <em>plain</em> destinations can be used for broadcast information intended to be public.</p>
</dd> </dd>
</dl> </dl>
</li> </li>
@ -575,7 +581,7 @@ the transfer is needed.</p>
<p>This is the purpose of the Reticulum <a class="reference internal" href="reference.html#api-resource"><span class="std std-ref">Resource</span></a>. A <em>Resource</em> can automatically <p>This is the purpose of the Reticulum <a class="reference internal" href="reference.html#api-resource"><span class="std std-ref">Resource</span></a>. A <em>Resource</em> can automatically
handle the reliable transfer of an arbitrary amount of data over an established <a class="reference internal" href="reference.html#api-link"><span class="std std-ref">Link</span></a>. handle the reliable transfer of an arbitrary amount of data over an established <a class="reference internal" href="reference.html#api-link"><span class="std std-ref">Link</span></a>.
Resources can auto-compress data, will handle breaking the data into individual packets, sequencing Resources can auto-compress data, will handle breaking the data into individual packets, sequencing
the transfer and reassembling the data on the other end.</p> the transfer, integrity verification and reassembling the data on the other end.</p>
<p><a class="reference internal" href="reference.html#api-resource"><span class="std std-ref">Resources</span></a> are programmatically very simple to use, and only requires a few lines <p><a class="reference internal" href="reference.html#api-resource"><span class="std std-ref">Resources</span></a> are programmatically very simple to use, and only requires a few lines
of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory, of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
or stream data directly from files.</p> or stream data directly from files.</p>
@ -654,8 +660,8 @@ treated more as a reference than as essential reading.</p>
<div class="section" id="node-types"> <div class="section" id="node-types">
<h3>Node Types<a class="headerlink" href="#node-types" title="Permalink to this headline"></a></h3> <h3>Node Types<a class="headerlink" href="#node-types" title="Permalink to this headline"></a></h3>
<p>Currently Reticulum defines two node types, the <em>Station</em> and the <em>Peer</em>. A node is a <em>station</em> if it fixed <p>Currently Reticulum defines two node types, the <em>Station</em> and the <em>Peer</em>. A node is a <em>station</em> if it fixed
in one place, and if it is intended to be kept online most of the time. Otherwise the node is a <em>peer</em>. in one place, and if it is intended to be kept online most of the time. Otherwise the node is a <em>peer</em>.</p>
This distinction is made by the user configuring the node, and is used to determine what nodes on the <p>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 connectivity.</p> network will help forward traffic, and what nodes rely on other nodes for connectivity.</p>
<p>If a node is a <em>Peer</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>.</p> <p>If a node is a <em>Peer</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>.</p>
<p>If it is a <em>Station</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>Station</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>
@ -665,9 +671,6 @@ network will help forward traffic, and what nodes rely on other nodes for connec
<p>Currently, Reticulum is completely priority-agnostic regarding general traffic. All traffic is handled <p>Currently, Reticulum is completely priority-agnostic regarding general traffic. All traffic is handled
on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission
times and priorities described earlier in this chapter.</p> times and priorities described earlier in this chapter.</p>
<p>It is possible that a prioritisation engine could be added to Reticulum in the future, but in
the light of Reticulums goal of equal access, doing so would need to be the subject of careful
investigation of the consequences first.</p>
</div> </div>
<div class="section" id="binary-packet-format"> <div class="section" id="binary-packet-format">
<span id="understanding-packetformat"></span><h3>Binary Packet Format<a class="headerlink" href="#binary-packet-format" title="Permalink to this headline"></a></h3> <span id="understanding-packetformat"></span><h3>Binary Packet Format<a class="headerlink" href="#binary-packet-format" title="Permalink to this headline"></a></h3>

7
docs/source/gettingstartedfast.rst
View File

@ -16,7 +16,7 @@ provides a complete encrypted communications suite built with Reticulum.
:target: _images/nomadnet_3.png :target: _images/nomadnet_3.png
`Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client `Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client
in the development for the messaging and information-sharing protocol for the messaging and information-sharing protocol
`LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum. `LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum.
You can install Nomad Network via pip: You can install Nomad Network via pip:
@ -48,7 +48,8 @@ Creating a Network With Reticulum
============================================= =============================================
To create a network, you will need to specify one or more *interfaces* for To create a network, you will need to specify one or more *interfaces* for
Reticulum to use. This is done in the Reticulum configuration file, which by Reticulum to use. This is done in the Reticulum configuration file, which by
default is located at ``~/.reticulum/config``. default is located at ``~/.reticulum/config``. You can edit this file by hand,
or use the interactive ``rnsconfig`` utility.
When Reticulum is started for the first time, it will create a default When Reticulum is started for the first time, it will create a default
configuration file, with one active interface. This default interface uses configuration file, with one active interface. This default interface uses
@ -152,7 +153,7 @@ From within Termux, execute the following:
pkg update pkg update
pkg upgrade pkg upgrade
# Then install dependencies for cryptography library. # Then install dependencies for the cryptography library.
pkg install python build-essential openssl libffi rust pkg install python build-essential openssl libffi rust
# Make sure pip is up to date, and install the wheel module. # Make sure pip is up to date, and install the wheel module.

29
docs/source/interfaces.rst
View File

@ -78,6 +78,9 @@ pre-existing LAN.
# forward_ip = 10.55.0.16 # forward_ip = 10.55.0.16
# forward_port = 4242 # forward_port = 4242
*Please Note!* If you use the ``device`` option, you will need the Python module
``netifaces`` installed on your system. You can install it with ``pip3 install netifaces``.
.. _interfaces-tcps: .. _interfaces-tcps:
TCP Server Interface TCP Server Interface
@ -114,6 +117,8 @@ configured, other Reticulum peers can connect to it with a TCP Client interface.
# device = eth0 # device = eth0
# port = 4242 # port = 4242
*Please Note!* If you use the ``device`` option, you will need the Python module
``netifaces`` installed on your system. You can install it with ``pip3 install netifaces``.
.. _interfaces-tcpc: .. _interfaces-tcpc:
@ -136,6 +141,30 @@ same TCP Server interface at the same time.
target_host = 127.0.0.1 target_host = 127.0.0.1
target_port = 4242 target_port = 4242
It is also possible to use this interface type to connect via other programs
or hardware devices that expose a KISS interface on a TCP port, for example
software-based soundmodems. To do this, use the ``kiss_framing`` option:
.. code::
# Here's an example of a TCP Client interface that connects
# to a software TNC soundmodem on a KISS over TCP port.
[[TCP KISS Interface]]
type = TCPClientInterface
interface_enabled = True
outgoing = True
kiss_framing = True
target_host = 127.0.0.1
target_port = 8001
**Caution!** Only use the KISS framing option when connecting to external devices
and programs like soundmodems and similar over TCP. When using the
``TCPClientInterface`` in conjunction with the ``TCPServerInterface`` you should
never enable ``kiss_framing``, since this will disable internal reliability and
recovery mechanisms that greatly improves performance over unreliable and
intermittent TCP links.
.. _interfaces-rnode: .. _interfaces-rnode:

32
docs/source/understanding.rst
View File

@ -67,9 +67,12 @@ guide the design of Reticulum:
it can be easily replicated. it can be easily replicated.
* **Very low bandwidth requirements** * **Very low bandwidth requirements**
Reticulum should be able to function reliably over links with a transmission capacity as low Reticulum should be able to function reliably over links with a transmission capacity as low
as *1,000 bps*. as *500 bps*.
* **Encryption by default** * **Encryption by default**
Reticulum must use encryption by default where possible and applicable. Reticulum must use strong encryption by default for all communication.
* **Initiator Anonymity**
It must be possible to communicate over a Reticulum network without revealing any identifying
information about oneself.
* **Unlicensed use** * **Unlicensed use**
Reticulum shall be functional over physical communication mediums that do not require any Reticulum shall be functional over physical communication mediums that do not require any
form of license to use. Reticulum must be designed in a way, so it is usable over ISM radio form of license to use. Reticulum must be designed in a way, so it is usable over ISM radio
@ -99,7 +102,7 @@ Introduction & Basic Functionality
Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at it’s
core a *message oriented* system. It is suited for both local point-to-point or point-to-multipoint core a *message oriented* system. It is suited for both local point-to-point or point-to-multipoint
scenarios where alle nodes are within range of each other, as well as scenarios where packets need scenarios where alle nodes are within range of each other, as well as scenarios where packets need
to be transported over multiple hops to reach the recipient. to be transported over multiple hops in a complex network to reach the recipient.
Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead
Reticulum uses the singular concept of *destinations*. Any application using Reticulum as it’s Reticulum uses the singular concept of *destinations*. Any application using Reticulum as it’s
@ -110,9 +113,9 @@ All destinations in Reticulum are represented internally as 10 bytes, derived fr
SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
will be displayed as 10 bytes in hexadecimal representation, as in the following example: ``<80e29bf7cccaf31431b3>``. will be displayed as 10 bytes in hexadecimal representation, as in the following example: ``<80e29bf7cccaf31431b3>``.
By default Reticulum encrypts all data using public-key cryptography. Any message sent to a By default Reticulum encrypts all data using elliptic curve cryptography. Any packet sent to a
destination is encrypted with that destinations public key. Reticulum can also set up an encrypted destination is encrypted with a derived ephemeral key. Reticulum can also set up an encrypted
channel to a destination with *Perfect Forward Secrecy* and *Initiator Anonymity* using a elliptic channel to a destination with *Forward Secrecy* and *Initiator Anonymity* using a elliptic
curve cryptography and ephemeral keys derived from a Diffie Hellman exchange on Curve25519. In curve cryptography and ephemeral keys derived from a Diffie Hellman exchange on Curve25519. In
Reticulum terminology, this is called a *Link*. Reticulum terminology, this is called a *Link*.
@ -135,17 +138,17 @@ destinations. Reticulum uses three different basic destination types, and one sp
* **Single** * **Single**
The *single* destination type defines a public-key encrypted destination. Any data sent to this The *single* destination type is always identified by a unique public key. Any data sent to this
destination will be encrypted with the destination’s public key, and will only be readable by destination will be encrypted using ephemeral keys derived from an ECDH key exchange, and will
the creator of the destination. only be readable by the creator of the destination, who holds the corresponding private key.
* **Group** * **Group**
The *group* destination type defines a symmetrically encrypted destination. Data sent to this The *group* destination type defines a symmetrically encrypted destination. Data sent to this
destination will be encrypted with a symmetric key, and will be readable by anyone in destination will be encrypted with a symmetric key, and will be readable by anyone in
possession of the key. The *group* destination can be used just as well by only two peers, as it possession of the key.
can by many.
* **Plain** * **Plain**
A *plain* destination type is unencrypted, and suited for traffic that should be broadcast to a A *plain* destination type is unencrypted, and suited for traffic that should be broadcast to a
number of users, or should be readable by anyone. Traffic to a *plain* destination is not encrypted. number of users, or should be readable by anyone. Traffic to a *plain* destination is not encrypted.
Generally, *plain* destinations can be used for broadcast information intended to be public.
* **Link** * **Link**
A *link* is a special destination type, that serves as an abstract channel to a *single* A *link* is a special destination type, that serves as an abstract channel to a *single*
destination, directly connected or over multiple hops. The *link* also offers reliability and destination, directly connected or over multiple hops. The *link* also offers reliability and
@ -507,7 +510,7 @@ the transfer is needed.
This is the purpose of the Reticulum :ref:`Resource<api-resource>`. A *Resource* can automatically This is the purpose of the Reticulum :ref:`Resource<api-resource>`. A *Resource* can automatically
handle the reliable transfer of an arbitrary amount of data over an established :ref:`Link<api-link>`. handle the reliable transfer of an arbitrary amount of data over an established :ref:`Link<api-link>`.
Resources can auto-compress data, will handle breaking the data into individual packets, sequencing Resources can auto-compress data, will handle breaking the data into individual packets, sequencing
the transfer and reassembling the data on the other end. the transfer, integrity verification and reassembling the data on the other end.
:ref:`Resources<api-resource>` are programmatically very simple to use, and only requires a few lines :ref:`Resources<api-resource>` are programmatically very simple to use, and only requires a few lines
of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory, of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
@ -581,6 +584,7 @@ Node Types
Currently Reticulum defines two node types, the *Station* and the *Peer*. A node is a *station* if it fixed Currently Reticulum defines two node types, the *Station* and the *Peer*. A node is a *station* if it fixed
in one place, and if it is intended to be kept online most of the time. Otherwise the node is a *peer*. in one place, and if it is intended to be kept online most of the time. Otherwise the node is a *peer*.
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 connectivity. network will help forward traffic, and what nodes rely on other nodes for connectivity.
@ -596,10 +600,6 @@ Currently, Reticulum is completely priority-agnostic regarding general traffic.
on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission
times and priorities described earlier in this chapter. times and priorities described earlier in this chapter.
It is possible that a prioritisation engine could be added to Reticulum in the future, but in
the light of Reticulums goal of equal access, doing so would need to be the subject of careful
investigation of the consequences first.
.. _understanding-packetformat: .. _understanding-packetformat: