Updated docs and readme

README.md

@@ -42,6 +42,9 @@ For more info, see [reticulum.network](https://reticulum.network/) and [the FAQ
 ## Notable Features
 - Coordination-less globally unique addressing and identification
 - Fully self-configuring multi-hop routing over heterogeneous carriers
+- Flexible scalability over heterogeneous topologies
+  - Reticulum can carry data over any mixture of physical mediums and topologies
+  - Low-bandwidth networks can co-exist and interoperate with large, high-bandwidth networks
 - Initiator anonymity, communicate without revealing your identity
   - Reticulum does not include source addresses on any packets
 - Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication
@@ -54,10 +57,13 @@ For more info, see [reticulum.network](https://reticulum.network/) and [the FAQ
   - IVs are generated through os.urandom()
 - Unforgeable packet delivery confirmations
 - Flexible and extensible interface system
-  - Includes a large variety of built-in interface types
+  - Reticulum includes a large variety of built-in interface types
   - Ability to load and utilise custom user- or community-supplied interface types
   - Easily create your own custom interfaces for communicating over anything
+- Authentication and virtual network segmentation on all supported interface types
 - An intuitive and easy-to-use API
+  - Simpler and easier to use than sockets APIs and simpler, but more powerful
+  - Makes building distributed and decentralised applications much simpler
 - Reliable and efficient transfer of arbitrary amounts of data
   - Reticulum can handle a few bytes of data or files of many gigabytes
   - Sequencing, compression, transfer coordination and checksumming are automatic
@@ -175,11 +181,12 @@ program.
 
 Reticulum implements a range of generalised interface types that covers most of
 the communications hardware that Reticulum can run over. If your hardware is
-not supported, it's relatively simple to implement an interface class. I will
+not supported, it's [simple to implement a custom interface module](https://markqvist.github.io/Reticulum/manual/interfaces.html#custom-interfaces).
-gratefully accept pull requests for custom interfaces if they are generally
-useful.
 
-Currently, the following interfaces are supported:
+Pull requests for custom interfaces are gratefully accepted, provided they are
+generally useful and well-tested in real-world usage.
+
+Currently, the following built-in interfaces are supported:
 
 - Any Ethernet device
 - LoRa using [RNode](https://unsigned.io/rnode/)

docs/manual/_sources/understanding.rst.txt

@@ -868,13 +868,17 @@ both on general-purpose CPUs and on microcontrollers. The necessary primitives a
 
 * HKDF for key derivation
 
-* Modified Fernet for encrypted tokens
+* Encrypted tokens are based on the Fernet spec
 
-  * AES-128 in CBC mode
+  * Ephemeral keys derived from an ECDH key exchange on Curve25519
 
-  * HMAC for message authentication
+  * AES-128 in CBC mode with PKCS7 padding
 
-  * No Version and Timestamp metadata included
+  * HMAC using SHA256 for message authentication
+
+  * IVs are generated through os.urandom()
+
+  * No Fernet version and timestamp metadata fields
 
 * SHA-256
 
@@ -884,12 +888,12 @@ In the default installation configuration, the ``X25519``, ``Ed25519`` and ``AES
 primitives are provided by `OpenSSL <https://www.openssl.org/>`_ (via the `PyCA/cryptography <https://github.com/pyca/cryptography>`_
 package). The hashing functions ``SHA-256`` and ``SHA-512`` are provided by the standard
 Python `hashlib <https://docs.python.org/3/library/hashlib.html>`_. The ``HKDF``, ``HMAC``,
-``Fernet`` primitives, and the ``PKCS7`` padding function are always provided by the
+``Token`` primitives, and the ``PKCS7`` padding function are always provided by the
 following internal implementations:
 
 - ``RNS/Cryptography/HKDF.py``
 - ``RNS/Cryptography/HMAC.py``
-- ``RNS/Cryptography/Fernet.py``
+- ``RNS/Cryptography/Token.py``
 - ``RNS/Cryptography/PKCS7.py``
 
 

docs/manual/_sources/whatis.rst.txt

@@ -43,19 +43,30 @@ considered complete and stable at the moment, but could change if absolutely war
 
 What does Reticulum Offer?
 ==========================
+
 * Coordination-less globally unique addressing and identification
 
-* Fully self-configuring multi-hop routing
+* Fully self-configuring multi-hop routing over heterogeneous carriers
 
-* Complete initiator anonymity, communicate without revealing your identity
+* Flexible scalability over heterogeneous topologies
 
-* Asymmetric encryption based on X25519, and Ed25519 signatures as a basis for all communication
+  * Reticulum can carry data over any mixture of physical mediums and topologies
 
-* Forward Secrecy by using ephemeral Elliptic Curve Diffie-Hellman keys on Curve25519
+  * Low-bandwidth networks can co-exist and interoperate with large, high-bandwidth networks
 
-* Reticulum uses a modified version of the `Fernet <https://github.com/fernet/spec/blob/master/Spec.md>`_ specification for on-the-wire / over-the-air encryption
+* Initiator anonymity, communicate without revealing your identity
 
-  * Keys are ephemeral and derived from an ECDH key exchange on Curve25519
+  * Reticulum does not include source addresses on any packets
+
+* Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication
+
+  * The foundational Reticulum Identity Keys are 512-bit Elliptic Curve keysets
+
+* Forward Secrecy is available for all communication types, both for single packets and over links
+
+* Reticulum uses the following format for encrypted tokens:
+
+  * Ephemeral per-packet and link keys and derived from an ECDH key exchange on Curve25519
 
   * AES-128 in CBC mode with PKCS7 padding
 
@@ -63,13 +74,33 @@ What does Reticulum Offer?
 
   * IVs are generated through os.urandom()
 
-  * No Version and Timestamp metadata included
-
 * Unforgeable packet delivery confirmations
 
-* A variety of supported interface types
+* Flexible and extensible interface system
 
-* An intuitive and developer-friendly API
+  * Reticulum includes a large variety of built-in interface types
+
+  * Ability to load and utilise custom user- or community-supplied interface types
+
+  * Easily create your own custom interfaces for communicating over anything
+
+* Authentication and virtual network segmentation on all supported interface types
+
+* An intuitive and easy-to-use API
+
+  * Simpler and easier to use than sockets APIs and simpler, but more powerful
+
+  * Makes building distributed and decentralised applications much simpler
+
+* Reliable and efficient transfer of arbitrary amounts of data
+
+  * Reticulum can handle a few bytes of data or files of many gigabytes
+
+  * Sequencing, compression, transfer coordination and checksumming are automatic
+
+  * The API is very easy to use, and provides transfer progress
+
+* Lightweight, flexible and expandable Request/Response mechanism
 
 * Efficient link establishment
 
@@ -77,17 +108,7 @@ What does Reticulum Offer?
 
   * Low cost of keeping links open at only 0.44 bits per second
 
-* Reliable and efficient transfer of arbitrary amounts of data
+* Reliable sequential delivery with Channel and Buffer mechanisms
-
-  * Reticulum can handle a few bytes of data or files of many gigabytes
-
-  * Sequencing, transfer coordination and checksumming is automatic
-
-  * The API is very easy to use, and provides transfer progress
-
-* Authentication and virtual network segmentation on all supported interface types
-
-* Flexible scalability allowing extremely low-bandwidth networks to co-exist and interoperate with large, high-bandwidth networks
 
 
 Where can Reticulum be Used?
@@ -118,7 +139,7 @@ network, and vice versa.
 
 Interface Types and Devices
 ===========================
-Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it's relatively simple to implement an interface class. Currently, Reticulum can use the following devices and communication mediums:
+Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it's simple to :ref:`implement an interface class<example-custominterface>`. Currently, Reticulum can use the following devices and communication mediums:
 
 * Any Ethernet device
 

docs/manual/understanding.html

@@ -1069,11 +1069,13 @@ both on general-purpose CPUs and on microcontrollers. The necessary primitives a
 <li><p>Ed25519 for signatures</p></li>
 <li><p>X25519 for ECDH key exchanges</p></li>
 <li><p>HKDF for key derivation</p></li>
-<li><p>Modified Fernet for encrypted tokens</p>
+<li><p>Encrypted tokens are based on the Fernet spec</p>
 <ul>
-<li><p>AES-128 in CBC mode</p></li>
+<li><p>Ephemeral keys derived from an ECDH key exchange on Curve25519</p></li>
-<li><p>HMAC for message authentication</p></li>
+<li><p>AES-128 in CBC mode with PKCS7 padding</p></li>
-<li><p>No Version and Timestamp metadata included</p></li>
+<li><p>HMAC using SHA256 for message authentication</p></li>
+<li><p>IVs are generated through os.urandom()</p></li>
+<li><p>No Fernet version and timestamp metadata fields</p></li>
 </ul>
 </li>
 <li><p>SHA-256</p></li>
@@ -1083,12 +1085,12 @@ both on general-purpose CPUs and on microcontrollers. The necessary primitives a
 primitives are provided by <a class="reference external" href="https://www.openssl.org/">OpenSSL</a> (via the <a class="reference external" href="https://github.com/pyca/cryptography">PyCA/cryptography</a>
 package). The hashing functions <code class="docutils literal notranslate"><span class="pre">SHA-256</span></code> and <code class="docutils literal notranslate"><span class="pre">SHA-512</span></code> are provided by the standard
 Python <a class="reference external" href="https://docs.python.org/3/library/hashlib.html">hashlib</a>. The <code class="docutils literal notranslate"><span class="pre">HKDF</span></code>, <code class="docutils literal notranslate"><span class="pre">HMAC</span></code>,
-<code class="docutils literal notranslate"><span class="pre">Fernet</span></code> primitives, and the <code class="docutils literal notranslate"><span class="pre">PKCS7</span></code> padding function are always provided by the
+<code class="docutils literal notranslate"><span class="pre">Token</span></code> primitives, and the <code class="docutils literal notranslate"><span class="pre">PKCS7</span></code> padding function are always provided by the
 following internal implementations:</p>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">RNS/Cryptography/HKDF.py</span></code></p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">RNS/Cryptography/HMAC.py</span></code></p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">RNS/Cryptography/Fernet.py</span></code></p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">RNS/Cryptography/Token.py</span></code></p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">RNS/Cryptography/PKCS7.py</span></code></p></li>
 </ul>
 <p>Reticulum also includes a complete implementation of all necessary primitives in pure Python.

docs/manual/whatis.html

@@ -258,37 +258,62 @@ considered complete and stable at the moment, but could change if absolutely war
 <h2>What does Reticulum Offer?<a class="headerlink" href="#what-does-reticulum-offer" title="Permalink to this heading">#</a></h2>
 <ul class="simple">
 <li><p>Coordination-less globally unique addressing and identification</p></li>
-<li><p>Fully self-configuring multi-hop routing</p></li>
+<li><p>Fully self-configuring multi-hop routing over heterogeneous carriers</p></li>
-<li><p>Complete initiator anonymity, communicate without revealing your identity</p></li>
+<li><p>Flexible scalability over heterogeneous topologies</p>
-<li><p>Asymmetric encryption based on X25519, and Ed25519 signatures as a basis for all communication</p></li>
-<li><p>Forward Secrecy by using ephemeral Elliptic Curve Diffie-Hellman keys on Curve25519</p></li>
-<li><p>Reticulum uses a modified version of the <a class="reference external" href="https://github.com/fernet/spec/blob/master/Spec.md">Fernet</a> specification for on-the-wire / over-the-air encryption</p>
 <ul>
-<li><p>Keys are ephemeral and derived from an ECDH key exchange on Curve25519</p></li>
+<li><p>Reticulum can carry data over any mixture of physical mediums and topologies</p></li>
+<li><p>Low-bandwidth networks can co-exist and interoperate with large, high-bandwidth networks</p></li>
+</ul>
+</li>
+<li><p>Initiator anonymity, communicate without revealing your identity</p>
+<ul>
+<li><p>Reticulum does not include source addresses on any packets</p></li>
+</ul>
+</li>
+<li><p>Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication</p>
+<ul>
+<li><p>The foundational Reticulum Identity Keys are 512-bit Elliptic Curve keysets</p></li>
+</ul>
+</li>
+<li><p>Forward Secrecy is available for all communication types, both for single packets and over links</p></li>
+<li><p>Reticulum uses the following format for encrypted tokens:</p>
+<ul>
+<li><p>Ephemeral per-packet and link keys and derived from an ECDH key exchange on Curve25519</p></li>
 <li><p>AES-128 in CBC mode with PKCS7 padding</p></li>
 <li><p>HMAC using SHA256 for authentication</p></li>
 <li><p>IVs are generated through os.urandom()</p></li>
-<li><p>No Version and Timestamp metadata included</p></li>
 </ul>
 </li>
 <li><p>Unforgeable packet delivery confirmations</p></li>
-<li><p>A variety of supported interface types</p></li>
+<li><p>Flexible and extensible interface system</p>
-<li><p>An intuitive and developer-friendly API</p></li>
+<ul>
+<li><p>Reticulum includes a large variety of built-in interface types</p></li>
+<li><p>Ability to load and utilise custom user- or community-supplied interface types</p></li>
+<li><p>Easily create your own custom interfaces for communicating over anything</p></li>
+</ul>
+</li>
+<li><p>Authentication and virtual network segmentation on all supported interface types</p></li>
+<li><p>An intuitive and easy-to-use API</p>
+<ul>
+<li><p>Simpler and easier to use than sockets APIs and simpler, but more powerful</p></li>
+<li><p>Makes building distributed and decentralised applications much simpler</p></li>
+</ul>
+</li>
+<li><p>Reliable and efficient transfer of arbitrary amounts of data</p>
+<ul>
+<li><p>Reticulum can handle a few bytes of data or files of many gigabytes</p></li>
+<li><p>Sequencing, compression, transfer coordination and checksumming are automatic</p></li>
+<li><p>The API is very easy to use, and provides transfer progress</p></li>
+</ul>
+</li>
+<li><p>Lightweight, flexible and expandable Request/Response mechanism</p></li>
 <li><p>Efficient link establishment</p>
 <ul>
 <li><p>Total cost of setting up an encrypted and verified link is only 3 packets, totalling 297 bytes</p></li>
 <li><p>Low cost of keeping links open at only 0.44 bits per second</p></li>
 </ul>
 </li>
-<li><p>Reliable and efficient transfer of arbitrary amounts of data</p>
+<li><p>Reliable sequential delivery with Channel and Buffer mechanisms</p></li>
-<ul>
-<li><p>Reticulum can handle a few bytes of data or files of many gigabytes</p></li>
-<li><p>Sequencing, transfer coordination and checksumming is automatic</p></li>
-<li><p>The API is very easy to use, and provides transfer progress</p></li>
-</ul>
-</li>
-<li><p>Authentication and virtual network segmentation on all supported interface types</p></li>
-<li><p>Flexible scalability allowing extremely low-bandwidth networks to co-exist and interoperate with large, high-bandwidth networks</p></li>
 </ul>
 </section>
 <section id="where-can-reticulum-be-used">
@@ -316,7 +341,7 @@ network, and vice versa.</p>
 </section>
 <section id="interface-types-and-devices">
 <h2>Interface Types and Devices<a class="headerlink" href="#interface-types-and-devices" title="Permalink to this heading">#</a></h2>
-<p>Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it’s relatively simple to implement an interface class. Currently, Reticulum can use the following devices and communication mediums:</p>
+<p>Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it’s simple to <a class="reference internal" href="examples.html#example-custominterface"><span class="std std-ref">implement an interface class</span></a>. Currently, Reticulum can use the following devices and communication mediums:</p>
 <ul class="simple">
 <li><p>Any Ethernet device</p>
 <ul>

docs/source/whatis.rst

@@ -43,19 +43,30 @@ considered complete and stable at the moment, but could change if absolutely war
 
 What does Reticulum Offer?
 ==========================
+
 * Coordination-less globally unique addressing and identification
 
-* Fully self-configuring multi-hop routing
+* Fully self-configuring multi-hop routing over heterogeneous carriers
 
-* Complete initiator anonymity, communicate without revealing your identity
+* Flexible scalability over heterogeneous topologies
 
-* Asymmetric encryption based on X25519, and Ed25519 signatures as a basis for all communication
+  * Reticulum can carry data over any mixture of physical mediums and topologies
 
-* Forward Secrecy by using ephemeral Elliptic Curve Diffie-Hellman keys on Curve25519
+  * Low-bandwidth networks can co-exist and interoperate with large, high-bandwidth networks
 
-* Reticulum uses a modified version of the `Fernet <https://github.com/fernet/spec/blob/master/Spec.md>`_ specification for on-the-wire / over-the-air encryption
+* Initiator anonymity, communicate without revealing your identity
 
-  * Keys are ephemeral and derived from an ECDH key exchange on Curve25519
+  * Reticulum does not include source addresses on any packets
+
+* Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication
+
+  * The foundational Reticulum Identity Keys are 512-bit Elliptic Curve keysets
+
+* Forward Secrecy is available for all communication types, both for single packets and over links
+
+* Reticulum uses the following format for encrypted tokens:
+
+  * Ephemeral per-packet and link keys and derived from an ECDH key exchange on Curve25519
 
   * AES-128 in CBC mode with PKCS7 padding
 
@@ -63,13 +74,33 @@ What does Reticulum Offer?
 
   * IVs are generated through os.urandom()
 
-  * No Version and Timestamp metadata included
-
 * Unforgeable packet delivery confirmations
 
-* A variety of supported interface types
+* Flexible and extensible interface system
 
-* An intuitive and developer-friendly API
+  * Reticulum includes a large variety of built-in interface types
+
+  * Ability to load and utilise custom user- or community-supplied interface types
+
+  * Easily create your own custom interfaces for communicating over anything
+
+* Authentication and virtual network segmentation on all supported interface types
+
+* An intuitive and easy-to-use API
+
+  * Simpler and easier to use than sockets APIs and simpler, but more powerful
+
+  * Makes building distributed and decentralised applications much simpler
+
+* Reliable and efficient transfer of arbitrary amounts of data
+
+  * Reticulum can handle a few bytes of data or files of many gigabytes
+
+  * Sequencing, compression, transfer coordination and checksumming are automatic
+
+  * The API is very easy to use, and provides transfer progress
+
+* Lightweight, flexible and expandable Request/Response mechanism
 
 * Efficient link establishment
 
@@ -77,17 +108,7 @@ What does Reticulum Offer?
 
   * Low cost of keeping links open at only 0.44 bits per second
 
-* Reliable and efficient transfer of arbitrary amounts of data
+* Reliable sequential delivery with Channel and Buffer mechanisms
-
-  * Reticulum can handle a few bytes of data or files of many gigabytes
-
-  * Sequencing, transfer coordination and checksumming is automatic
-
-  * The API is very easy to use, and provides transfer progress
-
-* Authentication and virtual network segmentation on all supported interface types
-
-* Flexible scalability allowing extremely low-bandwidth networks to co-exist and interoperate with large, high-bandwidth networks
 
 
 Where can Reticulum be Used?
@@ -118,7 +139,7 @@ network, and vice versa.
 
 Interface Types and Devices
 ===========================
-Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it's relatively simple to implement an interface class. Currently, Reticulum can use the following devices and communication mediums:
+Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, it's simple to :ref:`implement an interface class<example-custominterface>`. Currently, Reticulum can use the following devices and communication mediums:
 
 * Any Ethernet device