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§
- Replay
Filter Config - Configuration of the
TagReplayFilter. - Replay
Shard 🔒 - One generation pair of a shard.
- TagReplay
Filter - 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/SmartDefaultdefault forReplayFilterConfig::max_tracked_packets.- default_
shards 🔒 serde/SmartDefaultdefault forReplayFilterConfig::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_SHARDslots. - validate_
shards 🔒 - Rejects a shard count that is out of range or not a power of two.
Type Aliases§
- Replay
Token - The token a replay filter is keyed on: the packet’s Sphinx authentication tag.