1209 lines
70 KiB
HTML
1209 lines
70 KiB
HTML
<!doctype html>
|
||
<html class="no-js" lang="en">
|
||
<head><meta charset="utf-8"/>
|
||
<meta name="viewport" content="width=device-width,initial-scale=1"/>
|
||
<meta name="color-scheme" content="light dark"><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
<link rel="index" title="Index" href="genindex.html" /><link rel="search" title="Search" href="search.html" /><link rel="next" title="Communications Hardware" href="hardware.html" /><link rel="prev" title="Using Reticulum on Your System" href="using.html" />
|
||
|
||
<meta name="generator" content="sphinx-5.2.2, furo 2022.09.29"/>
|
||
<title>Understanding Reticulum - Reticulum Network Stack 0.4.9 beta documentation</title>
|
||
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
|
||
<link rel="stylesheet" type="text/css" href="_static/styles/furo.css?digest=d81277517bee4d6b0349d71bb2661d4890b5617c" />
|
||
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
|
||
<link rel="stylesheet" type="text/css" href="_static/styles/furo-extensions.css?digest=30d1aed668e5c3a91c3e3bf6a60b675221979f0e" />
|
||
<link rel="stylesheet" type="text/css" href="_static/custom.css" />
|
||
|
||
|
||
|
||
|
||
<style>
|
||
body {
|
||
--color-code-background: #f8f8f8;
|
||
--color-code-foreground: black;
|
||
|
||
}
|
||
@media not print {
|
||
body[data-theme="dark"] {
|
||
--color-code-background: #202020;
|
||
--color-code-foreground: #d0d0d0;
|
||
--color-background-primary: #202b38;
|
||
--color-background-secondary: #161f27;
|
||
--color-foreground-primary: #dbdbdb;
|
||
--color-foreground-secondary: #a9b1ba;
|
||
--color-brand-primary: #41adff;
|
||
--color-background-hover: #161f27;
|
||
--color-api-name: #ffbe85;
|
||
--color-api-pre-name: #efae75;
|
||
|
||
}
|
||
@media (prefers-color-scheme: dark) {
|
||
body:not([data-theme="light"]) {
|
||
--color-code-background: #202020;
|
||
--color-code-foreground: #d0d0d0;
|
||
--color-background-primary: #202b38;
|
||
--color-background-secondary: #161f27;
|
||
--color-foreground-primary: #dbdbdb;
|
||
--color-foreground-secondary: #a9b1ba;
|
||
--color-brand-primary: #41adff;
|
||
--color-background-hover: #161f27;
|
||
--color-api-name: #ffbe85;
|
||
--color-api-pre-name: #efae75;
|
||
|
||
}
|
||
}
|
||
}
|
||
</style></head>
|
||
<body>
|
||
|
||
<script>
|
||
document.body.dataset.theme = localStorage.getItem("theme") || "auto";
|
||
</script>
|
||
|
||
|
||
<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
|
||
<symbol id="svg-toc" viewBox="0 0 24 24">
|
||
<title>Contents</title>
|
||
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
|
||
<path d="M408 442h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8zm-8 204c0 4.4 3.6 8 8 8h480c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8H408c-4.4 0-8 3.6-8 8v56zm504-486H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zm0 632H120c-4.4 0-8 3.6-8 8v56c0 4.4 3.6 8 8 8h784c4.4 0 8-3.6 8-8v-56c0-4.4-3.6-8-8-8zM115.4 518.9L271.7 642c5.8 4.6 14.4.5 14.4-6.9V388.9c0-7.4-8.5-11.5-14.4-6.9L115.4 505.1a8.74 8.74 0 0 0 0 13.8z"/>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-menu" viewBox="0 0 24 24">
|
||
<title>Menu</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-menu">
|
||
<line x1="3" y1="12" x2="21" y2="12"></line>
|
||
<line x1="3" y1="6" x2="21" y2="6"></line>
|
||
<line x1="3" y1="18" x2="21" y2="18"></line>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-arrow-right" viewBox="0 0 24 24">
|
||
<title>Expand</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather-chevron-right">
|
||
<polyline points="9 18 15 12 9 6"></polyline>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun" viewBox="0 0 24 24">
|
||
<title>Light mode</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="feather-sun">
|
||
<circle cx="12" cy="12" r="5"></circle>
|
||
<line x1="12" y1="1" x2="12" y2="3"></line>
|
||
<line x1="12" y1="21" x2="12" y2="23"></line>
|
||
<line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
|
||
<line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
|
||
<line x1="1" y1="12" x2="3" y2="12"></line>
|
||
<line x1="21" y1="12" x2="23" y2="12"></line>
|
||
<line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
|
||
<line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-moon" viewBox="0 0 24 24">
|
||
<title>Dark mode</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-moon">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
|
||
<path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z" />
|
||
</svg>
|
||
</symbol>
|
||
<symbol id="svg-sun-half" viewBox="0 0 24 24">
|
||
<title>Auto light/dark mode</title>
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor"
|
||
stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" class="icon-tabler-shadow">
|
||
<path stroke="none" d="M0 0h24v24H0z" fill="none"/>
|
||
<circle cx="12" cy="12" r="9" />
|
||
<path d="M13 12h5" />
|
||
<path d="M13 15h4" />
|
||
<path d="M13 18h1" />
|
||
<path d="M13 9h4" />
|
||
<path d="M13 6h1" />
|
||
</svg>
|
||
</symbol>
|
||
</svg>
|
||
|
||
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
|
||
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
|
||
<label class="overlay sidebar-overlay" for="__navigation">
|
||
<div class="visually-hidden">Hide navigation sidebar</div>
|
||
</label>
|
||
<label class="overlay toc-overlay" for="__toc">
|
||
<div class="visually-hidden">Hide table of contents sidebar</div>
|
||
</label>
|
||
|
||
|
||
|
||
<div class="page">
|
||
<header class="mobile-header">
|
||
<div class="header-left">
|
||
<label class="nav-overlay-icon" for="__navigation">
|
||
<div class="visually-hidden">Toggle site navigation sidebar</div>
|
||
<i class="icon"><svg><use href="#svg-menu"></use></svg></i>
|
||
</label>
|
||
</div>
|
||
<div class="header-center">
|
||
<a href="index.html"><div class="brand">Reticulum Network Stack 0.4.9 beta documentation</div></a>
|
||
</div>
|
||
<div class="header-right">
|
||
<div class="theme-toggle-container theme-toggle-header">
|
||
<button class="theme-toggle">
|
||
<div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
|
||
<svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
|
||
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
|
||
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
|
||
</button>
|
||
</div>
|
||
<label class="toc-overlay-icon toc-header-icon" for="__toc">
|
||
<div class="visually-hidden">Toggle table of contents sidebar</div>
|
||
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
|
||
</label>
|
||
</div>
|
||
</header>
|
||
<aside class="sidebar-drawer">
|
||
<div class="sidebar-container">
|
||
|
||
<div class="sidebar-sticky"><a class="sidebar-brand centered" href="index.html">
|
||
|
||
<div class="sidebar-logo-container">
|
||
<img class="sidebar-logo" src="_static/rns_logo_512.png" alt="Logo"/>
|
||
</div>
|
||
|
||
<span class="sidebar-brand-text">Reticulum Network Stack 0.4.9 beta documentation</span>
|
||
|
||
</a><form class="sidebar-search-container" method="get" action="search.html" role="search">
|
||
<input class="sidebar-search" placeholder=Search name="q" aria-label="Search">
|
||
<input type="hidden" name="check_keywords" value="yes">
|
||
<input type="hidden" name="area" value="default">
|
||
</form>
|
||
<div id="searchbox"></div><div class="sidebar-scroll"><div class="sidebar-tree">
|
||
<ul class="current">
|
||
<li class="toctree-l1"><a class="reference internal" href="whatis.html">What is Reticulum?</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="gettingstartedfast.html">Getting Started Fast</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="using.html">Using Reticulum on Your System</a></li>
|
||
<li class="toctree-l1 current current-page"><a class="current reference internal" href="#">Understanding Reticulum</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Communications Hardware</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="interfaces.html">Supported Interfaces</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="networks.html">Building Networks</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Code Examples</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="support.html">Support Reticulum</a></li>
|
||
</ul>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
</aside>
|
||
<div class="main">
|
||
<div class="content">
|
||
<div class="article-container">
|
||
<a href="#" class="back-to-top muted-link">
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
|
||
<path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
|
||
</svg>
|
||
<span>Back to top</span>
|
||
</a>
|
||
<div class="content-icon-container">
|
||
<div class="theme-toggle-container theme-toggle-content">
|
||
<button class="theme-toggle">
|
||
<div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
|
||
<svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
|
||
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
|
||
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
|
||
</button>
|
||
</div>
|
||
<label class="toc-overlay-icon toc-content-icon" for="__toc">
|
||
<div class="visually-hidden">Toggle table of contents sidebar</div>
|
||
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
|
||
</label>
|
||
</div>
|
||
<article role="main">
|
||
<section id="understanding-reticulum">
|
||
<span id="understanding-main"></span><h1>Understanding Reticulum<a class="headerlink" href="#understanding-reticulum" title="Permalink to this heading">#</a></h1>
|
||
<p>This chapter will briefly describe the overall purpose and operating principles of Reticulum.
|
||
It should give you an overview of how the stack works, and an understanding of how to
|
||
develop networked applications using Reticulum.</p>
|
||
<p>This chapter is not an exhaustive source of information on Reticulum, at least not yet. Currently,
|
||
the only complete repository, and final authority on how Reticulum actually functions, is the Python
|
||
reference implementation and API reference. That being said, this chapter is an essential resource in
|
||
understanding how Reticulum works from a high-level perspective, along with the general principles of
|
||
Reticulum, and how to apply them when creating your own networks or software.</p>
|
||
<p>After reading this document, you should be well-equipped to understand how a Reticulum network
|
||
operates, what it can achieve, and how you can use it yourself. If you want to help out with the
|
||
development, this is also the place to start, since it will provide a pretty clear overview of the
|
||
sentiments and the philosophy behind Reticulum, what problems it seeks to solve, and how it
|
||
approaches those solutions.</p>
|
||
<section id="motivation">
|
||
<span id="understanding-motivation"></span><h2>Motivation<a class="headerlink" href="#motivation" title="Permalink to this heading">#</a></h2>
|
||
<p>The primary motivation for designing and implementing Reticulum has been the current lack of
|
||
reliable, functional and secure minimal-infrastructure modes of digital communication. It is my
|
||
belief that it is highly desirable to create a reliable and efficient way to set up long-range digital
|
||
communication networks that can securely allow exchange of information between people and
|
||
machines, with no central point of authority, control, censorship or barrier to entry.</p>
|
||
<p>Almost all of the various networking systems in use today share a common limitation: They
|
||
require large amounts of coordination and centralised trust and power to function. To join such networks, you need approval
|
||
of gatekeepers in control. This need for coordination and trust inevitably leads to an environment of
|
||
central control, where it’s very easy for infrastructure operators or governments to control or alter
|
||
traffic, and censor or persecute unwanted actors. It also makes it completely impossible to freely deploy
|
||
and use networks at will, like one would use other common tools that enhance individual agency and freedom.</p>
|
||
<p>Reticulum aims to require as little coordination and trust as possible. It aims to make secure,
|
||
anonymous and permissionless networking and information exchange a tool that anyone can just pick up and use.</p>
|
||
<p>Since Reticulum is completely medium agnostic, it can be used to build networks on whatever is best
|
||
suited to the situation, or whatever you have available. In some cases, this might be packet radio
|
||
links over VHF frequencies, in other cases it might be a 2.4 GHz
|
||
network using off-the-shelf radios, or it might be using common LoRa development boards.</p>
|
||
<p>At the time of release of this document, the fastest and easiest setup for development and testing is using
|
||
LoRa radio modules with an open source firmware (see the section <a class="reference internal" href="#understanding-referencesystem"><span class="std std-ref">Reference Setup</span></a>),
|
||
connected to any kind of computer or mobile device that Reticulum can run on.</p>
|
||
<p>The ultimate aim of Reticulum is to allow anyone to be their own network operator, and to make it
|
||
cheap and easy to cover vast areas with a myriad of independent, interconnectable and autonomous networks.
|
||
Reticulum <strong>is not</strong> <em>one network</em>, it <strong>is a tool</strong> to build <em>thousands of networks</em>. Networks without
|
||
kill-switches, surveillance, censorship and control. Networks that can freely interoperate, associate and disassociate
|
||
with each other, and require no central oversight. Networks for human beings. <em>Networks for the people</em>.</p>
|
||
</section>
|
||
<section id="goals">
|
||
<span id="understanding-goals"></span><h2>Goals<a class="headerlink" href="#goals" title="Permalink to this heading">#</a></h2>
|
||
<p>To be as widely usable and efficient to deploy as possible, the following goals have been used to
|
||
guide the design of Reticulum:</p>
|
||
<ul class="simple">
|
||
<li><dl class="simple">
|
||
<dt><strong>Fully useable as open source software stack</strong></dt><dd><p>Reticulum must be implemented with, and be able to run using only open source software. This is
|
||
critical to ensuring the availability, security and transparency of the system.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Hardware layer agnosticism</strong></dt><dd><p>Reticulum must be fully hardware agnostic, and shall be useable over a wide range of
|
||
physical networking layers, such as data radios, serial lines, modems, handheld transceivers,
|
||
wired Ethernet, WiFi, or anything else that can carry a digital data stream. Hardware made for
|
||
dedicated Reticulum use shall be as cheap as possible and use off-the-shelf components, so
|
||
it can be easily modified and replicated by anyone interested in doing so.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Very low bandwidth requirements</strong></dt><dd><p>Reticulum should be able to function reliably over links with a transmission capacity as low
|
||
as <em>500 bits per second</em>.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Encryption by default</strong></dt><dd><p>Reticulum must use strong encryption by default for all communication.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Initiator Anonymity</strong></dt><dd><p>It must be possible to communicate over a Reticulum network without revealing any identifying
|
||
information about oneself.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Unlicensed use</strong></dt><dd><p>Reticulum shall be functional over physical communication mediums that do not require any
|
||
form of license to use. Reticulum must be designed in a way, so it is usable over ISM radio
|
||
frequency bands, and can provide functional long distance links in such conditions, for example
|
||
by connecting a modem to a PMR or CB radio, or by using LoRa or WiFi modules.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Supplied software</strong></dt><dd><p>In addition to the core networking stack and API, that allows a developer to build
|
||
applications with Reticulum, a basic set of Reticulum-based communication tools must be
|
||
implemented and released along with Reticulum itself. These shall serve both as a
|
||
functional, basic communication suite, and as an example and learning resource to others wishing
|
||
to build applications with Reticulum.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Ease of use</strong></dt><dd><p>The reference implementation of Reticulum is written in Python, to make it easy to use
|
||
and understand. A programmer with only basic experience should be able to use
|
||
Reticulum to write networked applications.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Low cost</strong></dt><dd><p>It shall be as cheap as possible to deploy a communication system based on Reticulum. This
|
||
should be achieved by using cheap off-the-shelf hardware that potential users might already
|
||
own. The cost of setting up a functioning node should be less than $100 even if all parts
|
||
needs to be purchased.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="introduction-basic-functionality">
|
||
<span id="understanding-basicfunctionality"></span><h2>Introduction & Basic Functionality<a class="headerlink" href="#introduction-basic-functionality" title="Permalink to this heading">#</a></h2>
|
||
<p>Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at its
|
||
core a <em>message oriented</em> system. It is suited for both local point-to-point or point-to-multipoint
|
||
scenarios where all nodes are within range of each other, as well as scenarios where packets need
|
||
to be transported over multiple hops in a complex network to reach the recipient.</p>
|
||
<p>Reticulum does away with the idea of addresses and ports known from IP, TCP and UDP. Instead
|
||
Reticulum uses the singular concept of <em>destinations</em>. Any application using Reticulum as its
|
||
networking stack will need to create one or more destinations to receive data, and know the
|
||
destinations it needs to send data to.</p>
|
||
<p>All destinations in Reticulum are _represented_ as a 16 byte hash. This hash is derived from truncating a full
|
||
SHA-256 hash of identifying characteristics of the destination. To users, the destination addresses
|
||
will be displayed as 16 hexadecimal bytes, like this example: <code class="docutils literal notranslate"><span class="pre"><13425ec15b621c1d928589718000d814></span></code>.</p>
|
||
<p>The truncation size of 16 bytes (128 bits) for destinations has been chosen as a reasonable trade-off
|
||
between address space
|
||
and packet overhead. The address space accommodated by this size can support many billions of
|
||
simultaneously active devices on the same network, while keeping packet overhead low, which is
|
||
essential on low-bandwidth networks. In the very unlikely case that this address space nears
|
||
congestion, a one-line code change can upgrade the Reticulum address space all the way up to 256
|
||
bits, ensuring the Reticulum address space could potentially support galactic-scale networks.
|
||
This is obviously complete and ridiculous over-allocation, and as such, the current 128 bits should
|
||
be sufficient, even far into the future.</p>
|
||
<p>By default Reticulum encrypts all data using elliptic curve cryptography and AES. Any packet sent to a
|
||
destination is encrypted with a per-packet derived key. Reticulum can also set up an encrypted
|
||
channel to a destination, called a <em>Link</em>. Both data sent over Links and single packets offer
|
||
<em>Initiator Anonymity</em>, and links additionally offer <em>Forward Secrecy</em> by using an Elliptic Curve
|
||
Diffie Hellman key exchange on Curve25519 to derive per-link ephemeral keys. The multi-hop transport,
|
||
coordination, verification and reliability layers are fully autonomous and also based on elliptic
|
||
curve cryptography.</p>
|
||
<p>Reticulum also offers symmetric key encryption for group-oriented communications, as well as
|
||
unencrypted packets for local broadcast purposes.</p>
|
||
<p>Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports,
|
||
and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or
|
||
private IP networks.</p>
|
||
<section id="destinations">
|
||
<span id="understanding-destinations"></span><h3>Destinations<a class="headerlink" href="#destinations" title="Permalink to this heading">#</a></h3>
|
||
<p>To receive and send data with the Reticulum stack, an application needs to create one or more
|
||
destinations. Reticulum uses three different basic destination types, and one special:</p>
|
||
<ul class="simple">
|
||
<li><dl class="simple">
|
||
<dt><strong>Single</strong></dt><dd><p>The <em>single</em> destination type is the most common type in Reticulum, and should be used for
|
||
most purposes. It is always identified by a unique public key. Any data sent to this
|
||
destination will be encrypted using ephemeral keys derived from an ECDH key exchange, and will
|
||
only be readable by the creator of the destination, who holds the corresponding private key.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Plain</strong></dt><dd><p>A <em>plain</em> destination type is unencrypted, and suited for traffic that should be broadcast to a
|
||
number of users, or should be readable by anyone. Traffic to a <em>plain</em> destination is not encrypted.
|
||
Generally, <em>plain</em> destinations can be used for broadcast information intended to be public.
|
||
Plain destinations are only reachable directly, and packets addressed to plain destinations are
|
||
never transported over multiple hops in the network. To be transportable over multiple hops in Reticulum, information
|
||
<em>must</em> be encrypted, since Reticulum uses the per-packet encryption to verify routing paths and
|
||
keep them alive.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Group</strong></dt><dd><p>The <em>group</em> special destination type, that defines a symmetrically encrypted virtual destination.
|
||
Data sent to this destination will be encrypted with a symmetric key, and will be readable by
|
||
anyone in possession of the key, but as with the <em>plain</em> destination type, packets to this type
|
||
of destination are not currently transported over multiple hops, although a planned upgrade
|
||
to Reticulum will allow globally reachable <em>group</em> destinations.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Link</strong></dt><dd><p>A <em>link</em> is a special destination type, that serves as an abstract channel to a <em>single</em>
|
||
destination, directly connected or over multiple hops. The <em>link</em> also offers reliability and
|
||
more efficient encryption, forward secrecy, initiator anonymity, and as such can be useful even
|
||
when a node is directly reachable. It also offers a more capable API and allows easily carrying
|
||
out requests and responses, large data transfers and more.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
</ul>
|
||
<section id="destination-naming">
|
||
<span id="understanding-destinationnaming"></span><h4>Destination Naming<a class="headerlink" href="#destination-naming" title="Permalink to this heading">#</a></h4>
|
||
<p>Destinations are created and named in an easy to understand dotted notation of <em>aspects</em>, and
|
||
represented on the network as a hash of this value. The hash is a SHA-256 truncated to 128 bits. The
|
||
top level aspect should always be a unique identifier for the application using the destination.
|
||
The next levels of aspects can be defined in any way by the creator of the application.</p>
|
||
<p>Aspects can be as long and as plentiful as required, and a resulting long destination name will not
|
||
impact efficiency, as names are always represented as truncated SHA-256 hashes on the network.</p>
|
||
<p>As an example, a destination for a environmental monitoring application could be made up of the
|
||
application name, a device type and measurement type, like this:</p>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>app name : environmentlogger
|
||
aspects : remotesensor, temperature
|
||
|
||
full name : environmentlogger.remotesensor.temperature
|
||
hash : 4faf1b2e0a077e6a9d92fa051f256038
|
||
</pre></div>
|
||
</div>
|
||
<p>For the <em>single</em> destination, Reticulum will automatically append the associated public key as a
|
||
destination aspect before hashing. This is done to ensure only the correct destination is reached,
|
||
since anyone can listen to any destination name. Appending the public key ensures that a given
|
||
packet is only directed at the destination that holds the corresponding private key to decrypt the
|
||
packet.</p>
|
||
<p><strong>Take note!</strong> There is a very important concept to understand here:</p>
|
||
<ul class="simple">
|
||
<li><p>Anyone can use the destination name <code class="docutils literal notranslate"><span class="pre">environmentlogger.remotesensor.temperature</span></code></p></li>
|
||
<li><p>Each destination that does so will still have a unique destination hash, and thus be uniquely
|
||
addressable, because their public keys will differ.</p></li>
|
||
</ul>
|
||
<p>In actual use of <em>single</em> destination naming, it is advisable not to use any uniquely identifying
|
||
features in aspect naming. Aspect names should be general terms describing what kind of destination
|
||
is represented. The uniquely identifying aspect is always achieved by appending the public key,
|
||
which expands the destination into a uniquely identifiable one. Reticulum does this automatically.</p>
|
||
<p>Any destination on a Reticulum network can be addressed and reached simply by knowing its
|
||
destination hash (and public key, but if the public key is not known, it can be requested from the
|
||
network simply by knowing the destination hash). The use of app names and aspects makes it easy to
|
||
structure Reticulum programs and makes it possible to filter what information and data your program
|
||
receives.</p>
|
||
<p>To recap, the different destination types should be used in the following situations:</p>
|
||
<ul class="simple">
|
||
<li><dl class="simple">
|
||
<dt><strong>Single</strong></dt><dd><p>When private communication between two endpoints is needed. Supports multiple hops.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Group</strong></dt><dd><p>When private communication between two or more endpoints is needed. Supports multiple hops
|
||
indirectly, but must first be established through a <em>single</em> destination.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Plain</strong></dt><dd><p>When plain-text communication is desirable, for example when broadcasting information, or for local discovery purposes.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
</ul>
|
||
<p>To communicate with a <em>single</em> destination, you need to know its public key. Any method for
|
||
obtaining the public key is valid, but Reticulum includes a simple mechanism for making other
|
||
nodes aware of your destinations public key, called the <em>announce</em>. It is also possible to request
|
||
an unknown public key from the network, as all transport instances serve as a distributed ledger
|
||
of public keys.</p>
|
||
<p>Note that public key information can be shared and verified in other ways than using the
|
||
built-in <em>announce</em> functionality, and that it is therefore not required to use the <em>announce</em> and <em>path request</em>
|
||
functionality to obtain public keys. It is by far the easiest though, and should definitely be used
|
||
if there is not a very good reason for doing it differently.</p>
|
||
</section>
|
||
</section>
|
||
<section id="public-key-announcements">
|
||
<span id="understanding-keyannouncements"></span><h3>Public Key Announcements<a class="headerlink" href="#public-key-announcements" title="Permalink to this heading">#</a></h3>
|
||
<p>An <em>announce</em> will send a special packet over any relevant interfaces, containing all needed
|
||
information about the destination hash and public key, and can also contain some additional,
|
||
application specific data. The entire packet is signed by the sender to ensure authenticity. It is not
|
||
required to use the announce functionality, but in many cases it will be the simplest way to share
|
||
public keys on the network. The announce mechanism also serves to establish end-to-end connectivity
|
||
to the announced destination, as the announce propagates through the network.</p>
|
||
<p>As an example, an announce in a simple messenger application might contain the following information:</p>
|
||
<ul class="simple">
|
||
<li><p>The announcers destination hash</p></li>
|
||
<li><p>The announcers public key</p></li>
|
||
<li><p>Application specific data, in this case the users nickname and availability status</p></li>
|
||
<li><p>A random blob, making each new announce unique</p></li>
|
||
<li><p>An Ed25519 signature of the above information, verifying authenticity</p></li>
|
||
</ul>
|
||
<p>With this information, any Reticulum node that receives it will be able to reconstruct an outgoing
|
||
destination to securely communicate with that destination. You might have noticed that there is one
|
||
piece of information lacking to reconstruct full knowledge of the announced destination, and that is
|
||
the aspect names of the destination. These are intentionally left out to save bandwidth, since they
|
||
will be implicit in almost all cases. The receiving application will already know them. If a destination
|
||
name is not entirely implicit, information can be included in the application specific data part that
|
||
will allow the receiver to infer the naming.</p>
|
||
<p>It is important to note that announces will be forwarded throughout the network according to a
|
||
certain pattern. This will be detailed in the section
|
||
<a class="reference internal" href="#understanding-announce"><span class="std std-ref">The Announce Mechanism in Detail</span></a>.</p>
|
||
<p>In Reticulum, destinations are allowed to move around the network at will. This is very different from
|
||
protocols such as IP, where an address is always expected to stay within the network segment it was assigned in.
|
||
This limitation does not exist in Reticulum, and any destination is <em>completely portable</em> over the entire topography
|
||
of the network, and <em>can even be moved to other Reticulum networks</em> than the one it was created in, and
|
||
still become reachable. To update its reachability, a destination simply needs to send an announce on any
|
||
networks it is part of. After a short while, it will be globally reachable in the network.</p>
|
||
<p>Seeing how <em>single</em> destinations are always tied to a private/public key pair leads us to the next topic.</p>
|
||
</section>
|
||
<section id="understanding-identities">
|
||
<span id="identities"></span><h3>Identities<a class="headerlink" href="#understanding-identities" title="Permalink to this heading">#</a></h3>
|
||
<p>In Reticulum, an <em>identity</em> does not necessarily represent a personal identity, but is an abstraction that
|
||
can represent any kind of <em>verifiable entity</em>. This could very well be a person, but it could also be the
|
||
control interface of a machine, a program, robot, computer, sensor or something else entirely. In
|
||
general, any kind of agent that can act, or be acted upon, or store or manipulate information, can be
|
||
represented as an identity. An <em>identity</em> can be used to create any number of destinations.</p>
|
||
<p>A <em>single</em> destination will always have an <em>identity</em> tied to it, but not <em>plain</em> or <em>group</em>
|
||
destinations. Destinations and identities share a multilateral connection. You can create a
|
||
destination, and if it is not connected to an identity upon creation, it will just create a new one to use
|
||
automatically. This may be desirable in some situations, but often you will probably want to create
|
||
the identity first, and then use it to create new destinations.</p>
|
||
<p>As an example, we could use an identity to represent the user of a messaging application.
|
||
Destinations can then be created by this identity to allow communication to reach the user.
|
||
In all cases it is of great importance to store the private keys associated with any
|
||
Reticulum Identity securely and privately, since obtaining access to the identity keys equals
|
||
obtaining access and controlling reachability to any destinations created by that identity.</p>
|
||
</section>
|
||
<section id="getting-further">
|
||
<span id="understanding-gettingfurther"></span><h3>Getting Further<a class="headerlink" href="#getting-further" title="Permalink to this heading">#</a></h3>
|
||
<p>The above functions and principles form the core of Reticulum, and would suffice to create
|
||
functional networked applications in local clusters, for example over radio links where all interested
|
||
nodes can directly hear each other. But to be truly useful, we need a way to direct traffic over multiple
|
||
hops in the network.</p>
|
||
<p>In the following sections, two concepts that allow this will be introduced, <em>paths</em> and <em>links</em>.</p>
|
||
</section>
|
||
</section>
|
||
<section id="reticulum-transport">
|
||
<span id="understanding-transport"></span><h2>Reticulum Transport<a class="headerlink" href="#reticulum-transport" title="Permalink to this heading">#</a></h2>
|
||
<p>The methods of routing used in traditional networks are fundamentally incompatible with the physical medium
|
||
types and circumstances that Reticulum was designed to handle. These mechanisms mostly assume trust at the physical layer,
|
||
and often needs a lot more bandwidth than Reticulum can assume is available. Since Reticulum is designed to
|
||
survive running over open radio spectrum, no such trust can be assumed, and bandwidth is often very limited.</p>
|
||
<p>To overcome such challenges, Reticulum’s <em>Transport</em> system uses asymmetric elliptic curve cryptography to
|
||
implement the concept of <em>paths</em> that allow discovery of how to get information closer to a certain
|
||
destination. It is important to note that no single node in a Reticulum network knows the complete
|
||
path to a destination. Every Transport node participating in a Reticulum network will only
|
||
know the most direct way to get a packet one hop closer to it’s destination.</p>
|
||
<section id="node-types">
|
||
<span id="understanding-nodetypes"></span><h3>Node Types<a class="headerlink" href="#node-types" title="Permalink to this heading">#</a></h3>
|
||
<p>Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network
|
||
are <em>Reticulum Instances</em>, and some are also <em>Transport Nodes</em>. If a system running Reticulum is fixed in
|
||
one place, and is intended to be kept available most of the time, it is a good contender to be a <em>Transport Node</em>.</p>
|
||
<p>Any Reticulum Instance can become a Transport Node by enabling it in the configuration.
|
||
This distinction is made by the user configuring the node, and is used to determine what nodes on the
|
||
network will help forward traffic, and what nodes rely on other nodes for wider connectivity.</p>
|
||
<p>If a node is an <em>Instance</em> it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">No</span></code>, which
|
||
is the default setting.</p>
|
||
<p>If it is a <em>Transport Node</em>, it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">Yes</span></code>.</p>
|
||
</section>
|
||
<section id="the-announce-mechanism-in-detail">
|
||
<span id="understanding-announce"></span><h3>The Announce Mechanism in Detail<a class="headerlink" href="#the-announce-mechanism-in-detail" title="Permalink to this heading">#</a></h3>
|
||
<p>When an <em>announce</em> for a destination is transmitted by a Reticulum instance, it will be forwarded by
|
||
any transport node receiving it, but according to some specific rules:</p>
|
||
<ul>
|
||
<li><div class="line-block">
|
||
<div class="line">If this exact announce has already been received before, ignore it.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">If not, record into a table which Transport Node the announce was received from, and how many times in
|
||
total it has been retransmitted to get here.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">If the announce has been retransmitted <em>m+1</em> times, it will not be forwarded any more. By default, <em>m</em> is
|
||
set to 128.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">After a randomised delay, the announce will be retransmitted on all interfaces that have bandwidth
|
||
available for processing announces. By default, the maximum bandwidth allocation for processing
|
||
announces is set at 2%, but can be configured on a per-interface basis.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">If any given interface does not have enough bandwidth available for retransmitting the announce,
|
||
the announce will be assigned a priority inversely proportional to its hop count, and be inserted
|
||
into a queue managed by the interface.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">When the interface has bandwidth available for processing an announce, it will prioritise announces
|
||
for destinations that are closest in terms of hops, thus prioritising reachability and connectivity
|
||
of local nodes, even on slow networks that connect to wider and faster networks.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">After the announce has been re-transmitted, and if no other nodes are heard retransmitting the announce
|
||
with a greater hop count than when it left this node, transmitting it will be retried <em>r</em> times. By default,
|
||
<em>r</em> is set to 1.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">If a newer announce from the same destination arrives, while an identical one is already waiting
|
||
to be transmitted, the newest announce is discarded. If the newest announce contains different
|
||
application specific data, it will replace the old announce.</div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p>Once an announce has reached a node in the network, any other node in direct contact with that
|
||
node will be able to reach the destination the announce originated from, simply by sending a packet
|
||
addressed to that destination. Any node with knowledge of the announce will be able to direct the
|
||
packet towards the destination by looking up the next node with the shortest amount of hops to the
|
||
destination.</p>
|
||
<p>According to these rules, an announce will propagate throughout the network in a predictable way,
|
||
and make the announced destination reachable in a short amount of time. Fast networks that have the
|
||
capacity to process many announces can reach full convergence very quickly, even when constantly adding
|
||
new destinations. Slower segments of such networks might take a bit longer to gain full knowledge about
|
||
the wide and fast networks they are connected to, but can still do so over time, while prioritising full
|
||
and quickly converging end-to-end connectivity for their local, slower segments.</p>
|
||
<p>In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full
|
||
end-to-end connectivity in about one minute, given there is enough bandwidth available to process
|
||
the required amount of announces.</p>
|
||
</section>
|
||
<section id="reaching-the-destination">
|
||
<span id="understanding-paths"></span><h3>Reaching the Destination<a class="headerlink" href="#reaching-the-destination" title="Permalink to this heading">#</a></h3>
|
||
<p>In networks with changing topology and trustless connectivity, nodes need a way to establish
|
||
<em>verified connectivity</em> with each other. Since the network is assumed to be trustless, Reticulum
|
||
must provide a way to guarantee that the peer you are communicating with is actually who you
|
||
expect. Reticulum offers two ways to do this.</p>
|
||
<p>For exchanges of small amounts of information, Reticulum offers the <em>Packet</em> API, which works exactly like you would expect - on a per packet level. The following process is employed when sending a packet:</p>
|
||
<ul>
|
||
<li><div class="line-block">
|
||
<div class="line">A packet is always created with an associated destination and some payload data. When the packet is sent
|
||
to a <em>single</em> destination type, Reticulum will automatically create an ephemeral encryption key, perform
|
||
an ECDH key exchange with the destination’s public key, and encrypt the information.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">It is important to note that this key exchange does not require any network traffic. The sender already
|
||
knows the public key of the destination from an earlier received <em>announce</em>, and can thus perform the ECDH
|
||
key exchange locally, before sending the packet.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">The public part of the newly generated ephemeral key-pair is included with the encrypted token, and sent
|
||
along with the encrypted payload data in the packet.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">When the destination receives the packet, it can itself perform an ECDH key exchange and decrypt the
|
||
packet.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">A new ephemeral key is used for every packet sent in this way.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">Once the packet has been received and decrypted by the addressed destination, that destination can opt
|
||
to <em>prove</em> its receipt of the packet. It does this by calculating the SHA-256 hash of the received packet,
|
||
and signing this hash with its Ed25519 signing key. Transport nodes in the network can then direct this
|
||
<em>proof</em> back to the packets origin, where the signature can be verified against the destination’s known
|
||
public signing key.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">In case the packet is addressed to a <em>group</em> destination type, the packet will be encrypted with the
|
||
pre-shared AES-128 key associated with the destination. In case the packet is addressed to a <em>plain</em>
|
||
destination type, the payload data will not be encrypted. Neither of these two destination types can offer
|
||
forward secrecy. In general, it is recommended to always use the <em>single</em> destination type, unless it is
|
||
strictly necessary to use one of the others.</div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p>For exchanges of larger amounts of data, or when longer sessions of bidirectional communication is desired, Reticulum offers the <em>Link</em> API. To establish a <em>link</em>, the following process is employed:</p>
|
||
<ul>
|
||
<li><div class="line-block">
|
||
<div class="line">First, the node that wishes to establish a link will send out a special packet, that
|
||
traverses the network and locates the desired destination. Along the way, the Transport Nodes that
|
||
forward the packet will take note of this <em>link request</em>.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">Second, if the destination accepts the <em>link request</em> , it will send back a packet that proves the
|
||
authenticity of its identity (and the receipt of the link request) to the initiating node. All
|
||
nodes that initially forwarded the packet will also be able to verify this proof, and thus
|
||
accept the validity of the <em>link</em> throughout the network.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">When the validity of the <em>link</em> has been accepted by forwarding nodes, these nodes will
|
||
remember the <em>link</em> , and it can subsequently be used by referring to a hash representing it.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">As a part of the <em>link request</em>, an Elliptic Curve Diffie-Hellman key exchange takes place, that sets up an
|
||
efficiently encrypted tunnel between the two nodes. As such, this mode of communication is preferred,
|
||
even for situations when nodes can directly communicate, when the amount of data to be exchanged numbers
|
||
in the tens of packets, or whenever the use of the more advanced API functions is desired.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">When a <em>link</em> has been set up, it automatically provides message receipt functionality, through
|
||
the same <em>proof</em> mechanism discussed before, so the sending node can obtain verified confirmation
|
||
that the information reached the intended recipient.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">Once the <em>link</em> has been set up, the initiator can remain anonymous, or choose to authenticate towards
|
||
the destination using a Reticulum Identity. This authentication is happening inside the encrypted
|
||
link, and is only revealed to the verified destination, and no intermediaries.</div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p>In a moment, we will discuss the details of how this methodology is
|
||
implemented, but let’s first recap what purposes this methodology serves. We
|
||
first ensure that the node answering our request is actually the one we want to
|
||
communicate with, and not a malicious actor pretending to be so. At the same
|
||
time we establish an efficient encrypted channel. The setup of this is
|
||
relatively cheap in terms of bandwidth, so it can be used just for a short
|
||
exchange, and then recreated as needed, which will also rotate encryption keys.
|
||
The link can also be kept alive for longer periods of time, if this is more
|
||
suitable to the application. The procedure also inserts the <em>link id</em> , a hash
|
||
calculated from the link request packet, into the memory of forwarding nodes,
|
||
which means that the communicating nodes can thereafter reach each other simply
|
||
by referring to this <em>link id</em>.</p>
|
||
<p>The combined bandwidth cost of setting up a link is 3 packets totalling 297 bytes (more info in the
|
||
<a class="reference internal" href="#understanding-packetformat"><span class="std std-ref">Binary Packet Format</span></a> section). The amount of bandwidth used on keeping
|
||
a link open is practically negligible, at 0.45 bits per second. Even on a slow 1200 bits per second packet
|
||
radio channel, 100 concurrent links will still leave 96% channel capacity for actual data.</p>
|
||
<section id="link-establishment-in-detail">
|
||
<h4>Link Establishment in Detail<a class="headerlink" href="#link-establishment-in-detail" title="Permalink to this heading">#</a></h4>
|
||
<p>After exploring the basics of the announce mechanism, finding a path through the network, and an overview
|
||
of the link establishment procedure, this section will go into greater detail about the Reticulum link
|
||
establishment process.</p>
|
||
<p>The <em>link</em> in Reticulum terminology should not be viewed as a direct node-to-node link on the
|
||
physical layer, but as an abstract channel, that can be open for any amount of time, and can span
|
||
an arbitrary number of hops, where information will be exchanged between two nodes.</p>
|
||
<ul>
|
||
<li><div class="line-block">
|
||
<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">
|
||
<div class="line">The <em>link request</em> is addressed to the destination hash of the desired destination, and
|
||
contains the following data: The newly generated X25519 public key <em>LKi</em>.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">The broadcasted packet will be directed through the network according to the rules laid out
|
||
previously.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">Any node that forwards the link request will store a <em>link id</em> in it’s <em>link table</em> , along with the
|
||
amount of hops the packet had taken when received. The link id is a hash of the entire link
|
||
request packet. If the link request packet is not <em>proven</em> by the addressed destination within some
|
||
set amount of time, the entry will be dropped from the <em>link table</em> again.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">When the destination receives the link request packet, it will decide whether to accept the request.
|
||
If it is accepted, the destination will also generate a new X25519 private/public key pair, and
|
||
perform a Diffie Hellman Key Exchange, deriving a new symmetric key that will be used to encrypt the
|
||
channel, once it has been established.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">A <em>link proof</em> packet is now constructed and transmitted over the network. This packet is
|
||
addressed to the <em>link id</em> of the <em>link</em>. It contains the following data: The newly generated X25519
|
||
public key <em>LKr</em> and an Ed25519 signature of the <em>link id</em> and <em>LKr</em> made by the <em>original signing key</em> of
|
||
the addressed destination.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">By verifying this <em>link proof</em> packet, all nodes that originally transported the <em>link request</em>
|
||
packet to the destination from the originator can now verify that the intended destination received
|
||
the request and accepted it, and that the path they chose for forwarding the request was valid.
|
||
In successfully carrying out this verification, the transporting nodes marks the link as active.
|
||
An abstract bi-directional communication channel has now been established along a path in the network.
|
||
Packets can now be exchanged bi-directionally from either end of the link simply by adressing the
|
||
packets to the <em>link id</em> of the link.</div>
|
||
</div>
|
||
</li>
|
||
<li><div class="line-block">
|
||
<div class="line">When the source receives the <em>proof</em> , it will know unequivocally that a verified path has been
|
||
established to the destination. It can now also use the X25519 public key contained in the
|
||
<em>link proof</em> 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.</div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p>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.</p>
|
||
<p>When using <em>links</em>, Reticulum will automatically verify all data sent over the link, and can also
|
||
automate retransmissions if <em>Resources</em> are used.</p>
|
||
</section>
|
||
</section>
|
||
<section id="resources">
|
||
<span id="understanding-resources"></span><h3>Resources<a class="headerlink" href="#resources" title="Permalink to this heading">#</a></h3>
|
||
<p>For exchanging small amounts of data over a Reticulum network, the <a class="reference internal" href="reference.html#api-packet"><span class="std std-ref">Packet</span></a> interface
|
||
is sufficient, but for exchanging data that would require many packets, an efficient way to coordinate
|
||
the transfer is needed.</p>
|
||
<p>This is the purpose of the Reticulum <a class="reference internal" href="reference.html#api-resource"><span class="std std-ref">Resource</span></a>. A <em>Resource</em> can automatically
|
||
handle the reliable transfer of an arbitrary amount of data over an established <a class="reference internal" href="reference.html#api-link"><span class="std std-ref">Link</span></a>.
|
||
Resources can auto-compress data, will handle breaking the data into individual packets, sequencing
|
||
the transfer, integrity verification and reassembling the data on the other end.</p>
|
||
<p><a class="reference internal" href="reference.html#api-resource"><span class="std std-ref">Resources</span></a> are programmatically very simple to use, and only requires a few lines
|
||
of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
|
||
or stream data directly from files.</p>
|
||
</section>
|
||
</section>
|
||
<section id="reference-setup">
|
||
<span id="understanding-referencesystem"></span><h2>Reference Setup<a class="headerlink" href="#reference-setup" title="Permalink to this heading">#</a></h2>
|
||
<p>This section will detail a recommended <em>Reference Setup</em> for Reticulum. It is important to
|
||
note that Reticulum is designed to be usable on more or less any computing device, and over more
|
||
or less any medium that allows you to send and receive data, which satisfies some very low
|
||
minimum requirements.</p>
|
||
<p>The communication channel must support at least half-duplex operation, and provide an average
|
||
throughput of around 500 bits per second, and supports a physical layer MTU of 500 bytes. The
|
||
Reticulum stack should be able to run on more or less any hardware that can provide a Python 3.x
|
||
runtime environment.</p>
|
||
<p>That being said, this reference setup has been outlined to provide a common platform for anyone
|
||
who wants to help in the development of Reticulum, and for everyone who wants to know a
|
||
recommended setup to get started experimenting. A reference system consists of three parts:</p>
|
||
<ul class="simple">
|
||
<li><dl class="simple">
|
||
<dt><strong>An Interface Device</strong></dt><dd><p>Which provides access to the physical medium whereupon the communication
|
||
takes place, for example a radio with an integrated modem. A setup with a separate modem
|
||
connected to a radio would also be an interface device.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>A Host Device</strong></dt><dd><p>Some sort of computing device that can run the necessary software, communicate with the
|
||
interface device, and provide user interaction.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>A Software Stack</strong></dt><dd><p>The software implementing the Reticulum protocol and applications using it.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
</ul>
|
||
<p>The reference setup can be considered a relatively stable platform to develop on, and also to start
|
||
building networks or applications on. While details of the implementation might change at the current stage of
|
||
development, it is the goal to maintain hardware compatibility for as long as entirely possible, and
|
||
the current reference setup has been determined to provide a functional platform for many years
|
||
into the future. The current Reference System Setup is as follows:</p>
|
||
<ul class="simple">
|
||
<li><dl class="simple">
|
||
<dt><strong>Interface Device</strong></dt><dd><p>A data radio consisting of a LoRa radio module, and a microcontroller with open source
|
||
firmware, that can connect to host devices via USB. It operates in either the 430, 868 or 900
|
||
MHz frequency bands. More details can be found on the <a class="reference external" href="https://unsigned.io/rnode">RNode Page</a>.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Host Device</strong></dt><dd><p>Any computer device running Linux and Python. A Raspberry Pi with a Debian based OS is
|
||
recommended.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
<li><dl class="simple">
|
||
<dt><strong>Software Stack</strong></dt><dd><p>The most recently released Python Implementation of Reticulum, running on a Debian based
|
||
operating system.</p>
|
||
</dd>
|
||
</dl>
|
||
</li>
|
||
</ul>
|
||
<p>To avoid confusion, it is very important to note, that the reference interface device <strong>does not</strong>
|
||
use the LoRaWAN standard, but uses a custom MAC layer on top of the plain LoRa modulation! As such, you will
|
||
need a plain LoRa radio module connected to an controller with the correct firmware. Full details on how to
|
||
get or make such a device is available on the <a class="reference external" href="https://unsigned.io/rnode">RNode Page</a>.</p>
|
||
<p>With the current reference setup, it should be possible to get on a Reticulum network for around 100$
|
||
even if you have none of the hardware already, and need to purchase everything.</p>
|
||
<p>This reference setup is of course just a recommendation for getting started easily, and you should
|
||
tailor it to your own specific needs, or whatever hardware you have available.</p>
|
||
</section>
|
||
<section id="protocol-specifics">
|
||
<span id="understanding-protocolspecifics"></span><h2>Protocol Specifics<a class="headerlink" href="#protocol-specifics" title="Permalink to this heading">#</a></h2>
|
||
<p>This chapter will detail protocol specific information that is essential to the implementation of
|
||
Reticulum, but non critical in understanding how the protocol works on a general level. It should be
|
||
treated more as a reference than as essential reading.</p>
|
||
<section id="packet-prioritisation">
|
||
<h3>Packet Prioritisation<a class="headerlink" href="#packet-prioritisation" title="Permalink to this heading">#</a></h3>
|
||
<p>Currently, Reticulum is completely priority-agnostic regarding general traffic. All traffic is handled
|
||
on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission
|
||
times and priorities described earlier in this chapter.</p>
|
||
</section>
|
||
<section id="interface-access-codes">
|
||
<h3>Interface Access Codes<a class="headerlink" href="#interface-access-codes" title="Permalink to this heading">#</a></h3>
|
||
<p>Reticulum can create named virtual networks, and networks that are only accessible by knowing a preshared
|
||
passphrase. The configuration of this is detailed in the <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">Common Interface Options</span></a>
|
||
section. To implement these feature, Reticulum uses the concept of Interface Access Codes, that are calculated
|
||
and verified per packet.</p>
|
||
<p>An interface with a named virtual network or passphrase authentication enabled will derive a shared Ed25519
|
||
signing identity, and for every outbound packet generate a signature of the entire packet. This signature is
|
||
then inserted into the packet as an Interface Access Code before transmission. Depending on the speed and
|
||
capabilities of the interface, the IFAC can be the full 512-bit Ed25519 signature, or a truncated version.
|
||
Configured IFAC length can be inspected for all interfaces with the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility.</p>
|
||
<p>Upon receipt, the interface will check that the signature matches the expected value, and drop the packet if it
|
||
does not. This ensures that only packets sent with the correct naming and/or passphrase parameters are allowed to
|
||
pass onto the network.</p>
|
||
</section>
|
||
<section id="wire-format">
|
||
<span id="understanding-packetformat"></span><h3>Wire Format<a class="headerlink" href="#wire-format" title="Permalink to this heading">#</a></h3>
|
||
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>== Reticulum Wire Format ======
|
||
|
||
A Reticulum packet is composed of the following fields:
|
||
|
||
[HEADER 2 bytes] [ADDRESSES 16/32 bytes] [CONTEXT 1 byte] [DATA 0-465 bytes]
|
||
|
||
* The HEADER field is 2 bytes long.
|
||
* Byte 1: [IFAC Flag], [Header Type], [Propagation Type], [Destination Type] and [Packet Type]
|
||
* Byte 2: Number of hops
|
||
|
||
* Interface Access Code field if the IFAC flag was set.
|
||
* The length of the Interface Access Code can vary from
|
||
1 to 64 bytes according to physical interface
|
||
capabilities and configuration.
|
||
|
||
* The ADDRESSES field contains either 1 or 2 addresses.
|
||
* Each address is 16 bytes long.
|
||
* The Header Type flag in the HEADER field determines
|
||
whether the ADDRESSES field contains 1 or 2 addresses.
|
||
* Addresses are SHA-256 hashes truncated to 16 bytes.
|
||
|
||
* The CONTEXT field is 1 byte.
|
||
* It is used by Reticulum to determine packet context.
|
||
|
||
* The DATA field is between 0 and 465 bytes.
|
||
* It contains the packets data payload.
|
||
|
||
IFAC Flag
|
||
-----------------
|
||
open 0 Packet for publically accessible interface
|
||
authenticated 1 Interface authentication is included in packet
|
||
|
||
|
||
Header Types
|
||
-----------------
|
||
type 1 0 Two byte header, one 16 byte address field
|
||
type 2 1 Two byte header, two 16 byte address fields
|
||
|
||
|
||
Propagation Types
|
||
-----------------
|
||
broadcast 00
|
||
transport 01
|
||
reserved 10
|
||
reserved 11
|
||
|
||
|
||
Destination Types
|
||
-----------------
|
||
single 00
|
||
group 01
|
||
plain 10
|
||
link 11
|
||
|
||
|
||
Packet Types
|
||
-----------------
|
||
data 00
|
||
announce 01
|
||
link request 10
|
||
proof 11
|
||
|
||
|
||
+- Packet Example -+
|
||
|
||
HEADER FIELD DESTINATION FIELDS CONTEXT FIELD DATA FIELD
|
||
_______|_______ ________________|________________ ________|______ __|_
|
||
| | | | | | | |
|
||
01010000 00000100 [HASH1, 16 bytes] [HASH2, 16 bytes] [CONTEXT, 1 byte] [DATA]
|
||
|| | | | |
|
||
|| | | | +-- Hops = 4
|
||
|| | | +------- Packet Type = DATA
|
||
|| | +--------- Destination Type = SINGLE
|
||
|| +----------- Propagation Type = TRANSPORT
|
||
|+------------- Header Type = HEADER_2 (two byte header, two address fields)
|
||
+-------------- Access Codes = DISABLED
|
||
|
||
|
||
+- Packet Example -+
|
||
|
||
HEADER FIELD DESTINATION FIELD CONTEXT FIELD DATA FIELD
|
||
_______|_______ _______|_______ ________|______ __|_
|
||
| | | | | | | |
|
||
00000000 00000111 [HASH1, 16 bytes] [CONTEXT, 1 byte] [DATA]
|
||
|| | | | |
|
||
|| | | | +-- Hops = 7
|
||
|| | | +------- Packet Type = DATA
|
||
|| | +--------- Destination Type = SINGLE
|
||
|| +----------- Propagation Type = BROADCAST
|
||
|+------------- Header Type = HEADER_1 (two byte header, one address field)
|
||
+-------------- Access Codes = DISABLED
|
||
|
||
|
||
+- Packet Example -+
|
||
|
||
HEADER FIELD IFAC FIELD DESTINATION FIELD CONTEXT FIELD DATA FIELD
|
||
_______|_______ ______|______ _______|_______ ________|______ __|_
|
||
| | | | | | | | | |
|
||
10000000 00000111 [IFAC, N bytes] [HASH1, 16 bytes] [CONTEXT, 1 byte] [DATA]
|
||
|| | | | |
|
||
|| | | | +-- Hops = 7
|
||
|| | | +------- Packet Type = DATA
|
||
|| | +--------- Destination Type = SINGLE
|
||
|| +----------- Propagation Type = BROADCAST
|
||
|+------------- Header Type = HEADER_1 (two byte header, one address field)
|
||
+-------------- Access Codes = ENABLED
|
||
|
||
|
||
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 counting all fields including headers,
|
||
but excluding any interface access codes.
|
||
|
||
- Path Request : 51 bytes
|
||
- Announce : 167 bytes
|
||
- Link Request : 83 bytes
|
||
- Link Proof : 115 bytes
|
||
- Link RTT packet : 99 bytes
|
||
- Link keepalive : 20 bytes
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="announce-propagation-rules">
|
||
<span id="understanding-announcepropagation"></span><h3>Announce Propagation Rules<a class="headerlink" href="#announce-propagation-rules" title="Permalink to this heading">#</a></h3>
|
||
<p>The following table illustrates the rules for automatically propagating announces
|
||
from one interface type to another, for all possible combinations. For the purpose
|
||
of announce propagation, the <em>Full</em> and <em>Gateway</em> modes are identical.</p>
|
||
<img alt="_images/if_mode_graph_b.png" src="_images/if_mode_graph_b.png" />
|
||
<p>See the <a class="reference internal" href="interfaces.html#interfaces-modes"><span class="std std-ref">Interface Modes</span></a> section for a conceptual overview
|
||
of the different interface modes, and how they are configured.</p>
|
||
</section>
|
||
<section id="cryptographic-primitives">
|
||
<span id="understanding-primitives"></span><h3>Cryptographic Primitives<a class="headerlink" href="#cryptographic-primitives" title="Permalink to this heading">#</a></h3>
|
||
<p>Reticulum has been designed to use a simple suite of efficient, strong and modern
|
||
cryptographic primitives, with widely available implementations that can be used
|
||
both on general-purpose CPUs and on microcontrollers. The necessary primitives are:</p>
|
||
<ul class="simple">
|
||
<li><p>Ed25519 for signatures</p></li>
|
||
<li><p>X22519 for ECDH key exchanges</p></li>
|
||
<li><p>HKDF for key derivation</p></li>
|
||
<li><p>Fernet for encrypted tokens</p>
|
||
<ul>
|
||
<li><p>AES-128 in CBC mode</p></li>
|
||
<li><p>HMAC for message authentication</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p>SHA-256</p></li>
|
||
<li><p>SHA-512</p></li>
|
||
</ul>
|
||
<p>In the default installation configuration, the <code class="docutils literal notranslate"><span class="pre">X25519</span></code>, <code class="docutils literal notranslate"><span class="pre">Ed25519</span></code> and <code class="docutils literal notranslate"><span class="pre">AES-128-CBC</span></code>
|
||
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
|
||
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/PKCS7.py</span></code></p></li>
|
||
</ul>
|
||
<p>Reticulum also includes a complete implementation of all necessary primitives in pure Python.
|
||
If OpenSSL & PyCA are not available on the system when Reticulum is started, Reticulum will
|
||
instead use the internal pure-python primitives. A trivial consequence of this is performance,
|
||
with the OpenSSL backend being <em>much</em> faster. The most important consequence however, is the
|
||
potential loss of security by using primitives that has not seen the same amount of scrutiny,
|
||
testing and review as those from OpenSSL.</p>
|
||
<p>If you want to use the internal pure-python primitives, it is <strong>highly advisable</strong> that you
|
||
have a good understanding of the risks that this pose, and make an informed decision on whether
|
||
those risks are acceptable to you.</p>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
</article>
|
||
</div>
|
||
<footer>
|
||
|
||
<div class="related-pages">
|
||
<a class="next-page" href="hardware.html">
|
||
<div class="page-info">
|
||
<div class="context">
|
||
<span>Next</span>
|
||
</div>
|
||
<div class="title">Communications Hardware</div>
|
||
</div>
|
||
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
|
||
</a>
|
||
<a class="prev-page" href="using.html">
|
||
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
|
||
<div class="page-info">
|
||
<div class="context">
|
||
<span>Previous</span>
|
||
</div>
|
||
|
||
<div class="title">Using Reticulum on Your System</div>
|
||
|
||
</div>
|
||
</a>
|
||
</div>
|
||
<div class="bottom-of-page">
|
||
<div class="left-details">
|
||
<div class="copyright">
|
||
Copyright © 2023, Mark Qvist
|
||
</div>
|
||
Generated with <a href="https://www.sphinx-doc.org/">Sphinx</a> and
|
||
<a href="https://github.com/pradyunsg/furo">Furo</a>
|
||
|
||
</div>
|
||
<div class="right-details">
|
||
<div class="icons">
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
</footer>
|
||
</div>
|
||
<aside class="toc-drawer">
|
||
|
||
|
||
<div class="toc-sticky toc-scroll">
|
||
<div class="toc-title-container">
|
||
<span class="toc-title">
|
||
On this page
|
||
</span>
|
||
</div>
|
||
<div class="toc-tree-container">
|
||
<div class="toc-tree">
|
||
<ul>
|
||
<li><a class="reference internal" href="#">Understanding Reticulum</a><ul>
|
||
<li><a class="reference internal" href="#motivation">Motivation</a></li>
|
||
<li><a class="reference internal" href="#goals">Goals</a></li>
|
||
<li><a class="reference internal" href="#introduction-basic-functionality">Introduction & Basic Functionality</a><ul>
|
||
<li><a class="reference internal" href="#destinations">Destinations</a><ul>
|
||
<li><a class="reference internal" href="#destination-naming">Destination Naming</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#public-key-announcements">Public Key Announcements</a></li>
|
||
<li><a class="reference internal" href="#understanding-identities">Identities</a></li>
|
||
<li><a class="reference internal" href="#getting-further">Getting Further</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#reticulum-transport">Reticulum Transport</a><ul>
|
||
<li><a class="reference internal" href="#node-types">Node Types</a></li>
|
||
<li><a class="reference internal" href="#the-announce-mechanism-in-detail">The Announce Mechanism in Detail</a></li>
|
||
<li><a class="reference internal" href="#reaching-the-destination">Reaching the Destination</a><ul>
|
||
<li><a class="reference internal" href="#link-establishment-in-detail">Link Establishment in Detail</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#resources">Resources</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#reference-setup">Reference Setup</a></li>
|
||
<li><a class="reference internal" href="#protocol-specifics">Protocol Specifics</a><ul>
|
||
<li><a class="reference internal" href="#packet-prioritisation">Packet Prioritisation</a></li>
|
||
<li><a class="reference internal" href="#interface-access-codes">Interface Access Codes</a></li>
|
||
<li><a class="reference internal" href="#wire-format">Wire Format</a></li>
|
||
<li><a class="reference internal" href="#announce-propagation-rules">Announce Propagation Rules</a></li>
|
||
<li><a class="reference internal" href="#cryptographic-primitives">Cryptographic Primitives</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</aside>
|
||
</div>
|
||
</div><script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
|
||
<script src="_static/jquery.js"></script>
|
||
<script src="_static/underscore.js"></script>
|
||
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
|
||
<script src="_static/doctools.js"></script>
|
||
<script src="_static/sphinx_highlight.js"></script>
|
||
<script src="_static/scripts/furo.js"></script>
|
||
<script src="_static/clipboard.min.js"></script>
|
||
<script src="_static/copybutton.js"></script>
|
||
</body>
|
||
</html> |