Updated documentation

docs/manual/_sources/gettingstartedfast.rst.txt

@@ -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
 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
 ===========================================
 If you want to develop programs that use Reticulum, the easiest way to get

docs/manual/_sources/index.rst.txt

@@ -1,9 +1,9 @@
 ******************************
 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::
    :maxdepth: 3

docs/manual/_sources/understanding.rst.txt

@@ -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
     will randomly generate a new X25519 private/public key pair. It then creates a *link request*
     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
     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
     that is used to encrypt the channel. Information can now be exchanged reliably and securely.
 
+
 It’s 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.
 
@@ -634,4 +640,19 @@ Binary Packet Format
      | | | +------- Packet Type      = DATA
      | | +--------- Destination Type = SINGLE
      | +----------- 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

docs/manual/_sources/whatis.rst.txt

@@ -16,7 +16,7 @@ Reticulum should currently be considered beta software. All core protocol featur
 
 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?
@@ -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
 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
 nothing stopping you from using it over wired ethernet or your local WiFi

docs/manual/gettingstartedfast.html

@@ -52,6 +52,10 @@ scenarios.</p>
 <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
 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 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>

docs/manual/index.html

@@ -39,9 +39,9 @@
             
   <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>
-<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">
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a><ul>

docs/manual/reference.html

@@ -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>
 <dl class="py class">
 <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>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters</dt>
 <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>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>
 </dd>
 </dl>

docs/manual/understanding.html

@@ -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
 will randomly generate a new X25519 private/public key pair. It then creates a <em>link request</em>
 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>
 </li>
 <li><div class="line-block">
@@ -691,6 +696,21 @@ proof           11
  | | +--------- Destination Type = SINGLE
  | +----------- Propagation Type = BROADCAST
  +------------- 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>
 </div>
 </div>

docs/manual/whatis.html

@@ -52,7 +52,7 @@
 </div>
 <div class="section" id="caveat-emptor">
 <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 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>
@@ -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,
 ad-hoc WiFi, free-space optical links and similar systems are all examples
 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 there’s
 nothing stopping you from using it over wired ethernet or your local WiFi
 network, where it’ll work just as well. In fact, one of the strengths of

docs/source/gettingstartedfast.rst

@@ -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
 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
 ===========================================
 If you want to develop programs that use Reticulum, the easiest way to get

docs/source/index.rst

@@ -1,9 +1,9 @@
 ******************************
 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::
    :maxdepth: 3

docs/source/understanding.rst

@@ -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
     will randomly generate a new X25519 private/public key pair. It then creates a *link request*
     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
     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
     that is used to encrypt the channel. Information can now be exchanged reliably and securely.
 
+
 It’s 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.
 
@@ -634,4 +640,19 @@ Binary Packet Format
      | | | +------- Packet Type      = DATA
      | | +--------- Destination Type = SINGLE
      | +----------- 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

docs/source/whatis.rst

@@ -16,7 +16,7 @@ Reticulum should currently be considered beta software. All core protocol featur
 
 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?
@@ -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
 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
 nothing stopping you from using it over wired ethernet or your local WiFi