15 KiB
Protecting Open Networks
IMPORTANT
Reticulum is currently transitioning towards full, on-network stamp verification and enforcement via a phased transition:
- The
1.6.0release completely implements the required mechanisms, and will start excercising the verification system in the transport backend. By default,1.6.0does not enable full stamp generation, emission and enforcement, but all of these options can be early-enabled in the configuration. - The
1.6.1release will enable full stamp generation and emission of all types by default, but will leave the enforcement a configurable option. - The
1.6.2release 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.
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_destinationsoption enables generation and emission of destination stamps in announces. This is a transitory option. It will become mandatory and enabled by default in RNS1.6.1.The
stamp_prsoption enables stamping of path requests emitted by this instance. This is a transitory option. It will become mandatory and enabled by default in RNS1.6.1.The
always_stamp_lrsoption 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_stampsoption 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 RNS1.6.2.The
destination_costoption sets the default required stamp cost for announced destinations to be accepted, and have their announces propagated by this node. Defaults to23.5.The
destination_valueoption 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 to25.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_costoption sets the required stamp cost for incoming path requests. Defaults to15.8.The
pr_valueoption sets the target stamp value for path request stamps generated by this instance. Defaults to15.8.The
lr_costoption 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 to12.5.The
lr_stamp_timeoutandpr_stamp_timeoutoptions 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 to15seconds for both options.
An example of customised stamp cost and value configuration follows below:
[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:
[[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.
# 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.
It is also possible for application code to directly get the destination value and link request cost for any known destination:
# 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:
# 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).