Skip to main content

Module replay_filter

Module replay_filter 

Source
Expand description

Replay detection for incoming HOPR packets.

A packet is replayed when the same wire bytes are delivered twice. Recognising that matters: the alternative is a header MAC verification, a payload permutation and a message parse for every duplicate an attacker cares to send.

The token is the packet’s Sphinx authentication tag, derived from the shared secret with the local node. That secret requires the elliptic-curve Diffie-Hellman, which cannot be avoided - but everything after it can, which is why the tag is handed to the filter from inside the Sphinx decode rather than after it (see HoprPacket::from_incoming_checked).

Keying on the derived tag rather than on the wire alpha matters because the tag depends on the node’s private key. Anybody can compute a tag from a chosen alpha and the node’s public key, so the early TagReplayFilter::contains check is not a proof of anything; what costs an attacker a well-formed packet is getting a token recorded, which TagReplayFilter::commit does only after the header MAC has verified. Rotating the filter out therefore needs packets the sender could actually authenticate, not merely bytes whose first field the attacker chose.

§Why a rolling filter rather than one Bloom filter that resets

A Bloom filter is sized for a fixed number of items and cannot grow. The previous implementation answered overflow by clearing the entire bitmap, which forgets every packet at once. It cleared once per capacity: the insertion that found the filter full of other tags reset it, so the history of all peers was dropped on a single packet.

Instead, each shard keeps two generations. When the current one fills it becomes the previous one and a fresh current is allocated, so a token is remembered for at least one full generation of its shard - a floor that no insertion pattern can take away, where the old design had none. The floor is per shard rather than global: a token’s shard is chosen by a keyed hash and ages out with that shard alone, so the configured count is a bound on total retention only when traffic spreads evenly across shards (see ReplayFilterConfig::max_tracked_packets).

Aging out is proportional to insert volume (a packet count, not wall time). The cost of shortening the window is authenticated packets, not paid ones: a token is committed once the header MAC verifies, which still precedes ticket validation, so a direct neighbour can rotate generations with packets it does not pay for. Each must still authenticate under the shared secret, which costs it the same elliptic-curve work a legitimate sender pays, and the window it shortens is bounded below by one full generation.

The shard a token lands in is chosen by a hash keyed per filter instance, so a sender - who computes the tag - cannot aim its packets at one shard and evict only that shard’s history.

§Why sharded

The filter is consulted by every concurrent decode task. A single mutex serialized them on one cache line; sharding by token hash divides that contention by the shard count without changing the semantics, because the filter is a set either way.

The namespace is deliberately global rather than per previous hop: the token names the packet, not the sender, so a replay injected through a different peer ID is still caught. The cost is that one high-volume peer advances rotations for everyone; that residual is bounded by the generation floor rather than eliminated.

Structs§

ReplayFilterConfig
Configuration of the TagReplayFilter.
ReplayShard 🔒
One generation pair of a shard.
TagReplayFilter
Replay-detecting filter over packet replay tokens.

Constants§

DEFAULT_MAX_TRACKED_PACKETS 🔒
Default for ReplayFilterConfig::max_tracked_packets.
DEFAULT_SHARDS 🔒
Default for ReplayFilterConfig::shards.
GENERATION_FALSE_POSITIVE_RATE 🔒
False-positive rate of a single generation.
MAX_SHARDS
Upper bound on ReplayFilterConfig::shards, enforced by the validator.
MAX_TRACKED_PACKETS
Upper bound on ReplayFilterConfig::max_tracked_packets, enforced by the validator.
MIN_CAPACITY_PER_SHARD
Lower bound on the number of tokens a single shard holds per generation, enforced by the validator.
MIN_SHARDS
Lower bound on ReplayFilterConfig::shards, enforced by the validator.
MIN_TRACKED_PACKETS
Lower bound on ReplayFilterConfig::max_tracked_packets, enforced by the validator.

Functions§

default_max_tracked_packets 🔒
serde/SmartDefault default for ReplayFilterConfig::max_tracked_packets.
default_shards 🔒
serde/SmartDefault default for ReplayFilterConfig::shards.
keyed_hash 🔒
Keyed hash over token, used to pick a shard.
validate_capacity_per_shard 🔒
Rejects a configuration whose capacity does not give every shard MIN_CAPACITY_PER_SHARD slots.
validate_shards 🔒
Rejects a shard count that is out of range or not a power of two.

Type Aliases§

ReplayToken
The token a replay filter is keyed on: the packet’s Sphinx authentication tag.