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
-gratefully accept pull requests for custom interfaces if they are generally
-useful.
+not supported, it's [simple to implement a custom interface module](https://markqvist.github.io/Reticulum/manual/interfaces.html#custom-interfaces).
 
-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,51 +43,72 @@ 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
+
+* 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
 
-* Complete initiator anonymity, communicate without revealing your identity
+* Asymmetric X25519 encryption and Ed25519 signatures as a basis for all communication
 
-* Asymmetric encryption based on X25519, and Ed25519 signatures as a basis for all communication
+  * The foundational Reticulum Identity Keys are 512-bit Elliptic Curve keysets
 
-* Forward Secrecy by using ephemeral Elliptic Curve Diffie-Hellman keys on Curve25519
+* Forward Secrecy is available for all communication types, both for single packets and over links
 
-* 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
+* Reticulum uses the following format for encrypted tokens:
 
-  * Keys are ephemeral and derived from an ECDH key exchange on Curve25519
+  * Ephemeral per-packet and link keys and derived from an ECDH key exchange on Curve25519
 
   * AES-128 in CBC mode with PKCS7 padding
 
   * HMAC using SHA256 for authentication
 
   * 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
 
-* Efficient link establishment
+  * Ability to load and utilise custom user- or community-supplied interface types
 
-  * Total cost of setting up an encrypted and verified link is only 3 packets, totalling 297 bytes
+  * Easily create your own custom interfaces for communicating over anything
 
-  * Low cost of keeping links open at only 0.44 bits per second
+* 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, transfer coordination and checksumming is automatic
+  * Sequencing, compression, transfer coordination and checksumming are automatic
 
   * The API is very easy to use, and provides transfer progress
 
-* Authentication and virtual network segmentation on all supported interface types
+* Lightweight, flexible and expandable Request/Response mechanism
+
+* Efficient link establishment
+
+  * Total cost of setting up an encrypted and verified link is only 3 packets, totalling 297 bytes
+
+  * Low cost of keeping links open at only 0.44 bits per second
 
-* Flexible scalability allowing extremely low-bandwidth networks to co-exist and interoperate with large, high-bandwidth networks
+* Reliable sequential delivery with Channel and Buffer mechanisms
 
 
 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 @@ <h3>Interface Access Codes<a class="headerlink" href="#interface-access-codes" t
 <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>HMAC for message authentication</p></li>
-<li><p>No Version and Timestamp metadata included</p></li>
+<li><p>Ephemeral keys 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 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 @@ <h3>Interface Access Codes<a class="headerlink" href="#interface-access-codes" t
 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 @@ <h2>Current Status<a class="headerlink" href="#current-status" title="Permalink
 <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>Complete initiator anonymity, communicate without revealing your identity</p></li>
-<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>
+<li><p>Fully self-configuring multi-hop routing over heterogeneous carriers</p></li>
+<li><p>Flexible scalability over heterogeneous topologies</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>An intuitive and developer-friendly API</p></li>
-<li><p>Efficient link establishment</p>
+<li><p>Flexible and extensible interface system</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>
+<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, transfer coordination and checksumming is automatic</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>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>
+<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 sequential delivery with Channel and Buffer mechanisms</p></li>
 </ul>
 </section>
 <section id="where-can-reticulum-be-used">
@@ -316,7 +341,7 @@ <h2>Where can Reticulum be Used?<a class="headerlink" href="#where-can-reticulum
 </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>