Updated documentation

This commit is contained in:
Mark Qvist 2021-05-17 20:01:53 +02:00
parent 94813d95b1
commit 57fc2b090b
20 changed files with 110 additions and 29 deletions

Binary file not shown.

Binary file not shown.

After

Width:  |  Height:  |  Size: 108 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 124 KiB

View File

@ -13,6 +13,13 @@ If you simply want to try using a program built with Reticulum, you can take
a look at `Nomad Network <https://github.com/markqvist/nomadnet>`_, which a look at `Nomad Network <https://github.com/markqvist/nomadnet>`_, which
provides a basic encrypted communications suite built completely on Reticulum. provides a basic encrypted communications suite built completely on Reticulum.
.. image:: screenshots/nomadnet3.png
:target: _images/nomadnet3.png
`Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client
in the development for the messaging and information-sharing protocol
`LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum.
Develop a Program with Reticulum Develop a Program with Reticulum
=========================================== ===========================================
If you want to develop programs that use Reticulum, the easiest way to get If you want to develop programs that use Reticulum, the easiest way to get

View File

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

View File

@ -405,6 +405,11 @@ of hops, where information will be exchanged between two nodes.
* | When a node in the network wants to establish verified connectivity with another node, it * | When a node in the network wants to establish verified connectivity with another node, it
will randomly generate a new X25519 private/public key pair. It then creates a *link request* will randomly generate a new X25519 private/public key pair. It then creates a *link request*
packet, and broadcast it. packet, and broadcast it.
|
| *It should be noted that the X25519 public/private keypair mentioned above is two separate keypairs:
An encryption key pair, used for derivation of a shared symmetric key, and a signing key pair, used
for signing and verifying messages on the link. They are sent together over the wire, and can be
considered as single public key for simplicity in this explanation.*
* | The *link request* is addressed to the destination hash of the desired destination, and * | The *link request* is addressed to the destination hash of the desired destination, and
contains the following data: The newly generated X25519 public key *LKi*. The contents contains the following data: The newly generated X25519 public key *LKi*. The contents
@ -438,6 +443,7 @@ of hops, where information will be exchanged between two nodes.
*link proof* to perform it's own Diffie Hellman Key Exchange and derive the symmetric key *link proof* to perform it's own Diffie Hellman Key Exchange and derive the symmetric key
that is used to encrypt the channel. Information can now be exchanged reliably and securely. that is used to encrypt the channel. Information can now be exchanged reliably and securely.
Its important to note that this methodology ensures that the source of the request does not need to Its important to note that this methodology ensures that the source of the request does not need to
reveal any identifying information about itself. The link initiator remains completely anonymous. reveal any identifying information about itself. The link initiator remains completely anonymous.
@ -634,4 +640,19 @@ Binary Packet Format
| | | +------- Packet Type = DATA | | | +------- Packet Type = DATA
| | +--------- Destination Type = SINGLE | | +--------- Destination Type = SINGLE
| +----------- Propagation Type = BROADCAST | +----------- Propagation Type = BROADCAST
+------------- Header Type = HEADER_1 (two byte header, one address field) +------------- Header Type = HEADER_1 (two byte header, one address field)
Size examples of different packet types
---------------------------------------
The following table lists example sizes of various
packet types. The size listed are the complete on-
wire size including all fields.
- Path Request : 33 bytes
- Announce : 323 bytes
- Link Request : 141 bytes
- Link Proof : 205 bytes
- Link RTT packet : 86 bytes
- Link keepalive : 14 bytes

View File

@ -16,7 +16,7 @@ Reticulum should currently be considered beta software. All core protocol featur
Caveat Emptor Caveat Emptor
============== ==============
Reticulum is experimental software, and should be considered as such. While it has been built with cryptography best-practices very foremost in mind, it has not been externally security audited, and there could very well be privacy-breaking bugs. To be considered secure, Reticulum needs a very thourough security review by independt cryptographers and security researchers. If you want to help out, or help sponsor an audit, please do get in touch. Reticulum is an experimental networking stack, and should be considered as such. While it has been built with cryptography best-practices very foremost in mind, it has not been externally security audited, and there could very well be privacy-breaking bugs. To be considered even remotely secure, Reticulum needs a very thourough security review by independt cryptographers and security researchers. If you want to help out, or help sponsor an audit, please do get in touch.
What does Reticulum Offer? What does Reticulum Offer?
@ -60,10 +60,10 @@ modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes,
ad-hoc WiFi, free-space optical links and similar systems are all examples ad-hoc WiFi, free-space optical links and similar systems are all examples
of the types of interfaces Reticulum was designed for. of the types of interfaces Reticulum was designed for.
An open-source LoRa-based interface called RNode has been designed An open-source LoRa-based interface called `RNode <https://unsigned.io/rnode>`_
specifically for use with Reticulum. It is possible to build yourself, or it has been designed specifically for use with Reticulum. It is possible to build
can be purchased as a complete transceiver that just needs a USB connection yourself, or it can be purchased as a complete transceiver that just needs a
to the host. USB connection to the host.
Reticulum can also be encapsulated over existing IP networks, so there's Reticulum can also be encapsulated over existing IP networks, so there's
nothing stopping you from using it over wired ethernet or your local WiFi nothing stopping you from using it over wired ethernet or your local WiFi

View File

@ -52,6 +52,10 @@ scenarios.</p>
<p>If you simply want to try using a program built with Reticulum, you can take <p>If you simply want to try using a program built with Reticulum, you can take
a look at <a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a>, which a look at <a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a>, which
provides a basic encrypted communications suite built completely on Reticulum.</p> provides a basic encrypted communications suite built completely on Reticulum.</p>
<a class="reference external image-reference" href="_images/nomadnet3.png"><img alt="_images/nomadnet3.png" src="_images/nomadnet3.png" /></a>
<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
<a class="reference external" href="https://github.com/markqvist/lxmf">LXMF</a>, another project built with Reticulum.</p>
</div> </div>
<div class="section" id="develop-a-program-with-reticulum"> <div class="section" id="develop-a-program-with-reticulum">
<h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Permalink to this headline"></a></h2> <h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Permalink to this headline"></a></h2>

View File

@ -39,9 +39,9 @@
<div class="section" id="reticulum-network-stack-manual"> <div class="section" id="reticulum-network-stack-manual">
<h1>Reticulum Network Stack Manual<a class="headerlink" href="#reticulum-network-stack-manual" title="Permalink to this headline"></a></h1> <h1>Reticulum Network Stack Manual<a class="headerlink" href="#reticulum-network-stack-manual" title="Permalink to this headline"></a></h1>
<p>Welcome to the manual for Reticulum. This document aims to provide you <p>This manual aims to provide you with all the information you need to
with all the information you need to understand Reticulum, develop programs understand Reticulum, develop programs using it, or to participate in
using it, or to participate in the development of Reticulum itself.</p> the development of Reticulum itself.</p>
<div class="toctree-wrapper compound"> <div class="toctree-wrapper compound">
<ul> <ul>
<li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a><ul> <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a><ul>

View File

@ -702,14 +702,15 @@ from a the <em>send()</em> method of a <a class="reference internal" href="#api-
<span id="api-link"></span><h3>Link<a class="headerlink" href="#link" title="Permalink to this headline"></a></h3> <span id="api-link"></span><h3>Link<a class="headerlink" href="#link" title="Permalink to this headline"></a></h3>
<dl class="py class"> <dl class="py class">
<dt class="sig sig-object py" id="RNS.Link"> <dt class="sig sig-object py" id="RNS.Link">
<em class="property"><span class="pre">class</span> </em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">Link</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">owner</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">peer_pub_bytes</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Link" title="Permalink to this definition"></a></dt> <em class="property"><span class="pre">class</span> </em><span class="sig-prename descclassname"><span class="pre">RNS.</span></span><span class="sig-name descname"><span class="pre">Link</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">owner</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">peer_pub_bytes</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">peer_sig_pub_bytes</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#RNS.Link" title="Permalink to this definition"></a></dt>
<dd><p>This class.</p> <dd><p>This class.</p>
<dl class="field-list simple"> <dl class="field-list simple">
<dt class="field-odd">Parameters</dt> <dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple"> <dd class="field-odd"><ul class="simple">
<li><p><strong>destination</strong> A <a class="reference internal" href="#api-destination"><span class="std std-ref">RNS.Destination</span></a> instance which to establish a link to.</p></li> <li><p><strong>destination</strong> A <a class="reference internal" href="#api-destination"><span class="std std-ref">RNS.Destination</span></a> instance which to establish a link to.</p></li>
<li><p><strong>owner</strong> Internal use by <a class="reference internal" href="#api-transport"><span class="std std-ref">RNS.Transport</span></a>, ignore this argument.</p></li> <li><p><strong>owner</strong> Internal use by <a class="reference internal" href="#api-transport"><span class="std std-ref">RNS.Transport</span></a>, ignore this argument.</p></li>
<li><p><strong>peer_pub_bytes</strong> Internal use by <a class="reference internal" href="#api-transport"><span class="std std-ref">RNS.Transport</span></a>, ignore this argument.</p></li> <li><p><strong>peer_pub_bytes</strong> Internal use, ignore this argument.</p></li>
<li><p><strong>peer_sig_pub_bytes</strong> Internal use, ignore this argument.</p></li>
</ul> </ul>
</dd> </dd>
</dl> </dl>

File diff suppressed because one or more lines are too long

View File

@ -452,6 +452,11 @@ of hops, where information will be exchanged between two nodes.</p>
<div class="line">When a node in the network wants to establish verified connectivity with another node, it <div class="line">When a node in the network wants to establish verified connectivity with another node, it
will randomly generate a new X25519 private/public key pair. It then creates a <em>link request</em> will randomly generate a new X25519 private/public key pair. It then creates a <em>link request</em>
packet, and broadcast it.</div> packet, and broadcast it.</div>
<div class="line"><br /></div>
<div class="line"><em>It should be noted that the X25519 public/private keypair mentioned above is two separate keypairs:
An encryption key pair, used for derivation of a shared symmetric key, and a signing key pair, used
for signing and verifying messages on the link. They are sent together over the wire, and can be
considered as single public key for simplicity in this explanation.</em></div>
</div> </div>
</li> </li>
<li><div class="line-block"> <li><div class="line-block">
@ -691,6 +696,21 @@ proof 11
| | +--------- Destination Type = SINGLE | | +--------- Destination Type = SINGLE
| +----------- Propagation Type = BROADCAST | +----------- Propagation Type = BROADCAST
+------------- Header Type = HEADER_1 (two byte header, one address field) +------------- Header Type = HEADER_1 (two byte header, one address field)
Size examples of different packet types
---------------------------------------
The following table lists example sizes of various
packet types. The size listed are the complete on-
wire size including all fields.
- Path Request : 33 bytes
- Announce : 323 bytes
- Link Request : 141 bytes
- Link Proof : 205 bytes
- Link RTT packet : 86 bytes
- Link keepalive : 14 bytes
</pre></div> </pre></div>
</div> </div>
</div> </div>

View File

@ -52,7 +52,7 @@
</div> </div>
<div class="section" id="caveat-emptor"> <div class="section" id="caveat-emptor">
<h2>Caveat Emptor<a class="headerlink" href="#caveat-emptor" title="Permalink to this headline"></a></h2> <h2>Caveat Emptor<a class="headerlink" href="#caveat-emptor" title="Permalink to this headline"></a></h2>
<p>Reticulum is experimental software, and should be considered as such. While it has been built with cryptography best-practices very foremost in mind, it has not been externally security audited, and there could very well be privacy-breaking bugs. To be considered secure, Reticulum needs a very thourough security review by independt cryptographers and security researchers. If you want to help out, or help sponsor an audit, please do get in touch.</p> <p>Reticulum is an experimental networking stack, and should be considered as such. While it has been built with cryptography best-practices very foremost in mind, it has not been externally security audited, and there could very well be privacy-breaking bugs. To be considered even remotely secure, Reticulum needs a very thourough security review by independt cryptographers and security researchers. If you want to help out, or help sponsor an audit, please do get in touch.</p>
</div> </div>
<div class="section" id="what-does-reticulum-offer"> <div class="section" id="what-does-reticulum-offer">
<h2>What does Reticulum Offer?<a class="headerlink" href="#what-does-reticulum-offer" title="Permalink to this headline"></a></h2> <h2>What does Reticulum Offer?<a class="headerlink" href="#what-does-reticulum-offer" title="Permalink to this headline"></a></h2>
@ -87,10 +87,10 @@ with 1.000 bits per second throughput, and an MTU of 500 bytes. Data radios,
modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes, modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes,
ad-hoc WiFi, free-space optical links and similar systems are all examples ad-hoc WiFi, free-space optical links and similar systems are all examples
of the types of interfaces Reticulum was designed for.</p> of the types of interfaces Reticulum was designed for.</p>
<p>An open-source LoRa-based interface called RNode has been designed <p>An open-source LoRa-based interface called <a class="reference external" href="https://unsigned.io/rnode">RNode</a>
specifically for use with Reticulum. It is possible to build yourself, or it has been designed specifically for use with Reticulum. It is possible to build
can be purchased as a complete transceiver that just needs a USB connection yourself, or it can be purchased as a complete transceiver that just needs a
to the host.</p> USB connection to the host.</p>
<p>Reticulum can also be encapsulated over existing IP networks, so theres <p>Reticulum can also be encapsulated over existing IP networks, so theres
nothing stopping you from using it over wired ethernet or your local WiFi nothing stopping you from using it over wired ethernet or your local WiFi
network, where itll work just as well. In fact, one of the strengths of network, where itll work just as well. In fact, one of the strengths of

View File

@ -13,6 +13,13 @@ If you simply want to try using a program built with Reticulum, you can take
a look at `Nomad Network <https://github.com/markqvist/nomadnet>`_, which a look at `Nomad Network <https://github.com/markqvist/nomadnet>`_, which
provides a basic encrypted communications suite built completely on Reticulum. provides a basic encrypted communications suite built completely on Reticulum.
.. image:: screenshots/nomadnet3.png
:target: _images/nomadnet3.png
`Nomad Network <https://github.com/markqvist/nomadnet>`_ is a user-facing client
in the development for the messaging and information-sharing protocol
`LXMF <https://github.com/markqvist/lxmf>`_, another project built with Reticulum.
Develop a Program with Reticulum Develop a Program with Reticulum
=========================================== ===========================================
If you want to develop programs that use Reticulum, the easiest way to get If you want to develop programs that use Reticulum, the easiest way to get

View File

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

Binary file not shown.

After

Width:  |  Height:  |  Size: 108 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 118 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 124 KiB

View File

@ -405,6 +405,11 @@ of hops, where information will be exchanged between two nodes.
* | When a node in the network wants to establish verified connectivity with another node, it * | When a node in the network wants to establish verified connectivity with another node, it
will randomly generate a new X25519 private/public key pair. It then creates a *link request* will randomly generate a new X25519 private/public key pair. It then creates a *link request*
packet, and broadcast it. packet, and broadcast it.
|
| *It should be noted that the X25519 public/private keypair mentioned above is two separate keypairs:
An encryption key pair, used for derivation of a shared symmetric key, and a signing key pair, used
for signing and verifying messages on the link. They are sent together over the wire, and can be
considered as single public key for simplicity in this explanation.*
* | The *link request* is addressed to the destination hash of the desired destination, and * | The *link request* is addressed to the destination hash of the desired destination, and
contains the following data: The newly generated X25519 public key *LKi*. The contents contains the following data: The newly generated X25519 public key *LKi*. The contents
@ -438,6 +443,7 @@ of hops, where information will be exchanged between two nodes.
*link proof* to perform it's own Diffie Hellman Key Exchange and derive the symmetric key *link proof* to perform it's own Diffie Hellman Key Exchange and derive the symmetric key
that is used to encrypt the channel. Information can now be exchanged reliably and securely. that is used to encrypt the channel. Information can now be exchanged reliably and securely.
Its important to note that this methodology ensures that the source of the request does not need to Its important to note that this methodology ensures that the source of the request does not need to
reveal any identifying information about itself. The link initiator remains completely anonymous. reveal any identifying information about itself. The link initiator remains completely anonymous.
@ -634,4 +640,19 @@ Binary Packet Format
| | | +------- Packet Type = DATA | | | +------- Packet Type = DATA
| | +--------- Destination Type = SINGLE | | +--------- Destination Type = SINGLE
| +----------- Propagation Type = BROADCAST | +----------- Propagation Type = BROADCAST
+------------- Header Type = HEADER_1 (two byte header, one address field) +------------- Header Type = HEADER_1 (two byte header, one address field)
Size examples of different packet types
---------------------------------------
The following table lists example sizes of various
packet types. The size listed are the complete on-
wire size including all fields.
- Path Request : 33 bytes
- Announce : 323 bytes
- Link Request : 141 bytes
- Link Proof : 205 bytes
- Link RTT packet : 86 bytes
- Link keepalive : 14 bytes

View File

@ -16,7 +16,7 @@ Reticulum should currently be considered beta software. All core protocol featur
Caveat Emptor Caveat Emptor
============== ==============
Reticulum is experimental software, and should be considered as such. While it has been built with cryptography best-practices very foremost in mind, it has not been externally security audited, and there could very well be privacy-breaking bugs. To be considered secure, Reticulum needs a very thourough security review by independt cryptographers and security researchers. If you want to help out, or help sponsor an audit, please do get in touch. Reticulum is an experimental networking stack, and should be considered as such. While it has been built with cryptography best-practices very foremost in mind, it has not been externally security audited, and there could very well be privacy-breaking bugs. To be considered even remotely secure, Reticulum needs a very thourough security review by independt cryptographers and security researchers. If you want to help out, or help sponsor an audit, please do get in touch.
What does Reticulum Offer? What does Reticulum Offer?
@ -60,10 +60,10 @@ modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes,
ad-hoc WiFi, free-space optical links and similar systems are all examples ad-hoc WiFi, free-space optical links and similar systems are all examples
of the types of interfaces Reticulum was designed for. of the types of interfaces Reticulum was designed for.
An open-source LoRa-based interface called RNode has been designed An open-source LoRa-based interface called `RNode <https://unsigned.io/rnode>`_
specifically for use with Reticulum. It is possible to build yourself, or it has been designed specifically for use with Reticulum. It is possible to build
can be purchased as a complete transceiver that just needs a USB connection yourself, or it can be purchased as a complete transceiver that just needs a
to the host. USB connection to the host.
Reticulum can also be encapsulated over existing IP networks, so there's Reticulum can also be encapsulated over existing IP networks, so there's
nothing stopping you from using it over wired ethernet or your local WiFi nothing stopping you from using it over wired ethernet or your local WiFi