William/Reticulum
1
0
Fork 0
mirror of https://github.com/markqvist/Reticulum.git synced 2024-11-23 06:00:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updated docs and readme

Browse Source
This commit is contained in:
Mark Qvist 2024-11-22 15:40:41 +01:00
parent aabb763cea
commit 6f8d3e882a
7 changed files with 161 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
README.md
View File

@ -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/)

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

@ -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``

65
docs/manual/_sources/whatis.rst.txt
View File

@ -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
* 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
* 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

2
docs/manual/searchindex.js
View File

File diff suppressed because one or more lines are too long

14
docs/manual/understanding.html
View File

@ -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>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 @@ 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.

63
docs/manual/whatis.html
View File

@ -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>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>Flexible and extensible interface system</p>
<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>
<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>
<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 @@ 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>

65
docs/source/whatis.rst
View File

@ -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
* 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
* 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