An Introduction to Network Stamps

The text below is taken more or less verbatim from the new "Protecting Open Networks" chapter of the Reticulum Manual. I wanted to post it here as well, to give an early head-up on how everything works. Release is getting very close now.

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.

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.

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

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.

Also, my percentage head math failed. It's a 0.27% difficulty increase per quantized step, not 0.4%.