mirror of
https://github.com/markqvist/Reticulum.git
synced 2026-11-19 14:36:34 -05:00
251 lines
No EOL
16 KiB
ReStructuredText
251 lines
No EOL
16 KiB
ReStructuredText
************************
|
|
Protecting Open Networks
|
|
************************
|
|
|
|
.. important::
|
|
Reticulum is currently transitioning towards full, on-network stamp verification and enforcement via a phased transition:
|
|
|
|
- The ``1.6.0`` release completely implements the required mechanisms, and will start excercising the verification system in the transport backend. By default, ``1.6.0`` does not enable full stamp generation, emission and enforcement, but all of these options can be early-enabled in the configuration.
|
|
|
|
- The ``1.6.1`` release will enable full stamp generation and emission of all types by default, but will leave the *enforcement* a configurable option.
|
|
|
|
- The ``1.6.2`` release will complete the transition, activating full stamp enforcement across all the systems.
|
|
|
|
The stated version numbers are the *intended* release sequence. If any issues or implementation problems are found during the initial network deployments, the transition points may be pushed later than this plan by interim releases.
|
|
|
|
While you can create entirely closed-off and private networks with Reticulum, the protocol itself is open and permissionless. On widely interconnected networks, anyone can create identities and globally reachable destinations without external permission or approval, and establish links anonymously over the network.
|
|
|
|
Such capabilities are powerful, and a required characteristic of a truly functional communications fabric, but also raise very large challenges, that have been almost impossible to solve in legacy networking technologies.
|
|
|
|
Reticulum approaches this particular problem, like most others, by employing cryptographic principles. This provides a comprehensive, multi-layered repertoire of defense mechanisms, which can be composed and employed in very effective ways.
|
|
|
|
In contrast to other networking paradigms, these mechanisms do not have to be bolted on to the application layer in hindsight, but are a core part of the protocol itself, which means that they can be applied universally and effectively:
|
|
|
|
All nodes help combat spam and network abuse, according to the rules *set by the actual owners of supplied resources* - not by any bureaucracy or external authority.
|
|
|
|
Rules and requirements can be adjusted live, dynamically and directly, and by those that actually operate and run the infrastructure and services.
|
|
|
|
The system has been designed so that it becomes very cheap computationally for resource-providing nodes to verify or reject traffic, and very expensive for malicious nodes to abuse the shared resources provided by the network's operators.
|
|
|
|
|
|
Cryptographic Stamps
|
|
====================
|
|
|
|
All networking primitives that consume shared network resources are gated by *stamps*. A stamp is compact, cryptographic token that proves that a certain amount of computation and energy has been expended in its creation.
|
|
|
|
The amount of such computation required for a stamp to be considered valid can be configured individually by the operator of the resource being made available, whether that is network transport, a node providing information for retrieval, a shared voice room, or something else entirely.
|
|
|
|
While the core functionality is completely automatic, and handled by Reticulum itself, the primitives are made available at the application layer API as well, so that developers can use them to implement further protections, if required by their usage scenarios. In most cases, however, simply setting the target *values* and required *costs* for the built-in mechanisms will be sufficient.
|
|
|
|
The *value* of a stamp is a decimal representation of how difficult a stamp was to create, on a scale from ``0.0`` to ``100.0``. The scale is **exponential**. An increase of one point is equal to *doubling* the average compute time required. Fractional values are supported, such as ``14.125``.
|
|
|
|
Internally, the fractional part is quantized to ``256`` different values, giving an approximately ``0.4%`` difficulty increase per step. You can use any decimal number when configuring stamps, such as ``9.3691`` and you do not have to worry about "landing on" the correct step values. Reticulum will automatically handle the quantization, wire-transport representation and value comparisons.
|
|
|
|
The term *cost* is used everywhere a stamp value *requirement* is configured or specified. In general, *value* refers to the actual, determined value of a given stamp, *cost* refers to a value requirement.
|
|
|
|
Base Primitives
|
|
---------------
|
|
|
|
Reticulum provides two types of base stamp primitives:
|
|
|
|
* **Detached stamps** can be tied to any external information, and are useful for stamping both static information and for one-time verification purposes. The stamp itself is a detached, short binary sequence, typically 14 to 32 bytes, that can be verified directly against the stamped material.
|
|
|
|
They can be configured from relatively easy to compute, even for embbedded systems and microcontrollers, all the way to something that is practically impossible, even with all the compute and memory on the planet.
|
|
|
|
* **Embedded stamps** are tied directly to a Reticulum Identity keyset, and embedded within it. The keyset itself *contains* the stamp, and there is no external, detached byte sequence for them.
|
|
|
|
Anyone can verify the value of an identity-embedded stamp simply from the public key material of the identity.
|
|
|
|
On-Network Types
|
|
----------------
|
|
|
|
The base primitives are used to implement scenario-specific network-level primitives that, if configured correctly, make spam and network abuse expensive, but validation and enforcement cheap and efficient.
|
|
|
|
* **Destination Stamps** are detached stamps associated with reticulum destinations. They are included in all announces sent by a destination, and by verifying that their value matches a transport node's cost requirement, they can be either accepted for rebroadcast onto the network, or rejected and dropped.
|
|
|
|
Destination stamps are *one-time* generations, and are reusable across announces. They limit the number of *new* destinations that can be created, and makes it expensive to spam a network with destinations that do not provide anything meaningful. As such, these stamps will typically target relatively high values, and their cost requirements should be set accordingly.
|
|
|
|
A generation time for such stamps in *minutes* rather than seconds can very well be reasonable on large, open-access networks. Due to their detached nature, they can also be pre-generated off-device (and do not require the private key material for generation), so that even low-powered nodes, such as microcontrollers, can use high-value destination stamps, by having them generated and loaded externally as a one-time procedure.
|
|
|
|
* **Path Request Stamps** are also detached stamps, but generated *individually* for every path request emitted on the network. These will typically have a much lower cost requirement than destination stamps, but if a node is overwhelmed by path requests, it can be tuned higher.
|
|
|
|
The stamp is generated against the individually unique *emission*, so that unstamped or low-value path requests for a destination cannot disrupt the resolution of legitimate ones toward that same destination.
|
|
|
|
* **Link Request Stamps** embedded stamps, carried in the ephemeral link request keyset. They are therefore completely transparent to the network, but can still be verified extremely quickly by any node along the link request path, who can then make a decision on whether or not to transport it.
|
|
|
|
Link request cost targets are set by the *endpoint destinations individually*. Every destination that includes a stamp in its announces will also include link request cost signalling. This means that any node that hears an announce from the destination will also know what link request stamp value to target, when establishing links to that destination.
|
|
|
|
Furthermore, spam and link request abuse can be filtered before even reaching the destination, if at least one node along the path validates the link request stamp value and cost requirement.
|
|
|
|
All of the stamp primitives, functionality and on-wire signalling is *transparent and backwards-compatible* with older versions of Reticulum transport nodes. This means, that even if a node doesn't itself understand stamp functionality, it will still transport all the required information. Stamped announces, path and link requests can cross older, non stamp-aware network segments transparently and unaffected.
|
|
|
|
.. _stamps-configuring:
|
|
|
|
Configuring Stamps
|
|
------------------
|
|
|
|
Reticulum, and its included utilities, provide sane default cost requirements and value targets for the different types of network stamps, but it is entirely up to the operator whether to follow the defaults. All of them are configurable on a per-node, per-application and per-destination basis.
|
|
|
|
Instance Configuration
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
In reality, different kinds of networks will want to configure different kinds of costs and value targets for their use. For instance-wide defaults and settings, you can configure these in the ``[stamps]`` section of the Reticulum configuration file:
|
|
|
|
* | The ``stamp_destinations`` option enables generation and emission
|
|
of destination stamps in announces. This is a transitory option.
|
|
It will become mandatory and enabled by default in RNS ``1.6.1``.
|
|
|
|
* | The ``stamp_prs`` option enables stamping of path requests emitted
|
|
by this instance. This is a transitory option. It will become
|
|
mandatory and enabled by default in RNS ``1.6.1``.
|
|
|
|
* | The ``always_stamp_lrs`` option will stamp *all* outgoing link
|
|
requests, even to destinations that have not announced a link
|
|
request cost (and will, in that case, use the configured or
|
|
default link request cost). This option is mostly useful for
|
|
testing and diagnostics. In general use, Reticulum will handle
|
|
link request stamping and cost targets automatically.
|
|
|
|
* | The ``enforce_stamps`` option allows early activation of stamp
|
|
enforcement. When enabled, announces and path requests that do
|
|
not meet the configured cost requirements are dropped, and link
|
|
requests with insufficient stamps are ignored. This is a transitory
|
|
option. It will become mandatory and enabled by default in RNS
|
|
``1.6.2``.
|
|
|
|
* | The ``destination_cost`` option sets the default required stamp
|
|
cost for announced destinations to be accepted, and have their
|
|
announces propagated by this node. Defaults to ``23.5``.
|
|
|
|
* | The ``destination_value`` option sets the default stamp value that
|
|
this instance will target when generating new destination stamps.
|
|
An application can request higher targets for destinations that it
|
|
creates, but a requested lower value will always be clamped to the
|
|
configured default as a minimum. Defaults to ``25.0``.
|
|
|
|
*Destination stamps are one-time generations per destination, so it
|
|
is generally a good idea to target a slightly higher value than the
|
|
minimum required cost of the networks you want the destination to
|
|
be reachable on.*
|
|
|
|
* | The ``pr_cost`` option sets the required stamp cost for incoming
|
|
path requests. Defaults to ``15.8``.
|
|
|
|
* | The ``pr_value`` option sets the target stamp value for path
|
|
request stamps generated by this instance. Defaults to ``15.8``.
|
|
|
|
* | The ``lr_cost`` option sets the default link request stamp cost,
|
|
that destinations created on this instance will require. This
|
|
value can be freely overridden by applications that specify their
|
|
own link request cost requirements, and is solely used as the
|
|
default if no such specification is provided. Defaults to ``12.5``.
|
|
|
|
* | The ``lr_stamp_timeout`` and ``pr_stamp_timeout`` options set the
|
|
maximum amount of time, in seconds, to spend while attempting to
|
|
generate link and path request stamps respectively. If a stamp is
|
|
not generated within this timespan, the generation is cancelled,
|
|
and the link request or path request fails. Defaults to ``15``
|
|
seconds for both options.
|
|
|
|
An example of customised stamp cost and value configuration follows below:
|
|
|
|
.. code:: ini
|
|
|
|
[stamps]
|
|
stamp_destinations = yes
|
|
stamp_prs = yes
|
|
|
|
destination_cost = 24.8
|
|
destination_value = 26.25
|
|
|
|
pr_cost = 15.8
|
|
pr_value = 16.45
|
|
|
|
Stamp cost requirements can also be configured on a per-interface basis:
|
|
|
|
.. code:: ini
|
|
|
|
[[Public Gateway]]
|
|
type = BackboneInterface
|
|
mode = gateway
|
|
listen_on = 0.0.0.0
|
|
port = 4242
|
|
|
|
destination_cost = 25.0
|
|
pr_cost = 17.2
|
|
|
|
[[Local RNode]]
|
|
type = RNodeInterface
|
|
port = /dev/ttyUSB0
|
|
|
|
# Much lower requirements
|
|
# for the local network.
|
|
destination_cost = 11.2
|
|
pr_cost = 5.0
|
|
|
|
For Developers
|
|
^^^^^^^^^^^^^^
|
|
|
|
Applications can dynamically set their own stamp values and required link requests costs at runtime. Whenever the values are adjusted, the destination will have to send an announce for the updated information to become known by the rest of the network.
|
|
|
|
If you are setting these values at destination creation time, ensure that they are set *immediately* after the destination is instantiated, as Reticulum may queue internal, instance-local announces for the destination shortly after creation, so that the local shared instance and its clients are aware of the newly created destination.
|
|
|
|
.. code:: python
|
|
|
|
# Create a new destination
|
|
my_destination = RNS.Destination(
|
|
my_identity,
|
|
RNS.Destination.IN,
|
|
RNS.Destination.SINGLE,
|
|
"myapp", "service"
|
|
)
|
|
|
|
# Configure stamps
|
|
my_destination.set_value(30.0)
|
|
my_destination.set_link_cost(15.0)
|
|
|
|
Dynamically adjusting link request costs is a viable and intended mechanism for mitigating resource abuse, scraping, DoS attempts and other malicious behaviour. An application may implement mechanisms to statically or dynamically raise link request costs under certain conditions.
|
|
|
|
.. tip::
|
|
Remember here, though, that announce cadence should be preserved for such situations! If your destination is announcing too often in general, and wants to dynamically adjust link request costs at a critical moment, it may already have exhausted its announce rate limits on upstream nodes. So plan your application's announce cadence thoughtfully!
|
|
|
|
It is also possible for application code to directly get the destination value and link request cost for any known destination:
|
|
|
|
.. code:: python
|
|
|
|
# Get the value of a known destination
|
|
RNS.Identity.recall_stamp_value(destination_hash)
|
|
|
|
# Get the current link cost requirement
|
|
# of a known destination
|
|
RNS.Identity.recall_link_cost(destination_hash)
|
|
|
|
|
|
An ``Identity`` can be created with an embedded stamp value, by passing the target value at instantiation time:
|
|
|
|
.. code:: python
|
|
|
|
# Create a new, stamped identity
|
|
my_identity = RNS.Identity(value=24.0)
|
|
|
|
# Get the value of any known identity
|
|
another_identity.get_value()
|
|
|
|
As with destination stamps, this is a one-time generation procedure, that happens at Identity creation. Once an identity is created with an embedded stamp, its value *cannot* be upgraded at a later point as with detached stamps.
|
|
|
|
|
|
Filtering & QoS
|
|
===============
|
|
|
|
TODO: Section explaining the ``[filter]`` configuration options, for creating allow and blocklists for specific destination types.
|
|
|
|
|
|
Blackhole Management
|
|
====================
|
|
|
|
TODO: Section explaining the blackhole system conceptually (including distributed updates from other nodes), with a few terse examples for either locally - or across an entire managed network - blocking specific identities (and therefore any destination types created by such), as well as blocking incoming (identified) link requests from that identity at terminus.
|
|
|
|
Ingress & Burst Control
|
|
=======================
|
|
|
|
TODO: Section explaining the rate-limiting, ingress control and burst limiters conceptually, with a few, terse examples on how to configure them (linked references to other more extensive documentation sections of the options). |